mdsel parses Markdown documents into semantic trees and exposes machine-addressable selectors for every meaningful chunk. It enables LLMs to request exactly the content they want—no more, no less—without loading entire files into context.

Demo

1. Index a document to see its structure:

$ mdsel README.md
h1.0 mdsel
 h2.0 Demo
 h2.1 Installation
 h2.2 Quick Start
 h2.3 Usage
  h3.0 Index (files only)
  h3.1 Select (files + selectors)
  h3.2 Search (fuzzy matching)
 h2.4 Selectors
 h2.5 Output Format
 h2.6 Error Handling
 h2.7 Development
 h2.8 License
---
code:29 para:29 list:5 table:4

2. Select specific content by selector:

$ mdsel h2.1 README.md
## Installation

npm install -g mdsel

**Requirements**: Node.js >=18.0.0

3. Drill into nested content:

$ mdsel "h2.1/code.0" README.md
npm install -g mdsel

Installation

npm install -g mdsel

Requirements: Node.js >=18.0.0

Quick Start

# Index a document to see its structure
mdsel README.md

# Select a specific section by index
mdsel h2.1 README.md

# Select the entire document
mdsel '*' README.md

# Select a nested element (first code block under second h2)
mdsel "h2.1/code.0" README.md

# Select multiple sections at once
mdsel h2.0 h2.1 README.md

# Select a range of sections
mdsel h2.0-2 README.md

# Fuzzy search when you don't know the exact selector
mdsel "installation" README.md

# Limit output to first N lines
mdsel "h2.0?head=10" README.md

# JSON output for programmatic use
mdsel --json README.md

Usage

mdsel [options] <files...> [selectors...]

Arguments are auto-detected: .md files and existing paths are files, everything else is a selector.

Options:

--json - Output JSON instead of text
--help - Show help

Index (files only)

When only files are provided, outputs the document structure:

mdsel README.md

h1.0 mdsel
 h2.0 Demo
 h2.1 Installation
 h2.2 Quick Start
 h2.3 Usage
  h3.0 Index (files only)
  h3.1 Select (files + selectors)
  h3.2 Search (fuzzy matching)
---
code:29 para:29 list:5 table:4

The index shows:

Heading hierarchy with selectors (e.g., h1.0, h2.0)
Indentation reflecting document structure
Block counts for code, paragraphs, lists, tables

Select (files + selectors)

When selectors are provided, retrieves matching content:

# Single result - content only
mdsel h2.1 README.md

## Installation

npm install -g mdsel

**Requirements**: Node.js >=18.0.0

# Multiple results - prefixed with selector
mdsel h2.0 h2.1 README.md

heading:h2.0:
## Demo
...
heading:h2.1:
## Installation
...

# Errors show suggestions
mdsel h2.99 README.md

!h2.99
Index out of range: document has 9 h2 headings
~h2.0 ~h2.1 ~h2.2

Search (fuzzy matching)

When input doesn't look like a selector, mdsel performs fuzzy search:

mdsel "installation" README.md

Search results for "installation":

readme::h2.1 (100% match)
  Installation

readme::code.9 (74% match)
  ## Installation npm install -g mdsel ...

Search returns selectors you can use directly to fetch the content.

Selectors

Selectors are path-based, ordinal, stateless, and deterministic. They resemble CSS/XPath conceptually but are purpose-built for Markdown.

Syntax

[namespace::]type[index][/path][?query]

namespace (optional) - Document identifier, defaults to all documents
type - Node type (root, heading, section, block) or shorthand
index (optional) - 0-based ordinal: .N, [N], .N-M (range), .N,M,O (list)
path (optional) - Additional path segments for nested selection
query (optional) - Query parameters (e.g., ?head=10, ?tail=5)

Node Types

Category	Full Form	Shorthand
Wildcard	`*`	`*`
Root	`root`	-
Headings	`heading:h1` ... `heading:h6`	`h1` ... `h6`
Sections	`section`	-
Blocks	`block:paragraph`	`para`, `paragraph`
	`block:code`	`code`
	`block:list`	`list`
	`block:table`	`table`
	`block:blockquote`	`quote`, `blockquote`

Index Syntax

Two equivalent notations are supported:

Notation	Example	Meaning
Dot	`h2.0`	First h2
Bracket	`h2[0]`	First h2
Range	`h2.1-3` or `h2[1-3]`	h2.1, h2.2, h2.3
Comma list	`h2.0,2,4` or `h2[0,2,4]`	h2.0, h2.2, h2.4
No index	`h2`	All h2 headings

Examples

Basic selection:

*                   # Entire document (wildcard)
root                # Document root
h1.0                # First h1 heading
h2.1                # Second h2 heading
code.0              # First code block
para.2              # Third paragraph

Full form (equivalent):

heading:h1[0]       # First h1 heading
block:code[0]       # First code block

Namespace selection:

readme::root        # Root in specific document
docs::h2.0          # First h2 in docs
api::table.1        # Second table in api

Path composition:

h2.1/code.0                    # First code block under second h2
section.0/list.1               # Second list in first section
docs::h2.0/section.0/code.0    # Nested path with namespace

Range and list selection:

h2.0-2              # First three h2 headings
h2.1,3,5            # 2nd, 4th, and 6th h2 headings
code.0,2            # 1st and 3rd code blocks

Query parameters:

h2.0?head=10        # First 10 lines of content
h2.0?tail=5         # Last 5 lines of content
section.2?head=20   # First 20 lines of section

Cross-document selection:

h1.0                # First h1 from ALL documents
code.0              # First code block from ALL documents

Index Semantics

Index is 0-based (first item is index 0)
Index counts among siblings of the same type
Index is relative to parent context, not global
No index means select all matches of that type

Output Format

Default output is compact text optimized for LLM token efficiency. Use --json for structured JSON output.

Index Response Schema (JSON)

interface IndexResponse {
  documents: DocumentIndex[];
  summary: {
    total_documents: number;
    total_nodes: number;
    total_selectors: number;
  };
}

Select Response Schema (JSON)

interface SelectResponse {
  matches: {
    selector: string;
    type: string;
    content: string;
    truncated: boolean;
    children_available: {
      selector: string;
      type: string;
      preview: string;
    }[];
  }[];
  unresolved: {
    selector: string;
    reason: string;
    suggestions: string[];
  }[];
}

Truncation

By default, full content is returned. Use ?head=N or ?tail=N query parameters to limit output to the first or last N lines. Truncated content includes a [truncated] marker.

Error Handling

Exit Codes

Code	Meaning
0	Success
1	Error
2	Usage error

Error Types

Type	Description
`FILE_NOT_FOUND`	Specified file does not exist
`PARSE_ERROR`	Markdown parsing failed
`INVALID_SELECTOR`	Selector syntax is invalid
`SELECTOR_NOT_FOUND`	Selector does not match any nodes
`NAMESPACE_NOT_FOUND`	Specified namespace does not exist
`PROCESSING_ERROR`	General processing error

Error Response Example

Text format:

!h2.99
Index out of range: document has 3 h2 headings
~h2.0 ~h2.1 ~h2.2

JSON format:

{
  "success": false,
  "command": "select",
  "timestamp": "2025-01-15T10:38:00.000Z",
  "data": {
    "matches": [],
    "unresolved": [
      {
        "selector": "h2.99",
        "reason": "Index out of range: document has 3 h2 headings",
        "suggestions": ["h2.0", "h2.1", "h2.2"]
      }
    ]
  }
}

Suggestions

When a selector fails to resolve, the tool provides fuzzy-matched suggestions based on:

Known selector grammar
Existing selectors in the document
Levenshtein distance and prefix similarity

Development

# Run tests
npm test

# Build project
npm run build

# Lint code
npm run lint

# Format code
npm run format

# Type check
npm run type-check

Requirements: Node.js >=18.0.0, npm

License

MIT

Keywords

FAQs

What is mdsel?

Is mdsel popular?

Is mdsel well maintained?

Package last updated on 31 Dec 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

mdsel