Skip to content

faouzi96/md-code-assist / .github/skills/markdown-ast

markdown-ast

Unverified

Expertise 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
PackagePurpose
unifiedCore processor pipeline
remark-parseMarkdown to AST parser
remark-stringifyAST to Markdown serializer
unist-util-visitAST traversal utility
mdastTypeScript 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

IssueCauseSolution
Position is undefinedParser option missingEnsure remark-parse is configured correctly
Indented code blocksNot fencedFilter by checking if node.lang exists
Fence style changesStringify defaultsConfigure remarkStringify options
Trailing newlinesStringify behaviorTrim or configure output
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 implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
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 fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
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 alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall