mdx-to-markdown

Name: mdx-to-markdown
Author: rstackjs

84stars1forks

How to install mdx-to-markdown?

rstackjs/agent-skills/mdx-to-markdown

$npx -y skills add rstackjs/agent-skills --skill mdx-to-markdown

Installs into the current project.

Summary

Convert .mdx to portable .md, cleaning MDX components, anchors, code titles, table-of-contents links, and root-relative docs links.

Files · 1

View on GitHub

SKILL.md

1	# MDX to Markdown
2
3	## Overview
4
5	Use this skill to produce plain Markdown from MDX without requiring the target renderer to understand MDX imports, JSX components, Rspress anchors, or code-block metadata.
6
7	## Workflow
8
9	1. Identify the source `.mdx` and target `.md` path. If the user gives only a source path, default the output to the same path with `.md`.
10	2. Inspect the MDX for non-Markdown constructs:
11	- YAML frontmatter.
12	- top-level `import` lines.
13	- custom components such as `<BlogAuthors />` and `<PackageManagerTabs />`.
14	- heading anchors like `### Title \{#title}`.
15	- standalone HTML anchors like `<a id="title"></a>`.
16	- fenced code block titles such as a JavaScript fence with `title="env.js"`.
17	- HTML image wrappers such as centered `<div><img ... /></div>`.
18	3. Run the helper script when the requested conversion matches the default rules:
19
20	```bash
21	node /path/to/skills/mdx-to-markdown/scripts/convert_mdx_to_markdown.mjs input.mdx output.md
22	```
23
24	4. Review the result with `rg` and a short diff. Confirm that no MDX-only syntax remains.
25	5. Apply any user-requested follow-up edits, such as removing a generated table of contents or changing link policy.
26
27	## Default Conversion Rules
28
29	- Drop YAML frontmatter and top-level MDX imports.
30	- Remove `<BlogAuthors />`.
31	- Expand `<PackageManagerTabs command="add pkg -D" />` to a `bash` code block using `pnpm add pkg -D`.
32	- Convert centered HTML image blocks into Markdown image syntax.
33	- Remove Rspress heading anchor suffixes while keeping the heading text.
34	- Remove standalone `<a id="..."></a>` anchor lines.
35	- Remove table-of-contents links that target in-page anchors, preserving the list text.
36	- Convert code-fence titles or standalone bold filename captions into the first line of the code block as a comment, for example:
37
38	```js
39	// hello.js
40	export function greet(name) {
41	return `Hello, ${name}!`;
42	}
43
44	console.log(greet('world'));
45	```
46
47	- Convert code blocks that contain markers such as `// [!code highlight]` to `diff` code blocks, remove the marker, and prefix highlighted lines with `+`.
48	- Prefix Markdown links whose target starts with `/` using the current repository's site domain. Infer the product from the input file's Git repository, remote, package name, or path segment:
49	- `rspack` -> `rspack.rs`
50	- `rsbuild` -> `rsbuild.rs`
51	- `rspress` -> `rspress.rs`
52	- `rslib` -> `rslib.rs`
53	- `rsdoctor` -> `rsdoctor.rs`
54	- `rstest` -> `rstest.rs`
55	- Add `/zh` to the prefix when the MDX path contains a `zh` path segment. For example, a Chinese Rspack document converts `/guide/optimization/tree-shaking` to `https://rspack.rs/zh/guide/optimization/tree-shaking`.
56	- Use `--link-prefix <prefix>` only when the inferred domain is wrong or the user explicitly requests a custom prefix.
57
58	## Validation Checklist
59
60	Run targeted checks after conversion:
61
62	````bash
63	rg -n '<BlogAuthors\|PackageManagerTabs\|title="\|\\{#\|^<a id="\|\\]\(/\|!code highlight\|^\\[^]+\\*$' output.md
64	rg -n '^```' output.md \| wc -l
65	````
66
67	The first command should return no matches unless the user intentionally kept that syntax. The fence count should be even.
68
69	## Resources
70
71	- `scripts/convert_mdx_to_markdown.mjs`: deterministic converter for the common Rspack/Rstack release-blog MDX pattern.

People who liked this also viewed

6 picks

Type

find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 20262.6M27k
grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026633k182k
vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026573k29k
improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026522k182k
setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026454k182k
triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026424k182k

mdx-to-markdown

84stars1forks

View on GitHub

How to install mdx-to-markdown?

rstackjs/agent-skills/mdx-to-markdown

$npx -y skills add rstackjs/agent-skills --skill mdx-to-markdown

Installs into the current project.

Summary

Convert .mdx to portable .md, cleaning MDX components, anchors, code titles, table-of-contents links, and root-relative docs links.

Files · 1

View on GitHub

SKILL.md

1	# MDX to Markdown
2
3	## Overview
4
5	Use this skill to produce plain Markdown from MDX without requiring the target renderer to understand MDX imports, JSX components, Rspress anchors, or code-block metadata.
6
7	## Workflow
8
9	1. Identify the source `.mdx` and target `.md` path. If the user gives only a source path, default the output to the same path with `.md`.
10	2. Inspect the MDX for non-Markdown constructs:
11	- YAML frontmatter.
12	- top-level `import` lines.
13	- custom components such as `<BlogAuthors />` and `<PackageManagerTabs />`.
14	- heading anchors like `### Title \{#title}`.
15	- standalone HTML anchors like `<a id="title"></a>`.
16	- fenced code block titles such as a JavaScript fence with `title="env.js"`.
17	- HTML image wrappers such as centered `<div><img ... /></div>`.
18	3. Run the helper script when the requested conversion matches the default rules:
19
20	```bash
21	node /path/to/skills/mdx-to-markdown/scripts/convert_mdx_to_markdown.mjs input.mdx output.md
22	```
23
24	4. Review the result with `rg` and a short diff. Confirm that no MDX-only syntax remains.
25	5. Apply any user-requested follow-up edits, such as removing a generated table of contents or changing link policy.
26
27	## Default Conversion Rules
28
29	- Drop YAML frontmatter and top-level MDX imports.
30	- Remove `<BlogAuthors />`.
31	- Expand `<PackageManagerTabs command="add pkg -D" />` to a `bash` code block using `pnpm add pkg -D`.
32	- Convert centered HTML image blocks into Markdown image syntax.
33	- Remove Rspress heading anchor suffixes while keeping the heading text.
34	- Remove standalone `<a id="..."></a>` anchor lines.
35	- Remove table-of-contents links that target in-page anchors, preserving the list text.
36	- Convert code-fence titles or standalone bold filename captions into the first line of the code block as a comment, for example:
37
38	```js
39	// hello.js
40	export function greet(name) {
41	return `Hello, ${name}!`;
42	}
43
44	console.log(greet('world'));
45	```
46
47	- Convert code blocks that contain markers such as `// [!code highlight]` to `diff` code blocks, remove the marker, and prefix highlighted lines with `+`.
48	- Prefix Markdown links whose target starts with `/` using the current repository's site domain. Infer the product from the input file's Git repository, remote, package name, or path segment:
49	- `rspack` -> `rspack.rs`
50	- `rsbuild` -> `rsbuild.rs`
51	- `rspress` -> `rspress.rs`
52	- `rslib` -> `rslib.rs`
53	- `rsdoctor` -> `rsdoctor.rs`
54	- `rstest` -> `rstest.rs`
55	- Add `/zh` to the prefix when the MDX path contains a `zh` path segment. For example, a Chinese Rspack document converts `/guide/optimization/tree-shaking` to `https://rspack.rs/zh/guide/optimization/tree-shaking`.
56	- Use `--link-prefix <prefix>` only when the inferred domain is wrong or the user explicitly requests a custom prefix.
57
58	## Validation Checklist
59
60	Run targeted checks after conversion:
61
62	````bash
63	rg -n '<BlogAuthors\|PackageManagerTabs\|title="\|\\{#\|^<a id="\|\\]\(/\|!code highlight\|^\\[^]+\\*$' output.md
64	rg -n '^```' output.md \| wc -l
65	````
66
67	The first command should return no matches unless the user intentionally kept that syntax. The fence count should be even.
68
69	## Resources
70
71	- `scripts/convert_mdx_to_markdown.mjs`: deterministic converter for the common Rspack/Rstack release-blog MDX pattern.

People who liked this also viewed

6 picks

Type