doc-snippets
Keep Markdown code examples under docs/**/*.md in sync with real source via snips, and write manual-testing instructions for onboarding guides. Use when adding/editing a doc that embeds source code or tells the reader how to try a server, when `make docs-check` fails, or when source behind an existing snippet marker changed.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 39
- Forks
- 14
01 前言 Front Matter
- name
- doc-snippets
- metadata
- { "author": "Konstantin Pavlov", "version": 1.1 }
- description
- Keep Markdown code examples under docs/**/*.md in sync with real source via snips, and write manual-testing instructions for onboarding guides. Use when adding/editing a doc that embeds source code or tells the reader how to try a server, when `make docs-check` fails, or when source behind an existing snippet marker changed.
03 SKILL.md 正文
Doc snippets (snips)
snips links a Markdown code block to real source so docs can't silently drift.
Requires Rust/cargo; Install locally: cargo install snips.
Commands
make docs-check # snips --check — CI-style, non-zero if any doc is stale
make docs-sync # snips — rewrite stale snippets from source, then restore java/kotlin/json fence tags
snips --diff <file.md> # preview what sync would change, no write
snips --quiet <file.md> # sync without output
make docs-check runs as part of make all. snips 0.0.6 options: --check, --diff, --quiet.
Marker syntax
Named snippet — wrap the block in source with snips-start: <name> / snips-end: <name>
comments (any language's comment syntax), then reference it in Markdown with an HTML
comment right before the fenced code block:
// snips-start: main_feature
println!("hello");
// snips-end: main_feature
<!-- snips: examples/example.rs#main_feature -->
```rust
println!("hello");
```
- Whole-file:
<!-- snips: path/to/File.java -->embeds the entire file, including anysnips-start/snips-endcomment lines it contains. - Paths resolve relative to the Markdown file, not the working directory.
- Named snippets and whole-file are the only marker kinds in snips 0.0.6..
snips rewrites the fence's language tag to the CodeMirror mode of the source file: clike
for Java and Kotlin, javascript for JSON. GitHub and the docs site don't highlight those.
make docs-sync runs .github/scripts/fix-doc-fences.py after snips to restore java,
kotlin and json; snips --check ignores the tag. After a bare snips run, rerun
make docs-sync instead of committing clike fences.
Workflow
- Writing a doc with a code example that exists in source (or vice versa): wrap the
source lines in
snips-start/snips-end, then replace the Markdown fenced block with the<!-- snips: ... -->marker + a fence (content gets filled on sync). make docs-syncto populate it, review the diff, commit both the marker and the generated content.- Source changes later →
make docs-checkcatches drift (fails the build);make docs-syncfixes it.
Where the examples live
Java and Kotlin code blocks in docs/ come from examples/doc-examples (see its README):
compiled against the published Tachyon release, with a test per example that runs it on a
port-0 server and asserts what the page claims.
- Package per page:
docs/<dir>/<page>.md→dev.tachyonmcp.docs.<dir>.<page>(hyphens dropped);_index.md→dev.tachyonmcp.docs.<dir>;docs/<page>.md→dev.tachyonmcp.docs.<page>. - Marker path from a doc:
../examples/doc-examples/src/main/java/dev/tachyonmcp/docs/<page>/Foo.java#name(one more../per directory level underdocs/). - Put
packageabovesnips-start; imports and the class go inside the snippet. Fragments sit in a method whose parameters supply the context, so the doc text compiles unchanged. - For a block that is a whole example (not a one-line fragment), link its source file inline in
the lead-in sentence:
Create `Foo.java` ([source](https://github.com/tachyonmcp/tachyon/blob/main/<repo path>)):, the sameblob/mainform the docs already use. - snips takes only the first region when a name repeats, so a block mixing top-level types with a builder call is two snippets in two fences. Imports can't sit inside a fragment: name their packages in the prose.
- Gradle build files come from
examples/doc-examples/kotlin-gradle/build.gradle.kts; itsbuildSrcdefinestachyon.versionso the embedded text keeps the docs'${tachyon.version}placeholder. Verify withgradle run(Gradle 8.14.3, JDK 21); the Maven build does not run it. - A doc claim that the code contradicts is a doc bug: fix the doc, don't bend the test.
- Build files and shell blocks (
${tachyon.version}placeholders) stay inline; the SNAPSHOT switch is the commentedtachyon.versionline in the module pom. - Reference page:
docs/quickstart.md→quickstart/MyMcpServer.java+MyMcpServerTest.java.
Manual-testing instructions
- For manual testing in onboarding guides, lead with MCP Inspector; retain curl as an alternative.
- Use HTML
<details>with descriptive<summary>labels for alternative instructions and long setup blocks. Open the recommended testing path with<details open>; keep alternatives collapsed. Leave blank lines around fenced Markdown inside the elements and check the rendered Hugo page. - Give the launch command, transport, endpoint, tool arguments, and expected result. Verify Inspector commands and UI labels against its official repository, and ground Tachyon behavior in source and existing tests.
- For Inspector CLI examples, use
--tool-args-jsonto preserve types and--format jsonfor parsed output. Follow the CLI smoke-testing guide for automation: pin the Inspector version, bound connection time, and preserve failing exit codes.
Gotchas
- Keep
snips-starton the line directly above the first snippet line andsnips-enddirectly below the last. A blank line inside the markers becomes a blank first or last line in the doc. snipswith no file args processes.mdand.markdownfiles in the current directory only (not recursive) — that's why the Makefile targets pass an explicitfind docs -name '*.md'file list (scoped todocs/) instead of relying on the default.- A stale snippet doesn't error at doc-write time — only
--checkcatches it, so it's only as good as CI/make allactually runningdocs-check.
04 同仓库更多 Skills
greeting
Greet the user by name
pdf-processing
Extract, fill, and assemble PDF documents
read-file
How to read a file
git-workflow
Follow this team's Git conventions for branching and commits
elvish-magic
Compose gentle, fictional Elvish spells for light, water, and growing things
elvish-healing
Create gentle, fictional Elvish remedies for fantasy stories and games