markdown-pro
Markdown authoring and processing — flavors, linting, conversion, and docs pipelines — use when writing or transforming Markdown.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- markdown-pro
- category
- document-processing
- description
- Markdown authoring and processing — flavors, linting, conversion, and docs pipelines — use when writing or transforming Markdown.
03 SKILL.md 正文
Overview
Markdown is the default writing format for docs, READMEs, and increasingly for LLM-facing content. But "Markdown" is a family of flavors (CommonMark, GFM, MDX), and real pipelines need linting, link checking, and conversion. This skill covers writing portable Markdown and building reliable Markdown toolchains.
When to use
- Writing documentation, READMEs, or knowledge-base content
- Choosing between CommonMark, GitHub Flavored Markdown, and MDX
- Linting Markdown and enforcing style in CI
- Converting Markdown to/from HTML, PDF, DOCX, or other formats
- Building docs sites or processing Markdown programmatically (AST)
Core concepts
Write to the common subset. Tables, task lists, footnotes, and admonitions are extensions, not core Markdown. If your content must render on GitHub, a docs site, and an LLM context window, stick to headings, lists, code fences, links, images, emphasis, and blockquotes — the portable core.
Flavors matter at the edges. GFM adds tables, strikethrough, task lists, and
autolinked URLs. MDX adds JSX components (powerful, but locks you into a
JS toolchain). Know which flavor your renderer supports before using extension
syntax — a :::note admonition renders as literal text on GitHub.
AST-based processing beats regex. For programmatic transforms (rewriting links, extracting headings, injecting TOCs), parse to an abstract syntax tree and manipulate that. Regex over Markdown breaks on nested constructs, code fences containing Markdown-like text, and reference-style links.
Frontmatter is metadata. YAML frontmatter (--- block) carries title,
date, tags, and layout hints. Validate it with a schema — untyped frontmatter
drifts (dates as strings vs dates, tags as string vs list) and breaks builds.
Line length and formatting. Enforce a formatter (consistent list markers, fenced code languages, trailing newline) so diffs stay clean and CI can check style mechanically.
Practical workflow
- Pick the flavor for the target renderer(s); document the choice so contributors don't use unsupported syntax.
- Structure with headings: one
#title, hierarchical##/###, no skipped levels — this drives TOCs, anchors, and screen-reader navigation. - Lint in CI: a Markdown linter with a checked-in config catches inconsistent style, missing code-fence languages, and broken relative links.
- Check links: run a link checker on internal and external links; external links rot — prefer permalinks and archive critical references.
- Convert via a real engine (Pandoc-style) for Markdown → PDF/DOCX/HTML, with a checked-in template/CSS so output is styled consistently.
- For programmatic pipelines: parse → AST → transform → serialize; keep the pipeline's Markdown subset documented and tested with fixture files.
Common pitfalls
- Flavor-specific syntax in "portable" docs — admonitions, math, and directives silently render as garbage outside their home renderer.
- Huge single files — split long docs into chapters with an index page; giant files are unsearchable and murder diffs.
- Images without alt text or with absolute local paths — breaks accessibility and portability; use relative paths and meaningful alt text.
- Linking to headings that get renamed — anchor links rot when headings change; some pipelines validate them, most don't.
- Tabs vs spaces in nested lists — inconsistent indentation renders differently across renderers; let the formatter own it.
- Putting generated content in hand-edited files — generated TOCs, changelogs, and API tables belong in build steps, not in files humans edit.
04 同仓库更多 Skills
web-scrape
Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.
design-taste-frontend
tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
requesting-code-review
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
brainstorming
You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).