markdown-mdx

name	markdown-mdx
description	Advanced Markdown and MDX processing for technical documentation. Parse, validate, lint, and transform Markdown content with support for MDX components, front matter, and remark/rehype plugins.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
backlog-id	SK-005
metadata	{"author":"babysitter-sdk","version":"1.0.0"}
graph	{"domains":["domain:software-engineering"],"specializations":["specialization:technical-documentation"],"skillAreas":["skill-area:docs-as-code","skill-area:reference-docs"],"roles":["role:technical-writer","role:documentation-engineer"]}

Markdown/MDX Skill

Advanced Markdown and MDX processing for technical documentation.

Capabilities

• Parse and validate Markdown syntax (CommonMark, GFM)
• MDX component development and integration
• Remark/Rehype plugin configuration
• Front matter parsing and validation
• Markdown linting (markdownlint rules)
• Table formatting and generation
• Link validation and URL checking
• Convert between documentation formats

Usage

Invoke this skill when you need to:

• Lint and validate Markdown files
• Create or integrate MDX components
• Configure remark/rehype pipelines
• Validate front matter schemas
• Convert between documentation formats

Inputs

Parameter	Type	Required	Description
inputPath	string	Yes	Path to Markdown/MDX file or directory
action	string	Yes	lint, validate, transform, parse-frontmatter
outputPath	string	No	Output path for transformed content
configPath	string	No	Path to markdownlint config
frontmatterSchema	object	No	JSON schema for front matter validation
plugins	array	No	Remark/rehype plugins to apply

Input Example

{
  "inputPath": "./docs",
  "action": "lint",
  "configPath": ".markdownlint.json"
}

Output Structure

Lint Output

{
  "files": 42,
  "errors": 5,
  "warnings": 12,
  "issues": [
    {
      "file": "docs/getting-started.md",
      "line": 15,
      "rule": "MD022",
      "message": "Headings should be surrounded by blank lines",
      "severity": "error"
    }
  ],
  "fixable": 8
}

Front Matter Parse Output

{
  "file": "docs/api/users.md",
  "frontmatter": {
    "title": "Users API",
    "description": "User management endpoints",
    "tags": ["api", "users"],
    "sidebar_position": 3
  },
  "valid": true,
  "content": "# Users API\n\nThis document..."
}

Markdown Patterns

CommonMark Extensions

# Heading 1

## Heading 2 {#custom-id}

Paragraph with **bold**, *italic*, and `code`.

> Blockquote with
> multiple lines

- Unordered list
- With items
  - Nested item

1. Ordered list
2. With numbers

| Column 1 | Column 2 |
|----------|----------|
| Cell 1   | Cell 2   |

[Link text](https://example.com "Title")

![Alt text](image.png)

```javascript
const code = 'block';

---

Horizontal rule above.

### GitHub Flavored Markdown (GFM)

```markdown
## GFM Extensions

### Task Lists
- [x] Completed task
- [ ] Incomplete task

### Tables
| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

### Strikethrough
~~deleted text~~

### Autolinks
https://example.com

### Footnotes
Here's a sentence with a footnote[^1].

[^1]: This is the footnote.

### Alerts
> [!NOTE]
> Useful information.

> [!WARNING]
> Critical content.

MDX Patterns

MDX Components

---
title: Interactive Guide
---

import { Tabs, TabItem } from '@site/src/components/Tabs';
import CodeBlock from '@theme/CodeBlock';

# Getting Started

<Tabs>
  <TabItem value="npm" label="npm">
    ```bash
    npm install my-package
    ```
  </TabItem>
  <TabItem value="yarn" label="yarn">
    ```bash
    yarn add my-package
    ```
  </TabItem>
</Tabs>

## Configuration

<CodeBlock language="json" title="config.json">
{`{
  "setting": "value"
}`}
</CodeBlock>

export const Highlight = ({children, color}) => (
  <span style={{backgroundColor: color, padding: '0.2rem'}}>
    {children}
  </span>
);

This is <Highlight color="#25c2a0">highlighted text</Highlight>.

MDX Component Library

// components/Callout.jsx
export function Callout({ type = 'info', title, children }) {
  const styles = {
    info: { bg: '#e7f5ff', border: '#339af0' },
    warning: { bg: '#fff3bf', border: '#fab005' },
    error: { bg: '#ffe3e3', border: '#fa5252' },
    success: { bg: '#d3f9d8', border: '#40c057' }
  };

  return (
    <div style={{
      backgroundColor: styles[type].bg,
      borderLeft: `4px solid ${styles[type].border}`,
      padding: '1rem',
      margin: '1rem 0'
    }}>
      {title && <strong>{title}</strong>}
      {children}
    </div>
  );
}

import { Callout } from '@site/src/components/Callout';

<Callout type="warning" title="Deprecation Notice">
  This API will be removed in version 3.0.
</Callout>

Markdownlint Configuration

.markdownlint.json

{
  "default": true,
  "MD013": false,
  "MD033": {
    "allowed_elements": ["details", "summary", "Tabs", "TabItem"]
  },
  "MD041": false,
  "MD024": {
    "siblings_only": true
  },
  "MD046": {
    "style": "fenced"
  },
  "MD048": {
    "style": "backtick"
  }
}

markdownlint-cli2 Configuration

# .markdownlint-cli2.yaml
config:
  default: true
  MD013: false

globs:
  - "docs/**/*.md"
  - "!node_modules"
  - "!.git"

ignores:
  - "CHANGELOG.md"

customRules:
  - markdownlint-rule-search-replace

Remark/Rehype Plugins

remark.config.mjs

import remarkGfm from 'remark-gfm';
import remarkFrontmatter from 'remark-frontmatter';
import remarkMdxFrontmatter from 'remark-mdx-frontmatter';
import remarkToc from 'remark-toc';
import remarkSlug from 'remark-slug';

export default {
  plugins: [
    remarkGfm,
    remarkFrontmatter,
    remarkMdxFrontmatter,
    [remarkToc, { heading: 'contents', tight: true }],
    remarkSlug
  ]
};

rehype.config.mjs

import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
import rehypePrism from 'rehype-prism-plus';

export default {
  plugins: [
    rehypeSlug,
    [rehypeAutolinkHeadings, { behavior: 'wrap' }],
    [rehypePrism, { showLineNumbers: true }]
  ]
};

Front Matter Schema

JSON Schema for Validation

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["title"],
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "type": "string",
      "maxLength": 300
    },
    "tags": {
      "type": "array",
      "items": { "type":  
    
     
       
       
    
     
       
       
    
  
   

Workflow

1. Parse content - Load Markdown/MDX files
2. Extract front matter - Parse YAML front matter
3. Validate structure - Check against schema
4. Lint content - Apply markdownlint rules
5. Transform - Apply remark/rehype plugins
6. Report findings - Output validation results

Dependencies

{
  "devDependencies": {
    "markdownlint-cli2": "^0.12.0",
    "remark": "^15.0.0",
    "remark-gfm": "^4.0.0",
    "remark-frontmatter": "^5.0.0",
    "remark-mdx": "^3.0.0",
    "rehype": "^13.0.0",
    "gray-matter": "^4.0.0",
    "ajv": "^8.0.0"
  }
}

CLI Commands

# Lint all Markdown files
npx markdownlint-cli2 "docs/**/*.md"

# Fix auto-fixable issues
npx markdownlint-cli2 --fix "docs/**/*.md"

# Parse and validate front matter
node scripts/validate-frontmatter.js docs/

# Convert Markdown to HTML
npx remark docs/guide.md -o build/guide.html

Best Practices Applied

• Use ATX-style headings (#)
• Consistent list markers (- for unordered)
• Fenced code blocks with language identifier
• Front matter for metadata
• Descriptive link text (not "click here")
• Alt text for all images
• One sentence per line for better diffs

References

• CommonMark: https://commonmark.org/
• GFM: https://github.github.com/gfm/
• MDX: https://mdxjs.com/
• markdownlint: https://github.com/DavidAnson/markdownlint
• remark: https://remark.js.org/
• rehype: https://github.com/rehypejs/rehype

Target Processes

• style-guide-enforcement.js
• docs-testing.js
• docs-audit.js
• content-strategy.js