dsh-plugin-md-outline

> 🇨🇳 中文文档  |  🇺🇸 English

A minimal but practical DeepSeek Harness plugin that adds an md_outline tool. It outlines and lints Markdown documents: a nested heading tree plus structural warnings that are tedious to check by hand and easy to get wrong in long docs (book drafts, skill sets, specs).

> Topic: dsh-plugin — add this topic to the GitHub repo so the ecosystem > can discover it (see [Publishing the dsh-plugin topic](#publishing-the-dsh-plugin-topic) below).

What it does

Preview

Terminal preview from node examples/run.mjs (covers all 5 sample docs — clean, level skip, duplicate headings, multiple H1, unclosed fence):


What a bad doc looks like — examples/level-skip.md

The left side is the source as written; the right side is what md_outline reports. The H1 → H3 jump on line 3 is flagged with line number and reason.


To regenerate: python3 docs/gen_screenshot.py (writes docs/screenshot.png).

Install

One-click install (any machine, any profile):

dsh plugin add https://github.com/d-ouyang/dsh-plugin-md-outline.git
dsh --profile demo --dump-config | grep -i md-outline   # confirm the layer is present

Requires the dsh CLI (DeepSeek Harness). This plugin is plain ESM JavaScript: no build step, no allowBuilds prompt, installs straight from a git repo.

Local checkout also works:

dsh plugin --profile demo add /path/to/dsh-plugin-md-outline

To remove:

dsh plugin remove dsh-plugin-md-outline

Usage

In the Web UI (or any surface with tools), just ask the model:

> Outline ~/book/draft.md and tell me about structural issues.

Or call it directly in Code Mode:

await tools.md_outline({ path: '~/book/draft.md', mode: 'both' })
await tools.md_outline({ path: '~/skills', mode: 'lint', recursive: true })
await tools.md_outline({ path: '~/notes/spec.md', mode: 'outline', maxDepth: 2 })

Parameters

| Name | Type | Required | Notes | |---|---|---|---| | path | string | yes | A .md/.markdown/.mdx file, or a directory. | | mode | 'outline' \| 'lint' \| 'both' | no | Default both. | | maxDepth | number (1–6) | no | Limit outline nesting. | | recursive | boolean | no | Scan subdirectories when path is a dir (default true). |

The canonical return value is structured ({ files, summary }) for programmatic use in Code Mode; the model-facing card shows the human-readable summary.

How it is built (cookbook recap)

This plugin follows the official authoring path:

1. Tool contract — docs/user/develop/basic/tool.md and docs/cookbook/adding-a-tool.md: defineTool({ name, description, parameters, output, execute }) registered via ctx.tools.register(...). 2. Bundle packaging — docs/user/develop/basic/publish.md: a bundle is an npm package with a dsh.bundle manifest and a cordis.patch.yml layer that inserts the plugin row by package name. 3. No build — written in plain ESM JavaScript so a github: install loads without running any prepare script.

dsh-plugin-md-outline/
├── package.json        # dsh.bundle manifest + peer dep on @deepseek-ai/dsh-tools
├── cordis.patch.yml    # the layer applied when a profile adds this bundle
├── index.js            # plugin entry: name / inject / apply -> registers md_outline
├── md-outline-core.js  # pure, dependency-free analysis (unit-tested)
├── test.mjs            # `node test.mjs` validates the core logic
├── examples/           # sample docs + run.mjs (real output shown in docs/USAGE.md)
├── docs/USAGE.md       # 🇨🇳 full usage guide with real test results
├── README.md
└── README.zh-CN.md

Develop

node test.mjs                 # unit-test the pure logic
node examples/run.mjs         # run all sample docs and print real outlines + warnings
node --check index.js        # syntax check the plugin entry

See [docs/USAGE.md](docs/USAGE.md) (中文) for the full usage guide and real test output.

The runtime contract depends on @deepseek-ai/dsh-tools being present in the dsh installation (it is — the harness itself uses it). Declared as a peerDependency, so it is never fetched from a registry.

Publishing the dsh-plugin topic

The dsh-plugin GitHub topic is what makes community plugins discoverable. Add it in repo Settings → Topics, or via the API once the repo exists:

# after `git push`, set the topic through the GitHub API (needs a token)
curl -X PUT -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/d-ouyang/dsh-plugin-md-outline/topics \
  -d '{"names":["dsh-plugin","markdown","deepseek-harness"]}'

License

MIT