faouzi96/md-code-assist / .github/skills/markdown-ast
markdown-ast
UnverifiedExpertise in parsing and manipulating Markdown AST using unified, remark, and mdast. Use when working with Markdown parsing, extracting fenced code blocks, or transforming Markdown documents programmatically.
Markdown AST Parsing
When to Use This Skill
- Parsing Markdown documents to AST
- Extracting fenced code blocks with metadata
- Transforming or modifying Markdown content
- Working with unified/remark ecosystem
- Calculating source positions for code blocks
Core Libraries
npm install unified remark-parse remark-stringify unist-util-visit
| Package | Purpose |
|---|---|
unified | Core processor pipeline |
remark-parse | Markdown to AST parser |
remark-stringify | AST to Markdown serializer |
unist-util-visit | AST traversal utility |
mdast | TypeScript types for Markdown AST |
Parsing Markdown
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import type { Root, Code } from 'mdast';
const processor = unified().use(remarkParse);
function parseMarkdown(content: string): Root {
return processor.parse(content) as Root;
}
Extracting Fenced Code Blocks
import { visit } from 'unist-util-visit';
import type { Root, Code } from 'mdast';
interface CodeBlock {
language: string | null;
code: string;
startLine: number;
endLine: number;
startOffset: number;
endOffset: number;
}
function extractCodeBlocks(ast: Root): CodeBlock[] {
const blocks: CodeBlock[] = [];
visit(ast, 'code', (node: Code) => {
if (node.position) {
blocks.push({
language: node.lang || null,
code: node.value,
startLine: node.position.start.line - 1, // 0-indexed
endLine: node.position.end.line - 1,
startOffset: node.position.start.offset ?? 0,
endOffset: node.position.end.offset ?? 0,
});
}
});
return blocks;
}
AST Node Types for Code Blocks
// mdast Code node structure
interface Code {
type: 'code';
lang?: string; // Language identifier (e.g., 'javascript')
meta?: string; // Additional metadata after language
value: string; // The code content (without fences)
position?: { // Source location
start: { line: number; column: number; offset?: number };
end: { line: number; column: number; offset?: number };
};
}
Position Mapping
The AST positions point to the fence markers, not the code content:
```javascript <- position.start.line (line 1)
const x = 1; <- code starts here (line 2)
``` <- position.end.line (line 3)
// To get the actual code content line:
const codeContentStartLine = node.position.start.line; // Fence line
const firstCodeLine = codeContentStartLine + 1; // First code line
// To map a line within the code block back to Markdown:
function mapToMarkdownLine(codeBlockStart: number, lineInCode: number): number {
return codeBlockStart + lineInCode + 1; // +1 for opening fence
}
Modifying Code Blocks
import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkStringify from 'remark-stringify';
import { visit } from 'unist-util-visit';
async function formatCodeBlocks(
markdown: string,
formatter: (code: string, lang: string) => Promise<string>
): Promise<string> {
const processor = unified()
.use(remarkParse)
.use(() => async (tree: Root) => {
const promises: Promise<void>[] = [];
visit(tree, 'code', (node: Code) => {
if (node.lang) {
promises.push(
formatter(node.value, node.lang).then((formatted) => {
node.value = formatted;
})
);
}
});
await Promise.all(promises);
})
.use(remarkStringify, {
fence: '`',
fences: true,
});
const result = await processor.process(markdown);
return String(result);
}
Handling Language Aliases
const languageAliases: Record<string, string> = {
'js': 'javascript',
'ts': 'typescript',
'py': 'python',
'rb': 'ruby',
'sh': 'shell',
'bash': 'shell',
'zsh': 'shell',
'yml': 'yaml',
};
function normalizeLanguage(lang: string | null): string | null {
if (!lang) return null;
return languageAliases[lang.toLowerCase()] || lang.toLowerCase();
}
Common Patterns
Selective Processing
visit(ast, 'code', (node: Code, index, parent) => {
// Skip code blocks without language
if (!node.lang) return;
// Skip specific languages
if (['text', 'plaintext', 'txt'].includes(node.lang)) return;
// Process only supported languages
if (supportedLanguages.includes(node.lang)) {
processBlock(node);
}
});
Preserving Metadata
```javascript title="example.js" highlight={[1,3]}
const x = 1;
```
// node.meta contains: 'title="example.js" highlight={[1,3]}'
// Preserve it when modifying:
const meta = node.meta ? ` ${node.meta}` : '';
Gotchas
| Issue | Cause | Solution |
|---|---|---|
| Position is undefined | Parser option missing | Ensure remark-parse is configured correctly |
| Indented code blocks | Not fenced | Filter by checking if node.lang exists |
| Fence style changes | Stringify defaults | Configure remarkStringify options |
| Trailing newlines | Stringify behavior | Trim or configure output |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |