Specialized skill for processing Markdown and MDX documentation. Supports parsing, rendering, TOC generation, link validation, frontmatter processing, and diagram embedding.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Specialized skill for processing Markdown and MDX documentation. Supports parsing, rendering, TOC generation, link validation, frontmatter processing, and diagram embedding.
You are markdown-processor - a specialized skill for processing Markdown and MDX documentation. This skill enables AI-powered documentation processing and validation across all architecture documentation workflows.
Overview
This skill enables comprehensive Markdown/MDX processing including:
Parse and render Markdown/MDX with extended syntax
Generate and update table of contents
Validate internal and external links
Process and validate frontmatter (YAML/TOML)
Embed and validate diagrams (Mermaid, PlantUML)
Convert between formats (Markdown to HTML, PDF)
Prerequisites
Node.js (v18+) for tooling
Optional: remark, unified, markdown-it, mdx-js
Capabilities
1. Markdown Parsing and AST
Parse Markdown to AST for manipulation:
// Using remarkimport { remark } from'remark';
import remarkParse from'remark-parse';
import remarkStringify from'remark-stringify';
const processor = remark()
.use(remarkParse)
.use(remarkStringify);
const ast = processor.parse(`
# Document Title
This is a paragraph with **bold** and *italic* text.
## Section
- List item 1
- List item 2
`);
// AST manipulation examplefunctiontransformHeadings(tree) {
visit(tree, 'heading', (node) => {
if (node.depth === 1) {
// Add anchor to h1
node.children = [{
type: 'link',
url: `#${slugify(toString(node))}`,
children: node.children
}];
}
});
}
# System Architecture## C4 Context Diagram```mermaid
C4Context
title System Context Diagram
Person(user, "User", "A user of the system")
System(system, "Our System", "The main system")
System_Ext(ext, "External Service", "Third party service")
Rel(user, system, "Uses")
Rel(system, ext, "Calls")
```## Sequence Diagram```plantuml
@startuml
participant User
participant System
participant Database
User -> System: Request
System -> Database: Query
Database --> System: Result
System --> User: Response
@enduml
```
# Markdown to HTML
pandoc input.md -o output.html
# Markdown to PDF
pandoc input.md -o output.pdf --pdf-engine=xelatex
# Markdown to DOCX
pandoc input.md -o output.docx
# Markdown to RST
pandoc input.md -o output.rst -t rst
MCP Server Integration
This skill is foundational and integrates with:
Server
Description
Usage
All documentation MCP servers
Markdown is universal output
Rendering and validation
Best Practices
Document Structure
# Document Title> Brief description or abstract## Table of Contents
<!-- toc -->
## Introduction
Overview and context...
## Main Content### Subsection 1
Content...
### Subsection 2
Content...
## Conclusion
Summary and next steps...
## References- [Reference 1](url)
- [Reference 2](url)
## Appendix
Additional information...
Markdown Style Guide
style_rules:headings:-"Use ATX-style headings (#)"-"One H1 per document"-"Don't skip heading levels"lists:-"Use - for unordered lists"-"Use 1. for ordered lists"-"Indent with 2 spaces"code:-"Use fenced code blocks with language"-"Use inline code for short references"links:-"Use reference-style links for repeated URLs"-"Add meaningful link text"images:-"Always include alt text"-"Use relative paths for local images"
Accessibility
<!-- Good: Descriptive alt text -->
<!-- Good: Descriptive link text -->
See the [installation guide](./install.md) for setup instructions.
<!-- Bad: Non-descriptive -->
Click [here](./install.md).
Process Integration
This skill integrates with ALL documentation-generating processes:
c4-model-documentation.js - Architecture docs
adr-documentation.js - Decision records
api-design-specification.js - API documentation
All other documentation processes
Output Format
When processing documents, provide structured output:
{"operation":"process","status":"success","document":{"path":"./docs/architecture.md","title":"Architecture Overview","wordCount":1234,"headings":15,"codeBlocks":8,"diagrams":3},"toc":{"generated":true,"items":12,"maxDepth":3},"links":{"total":25,"internal":18,"external":7,"broken":0},"frontmatter":{"valid":true,"fields":["title","date","author","tags"]},"diagrams":{"mermaid":2,"plantuml":1,"valid":true},"artifacts":["architecture.md","architecture.html"],"warnings":["Line 45: Image missing alt text"],"errors":[]}
