Agent skill

markdown-mdx

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.

View SKILL.md on GitHub Repository
Stars 514
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/a5c-ai/babysitter/tree/main/library/specializations/technical-documentation/skills/markdown-mdx

Metadata

Additional technical details for this skill

author
babysitter-sdk
version
1.0.0

SKILL.md

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

<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

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

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

Target Processes

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

a5c-ai/babysitter

gsd-tools

Central utility skill for GSD operations. Provides config parsing, slug generation, timestamps, path operations, and orchestrates calls to other specialized skills. Acts as the unified entry point that the original gsd-tools.cjs provided via its lib/ modules (commands, config, core, init).

514 31
Explore
a5c-ai/babysitter

model-profile-resolution

Resolve model profile (quality/balanced/budget) at orchestration start and map agents to specific models. Enables cost/quality tradeoffs by selecting appropriate AI models for each agent role.

514 31
Explore
a5c-ai/babysitter

verification-suite

Plan structure validation, phase completeness checks, reference integrity verification, and artifact existence confirmation. Provides the structured verification layer ensuring GSD artifacts are well-formed and complete.

514 31
Explore
a5c-ai/babysitter

state-management

STATE.md reading, writing, and field-level updates. Provides cross-session state persistence via .planning/STATE.md with structured fields for current task, completed phases, blockers, decisions, and quick tasks.

514 31
Explore
a5c-ai/babysitter

git-integration

Git commit patterns, formats, and conventions for GSD methodology. Provides atomic commits per task, structured commit messages, planning file commits, branch management, and milestone tag operations.

514 31
Explore
a5c-ai/babysitter

frontmatter-parsing

YAML frontmatter parsing and manipulation for .planning/ documents. Provides read, write, update, query, and validation operations on frontmatter blocks in GSD markdown artifacts.

514 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results