--- 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" --- # 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 ```json { "inputPath": "./docs", "action": "lint", "configPath": ".markdownlint.json" } ``` ## Output Structure ### Lint Output ```json { "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 ```json { "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 ```markdown # 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 ```mdx --- title: Interactive Guide --- import { Tabs, TabItem } from '@site/src/components/Tabs'; import CodeBlock from '@theme/CodeBlock'; # Getting Started ```bash npm install my-package ``` ```bash yarn add my-package ``` ## Configuration {`{ "setting": "value" }`} export const Highlight = ({children, color}) => ( {children} ); This is highlighted text. ``` ### MDX Component Library ```jsx // 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 (
{title && {title}} {children}
); } ``` ```mdx import { Callout } from '@site/src/components/Callout'; This API will be removed in version 3.0. ``` ## Markdownlint Configuration ### .markdownlint.json ```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 ```yaml # .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 ```javascript 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 ```javascript 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 ```json { "$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": "string" } }, "sidebar_position": { "type": "integer", "minimum": 0 }, "draft": { "type": "boolean", "default": false } }, "additionalProperties": false } ``` ## 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 ```json { "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 ```bash # 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