markdown-tree-parser

A powerful JavaScript library and CLI tool for parsing and manipulating markdown files as tree structures. Built on top of the battle-tested remark/unified ecosystem.

🚀 Features

• 🌳 Tree-based parsing - Treats markdown as manipulable Abstract Syntax Trees (AST)
• ✂️ Section extraction - Extract specific sections with automatic boundary detection
• 🔍 Powerful search - CSS-like selectors and custom search functions
• 📚 Batch processing - Process multiple sections at once
• 🛠️ CLI & Library - Use as a command-line tool or JavaScript library
• 📊 Document analysis - Get statistics and generate table of contents
• 🎯 TypeScript ready - Full type definitions included

📦 Installation

Global Installation (for CLI usage)

# Using npm
npm install -g @kayvan/markdown-tree-parser
# Using pnpm (may require approval for build scripts)
pnpm install -g @kayvan/markdown-tree-parser
pnpm approve-builds -g # If prompted# Using yarn
yarn global add @kayvan/markdown-tree-parser

Local Installation (for library usage)

npm install @kayvan/markdown-tree-parser

🔧 CLI Usage

After global installation, use the md-tree command:

List all headings

md-tree list README.md
md-tree list README.md --format json

Extract specific sections

# Extract one section
md-tree extract README.md "Installation"# Extract to a file
md-tree extract README.md "Installation" --output ./sections

Extract all sections at a level

# Extract all level-2 sections
md-tree extract-all README.md 2
# Extract to separate files
md-tree extract-all README.md 2 --output ./sections

Show document structure

md-tree tree README.md

Search with CSS-like selectors

# Find all level-2 headings
md-tree search README.md "heading[depth=2]"# Find all links
md-tree search README.md "link"

Document statistics

md-tree stats README.md

Check links

md-tree check-links README.md
md-tree check-links README.md --recursive

Generate table of contents

md-tree toc README.md --max-level 3

Complete CLI options

md-tree help

📚 Library Usage

Basic Usage

import{MarkdownTreeParser}from'markdown-tree-parser';constparser=newMarkdownTreeParser();// Parse markdown into ASTconstmarkdown=`# My DocumentSome content here.## Section 1Content for section 1.## Section 2Content for section 2.`;consttree=awaitparser.parse(markdown);// Extract a specific sectionconstsection=parser.extractSection(tree,'Section 1');constsectionMarkdown=awaitparser.stringify(section);console.log(sectionMarkdown);// Output:// ## Section 1// Content for section 1.

Advanced Usage

import{MarkdownTreeParser,createParser,extractSection,}from'markdown-tree-parser';// Create parser with custom optionsconstparser=createParser({bullet: '-',// Use '-' for listsemphasis: '_',// Use '_' for emphasisstrong: '__',// Use '__' for strong});// Extract all sections at level 2consttree=awaitparser.parse(markdown);constsections=parser.extractAllSections(tree,2);sections.forEach(async(section,index)=>{constheading=parser.getHeadingText(section.heading);constcontent=awaitparser.stringify(section.tree);console.log(`Section ${index+1}: ${heading}`);console.log(content);});// Use convenience functionsconstsectionMarkdown=awaitextractSection(markdown,'Installation');

Search and Manipulation

// CSS-like selectorsconstheadings=parser.selectAll(tree,'heading[depth=2]');constlinks=parser.selectAll(tree,'link');constcodeBlocks=parser.selectAll(tree,'code');// Custom searchconstcustomNode=parser.findNode(tree,(node)=>{returnnode.type==='heading'&&parser.getHeadingText(node).includes('API');});// Transform contentparser.transform(tree,(node)=>{if(node.type==='heading'&&node.depth===1){node.depth=2;// Convert h1 to h2}});// Get document statisticsconststats=parser.getStats(tree);console.log(`Document has ${stats.wordCount} words and ${stats.headings.total} headings`);// Generate table of contentsconsttoc=parser.generateTableOfContents(tree,3);console.log(toc);

Working with Files

importfsfrom'fs/promises';// Read and process a fileconstcontent=awaitfs.readFile('README.md','utf-8');consttree=awaitparser.parse(content);// Extract all sections and save to filesconstsections=parser.extractAllSections(tree,2);for(leti=0;i<sections.length;i++){constsection=sections[i];constfilename=`section-${i+1}.md`;constmarkdown=awaitparser.stringify(section.tree);awaitfs.writeFile(filename,markdown);}

🎯 Use Cases

• 📖 Documentation Management - Split large docs into manageable sections
• 🌐 Static Site Generation - Process markdown for blogs and websites
• 📝 Content Organization - Restructure and reorganize markdown content
• 🔍 Content Analysis - Analyze document structure and extract insights
• 📋 Documentation Tools - Build custom documentation processing tools
• 🚀 Content Migration - Extract and transform content between formats

🏗️ API Reference

MarkdownTreeParser

Constructor

newMarkdownTreeParser((options={}));

Methods

• parse(markdown) - Parse markdown into AST
• stringify(tree) - Convert AST back to markdown
• extractSection(tree, headingText, level?) - Extract specific section
• extractAllSections(tree, level) - Extract all sections at level
• select(tree, selector) - Find first node matching CSS selector
• selectAll(tree, selector) - Find all nodes matching CSS selector
• findNode(tree, condition) - Find node with custom condition
• getHeadingText(headingNode) - Get text content of heading
• getHeadingsList(tree) - Get all headings with metadata
• getStats(tree) - Get document statistics
• generateTableOfContents(tree, maxLevel) - Generate TOC
• transform(tree, visitor) - Transform tree with visitor function

Convenience Functions

• createParser(options) - Create new parser instance
• extractSection(markdown, sectionName, options) - Quick section extraction
• getHeadings(markdown, options) - Quick heading extraction
• generateTOC(markdown, maxLevel, options) - Quick TOC generation

🔗 CSS-Like Selectors

The library supports powerful CSS-like selectors for searching:

// Element selectorsparser.selectAll(tree,'heading');// All headingsparser.selectAll(tree,'paragraph');// All paragraphsparser.selectAll(tree,'link');// All links// Attribute selectorsparser.selectAll(tree,'heading[depth=1]');// H1 headingsparser.selectAll(tree,'heading[depth=2]');// H2 headingsparser.selectAll(tree,'link[url*="github"]');// Links containing "github"// Pseudo selectorsparser.selectAll(tree,':first-child');// First child elementsparser.selectAll(tree,':last-child');// Last child elements

🧪 Testing

# Run tests
npm test# Test CLI
npm run test:cli
# Run examples
npm run example

🔧 Development

Prerequisites

• Node.js 18+
• npm

Setup

# Clone the repository
git clone https://github.com/ksylvan/markdown-tree-parser.git
cd markdown-tree-parser
# Install dependencies
npm install
# Run tests
npm test# Run linting
npm run lint
# Format code
npm run format
# Test CLI functionality
npm run test:cli

CI/CD

This project uses GitHub Actions for continuous integration. The workflow automatically:

• Tests against Node.js versions 18.x, 20.x, and 22.x
• Runs linting with ESLint
• Executes the full test suite
• Tests CLI functionality
• Verifies the package can be published

The CI badge in the README shows the current build status and links to the Actions page.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built on top of the excellent unified ecosystem:

• remark - Markdown processing
• mdast - Markdown AST specification
• unist - Universal syntax tree utilities

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---

Made with ❤️ by Kayvan Sylvan