markdown-docs
Navigate and work with interconnected markdown documentation. Use when reading, writing, or validating markdown documents in mddocs/, or when following links between documents.
When & Why to Use This Skill
This Claude skill provides a robust framework for managing and navigating interconnected Markdown documentation. It solves the problem of information overload in large document sets by allowing users to retrieve specific sections via anchors, automatically generate Tables of Contents, and validate cross-document links to ensure documentation integrity and prevent broken references.
Use Cases
- Efficiently exploring large technical repositories by retrieving only relevant sections instead of full documents to save context window space.
- Maintaining documentation integrity by automatically validating all internal markdown links and fragment identifiers across a corpus.
- Automating the creation and maintenance of Tables of Contents for complex, multi-file project documentation or internal wikis.
- Streamlining technical writing workflows by using hierarchical heading paths to disambiguate and link to specific content blocks.
| name | markdown-docs |
|---|---|
| description | Navigate and work with interconnected markdown documentation. Use when reading, writing, or validating markdown documents in mddocs/, or when following links between documents. |
Markdown Documentation Navigation
This skill enables working with a corpus of interconnected markdown documents in mddocs/.
Core Concepts
Documents link to each other using standard markdown syntax with fragment identifiers:
See the [authentication requirements](../prd.md#user-authentication) for details.
Section addressing uses heading anchors:
- Simple:
#user-authentication - Hierarchical:
#user-authentication/requirements(for nested/ambiguous headings)
Table of Contents: Every document has a ## Table of Contents section (anchor: #table-of-contents) for efficient navigation.
Tools
Explore a Document (ToC First)
When exploring unfamiliar documentation, first retrieve the Table of Contents:
python .claude/skills/markdown-docs/scripts/get_section.py <file> table-of-contents
Then retrieve only the sections you need.
Retrieve a Section
When you need context from a linked document, prefer loading specific sections over full documents:
python .claude/skills/markdown-docs/scripts/get_section.py <file> <anchor>
Examples:
# Get a section by anchor
python .claude/skills/markdown-docs/scripts/get_section.py mddocs/prd.md user-authentication
# Get a nested section by path
python .claude/skills/markdown-docs/scripts/get_section.py mddocs/prd.md user-authentication/requirements
# Get only immediate content (no subsections)
python .claude/skills/markdown-docs/scripts/get_section.py mddocs/prd.md user-authentication --shallow
List Available Sections
To see what sections exist in a document:
python .claude/skills/markdown-docs/scripts/get_section.py <file> --list
Validate Links
Before committing documentation changes, validate all cross-document links:
python .claude/skills/markdown-docs/scripts/validate_links.py mddocs/
Regenerate Table of Contents
After creating or modifying any document, regenerate ToCs:
# All documents
python .claude/skills/markdown-docs/scripts/generate_toc.py mddocs/
# Single file
python .claude/skills/markdown-docs/scripts/generate_toc.py mddocs/path/to/file.md
When to Load Full Documents vs Sections
Load the Table of Contents first when:
- Exploring a new/unfamiliar document
- You need to understand what topics are covered
- You're unsure which section contains the information you need
Load a specific section when:
- The link has a
#fragment - You only need background on one topic
- The document is large
Load the full document when:
- You're editing the document extensively
- Multiple scattered sections are relevant
- The document is small
Writing Documents
When writing or editing documents in mddocs/:
- Use the linking convention:
[descriptive text](relative/path.md#section-anchor) - Create unique headings or use hierarchical paths for disambiguation
- Regenerate ToCs:
python .claude/skills/markdown-docs/scripts/generate_toc.py mddocs/ - Run validation:
python .claude/skills/markdown-docs/scripts/validate_links.py mddocs/
See conventions.md for the full specification.