Skip to content

Add Markdown parser support (.md, .markdown) #145

@josephismikhail

Description

@josephismikhail

Problem

Ix does not currently parse .md or .markdown files. Markdown files are treated as
unrecognized and excluded from analysis, meaning documentation, API references, guides,
and developer-facing content are invisible to the system.

Proposed solution

Add a Markdown parser that can identify and extract:

  • Heading entities at all levels (h1–h6), including ATX (#) and setext (===, ---) syntax
  • Heading hierarchy as CONTAINS relationships (file → h1 → h2 → h3)
  • Section chunks scoped to each heading
  • YAML frontmatter blocks
  • VitePress/docusaurus anchor syntax (e.g. ## Heading {#anchor-id}) cleaned from entity names

Support the following file patterns: *.md, *.markdown

Why it matters

Markdown is the standard format for documentation in software projects — READMEs, API
references, changelogs, guides, and architecture docs are almost universally written in
it. Without parsing Markdown, Ix cannot reason about a project's documentation layer,
answer questions grounded in written specs, or surface relationships between docs and
the code they describe. This is especially relevant for documentation-heavy repos like
Vue, React, and other OSS projects where .md files are a primary artifact.

Merge requirements

Before this can be merged to main, the following must pass:

  • Tested on 3 repos
  • No regressions on existing parsers (ix map on a known TS/JS repo, verify counts unchanged)
  • Unit + smoke tests pass (npm test in ix-cli)
  • Heading hierarchy chains correctly: file → h1 → h2 → h3
  • Both ATX and setext heading syntax ingested
  • ix contains returns children for a known markdown file and heading
  • Frontmatter entities present where expected
  • Section chunks created alongside heading entities
  • ix text returns results with language: markdown
  • Both .md and .markdown extensions ingested

Metadata

Metadata

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions