---

name: markdown-indexing description: "Guides PageIndex Markdown-to-tree conversion, heading parsing, thinning, and optional summaries." disable-model-invocation: true metadata: disco-role: operating license: MIT

Markdown Indexing

Use this sub-skill when the user wants to convert .md or .markdown files into PageIndex trees, reason about heading parsing, use md_to_tree, enable tree thinning, or troubleshoot line-number based retrieval.

Do not use it for:

• PDF files -> use ../pdf-indexing/ or ../flash-indexing/
• workspace retrieval after indexing -> use ../retrieval-client/

Required context

Read these shared references as needed:

• ../../references/workflows.md#markdown-tree-extraction for CLI and API recipes.
• ../../references/api-reference.md#markdown-tree-extraction for the verified md_to_tree signature.
• ../../references/data-formats.md#markdown-tree-output for line-number output shape.
• ../../references/troubleshooting.md#markdown-extraction for heading and summary failures.
• ../../references/configuration.md#offline-friendly-modes for no-LLM settings.

Operating flow

1. Prefer explicit no-summary flags when the user only needs structure:

   python ../../scripts/pageindex_cli.py --md_path notes.md --if-add-node-summary no --if-add-doc-description no
   

2. Enable thinning only when the user has many small sections:

   python ../../scripts/pageindex_cli.py --md_path notes.md --if-thinning yes --thinning-threshold 5000 --if-add-node-summary no
   

3. Use the async API from synchronous code with asyncio.run:

   import asyncio
   from pageindex import md_to_tree
   
   result = asyncio.run(md_to_tree("notes.md", if_add_node_summary="no"))
   

4. For an offline smoke check, run python scripts/markdown_smoke.py from this sub-skill directory.

Heading rules

• ATX headings (#, ##, ... ######) become nodes at their matching levels.
• Non-empty bold-only lines (**Heading**) become level-1 nodes.
• Empty bold-only headings are ignored.
• Fenced code blocks suppress heading detection until the closing fence.
• Markdown output uses line_num, not PDF page indexes.

Common decisions

• If the user asks for retrieval after conversion, route to ../retrieval-client/ after generating or loading the workspace.
• If model keys are unavailable, turn off if_add_node_summary and if_add_doc_description.
• If the tree is too granular, use thinning; if content disappears, lower the thinning threshold or disable thinning.