// Convert ClickHouse blog content into docs pages. Use when porting a feature announcement, tutorial, or deep-dive from the blog into the docs site. Covers content extraction, asset handling, structural transformation, and voice conversion.
Review a docs PR from someone else. Triage issues by severity, draft comments with rationale, and focus on what matters. Use when reviewing a PR, not when checking your own work (use docs-pre-ship-review for that).
Voice, style, and content rules for writing ClickHouse docs. Use when drafting new pages, rewriting sections, or applying editorial polish. Covers identity, voice, pacing, sentence habits, anti-patterns, AI-ism removal, prose tightening, editorial instinct, linking, keywords, content integrity, and marketing site alignment.
Review a ClickHouse docs page before shipping. Runs the self-review checklist, Vale linting, and PR review rubric. Use when doing a final check, running Vale, or when asked "is this ready to ship."
| name | blog-to-docs |
| description | Convert ClickHouse blog content into docs pages. Use when porting a feature announcement, tutorial, or deep-dive from the blog into the docs site. Covers content extraction, asset handling, structural transformation, and voice conversion. |
Convert blog posts (or blog sections) into docs pages. Blog content is marketing-adjacent and narrative; docs content is task-oriented and scannable. This skill covers the transformation process.
Fetch the blog URL and extract all content from the relevant section. Request verbatim content, not a summary — you need every detail to avoid losing information during the conversion.
After extraction, build an exhaustive numbered checklist of every distinct technical claim, fact, setting, default value, behavioral detail, caveat, and recommendation in the blog. This is the source-of-truth inventory — you will check every item against the docs later in step 8. Don't summarize; enumerate.
Download all images and videos from the blog to
static/images/clickstack/<feature-name>/ (or the appropriate path).
Images: Download as .png or .jpg. Name descriptively
(service-map-overview.png, not screenshot-1.png).
Videos: Download .mp4 files. Keep them — MP4 at ~1MB is far better
than converting to GIF (which would be 5-15x larger and lower quality).
Import pattern: Import assets as webpack modules, not static paths.
Static paths (/images/...) don't work reliably with the dev server.
// Images — use IdealImage
import Image from '@theme/IdealImage';
import overview from '@site/static/images/clickstack/feature/overview.png';
<Image img={overview} alt="Description" size="lg"/>
// Videos — import as module, self-closing tag
import demo from '@site/static/images/clickstack/feature/demo.mp4';
<video src={demo} autoPlay loop muted playsInline width="100%" />
Do NOT use:
<!-- Static path — won't work in dev server -->
<video src="/images/clickstack/feature/demo.mp4" ... />
<!-- Nested source tag — doesn't render in MDX -->
<video>
<source src={demo} type="video/mp4" />
</video>
Before writing, read 2-3 sibling pages in the target directory. Match:
This is the critical transformation. Blog posts explain and narrate; docs pages orient and instruct.
Blog patterns to eliminate:
Docs patterns to apply:
Example transformation:
Blog structure (5 sections):
- Intro
- Accessing service maps
- Reading the map
- Controls
- How it works
Docs structure (2 sections):
- Intro (what it is + how it works + where to find it + prereqs)
- Exploring the service map (nodes, edges, controls — all in one)
- Trace-level service maps (the contextual variant)
Blog posts often use third person, marketing language, and narrative framing. Convert to docs voice per the docs-drafting skill:
The blog is the source of truth for technical claims. Don't weaken or second-guess what the blog says about how the feature works — but do strip the marketing wrapper.
Check sibling pages for how they mark beta features. Don't use :::note
admonitions for beta status — use the <BetaBadge/> component if that's
what siblings use.
import BetaBadge from '@theme/badges/BetaBadge';
<BetaBadge/>
Add the page to sidebars.js in the appropriate position. Check the
logical ordering relative to sibling pages.
After drafting, go back to the numbered checklist you built in step 1. Check every item against the current state of the docs — not just your draft, but also existing pages that may already cover it. For each item, mark one of:
Present the results as a coverage table. Every item must be accounted for. Don't move on until there are zero gaps.
Generalizable technical content must be moved. Every piece of technical guidance in the blog — commands, configuration, process steps, caveats, edge cases — belongs in the docs unless it is customer-specific.
Do not move customer-specific benchmarks or metrics. Performance numbers, resource comparisons, and before/after metrics from a specific customer deployment read as marketing in technical reference docs, imply universal applicability they don't have, and belong in the blog only. The test: would this number be true for a different customer on different hardware? If not, leave it in the blog.
Apply the docs-drafting skill for voice/style, then the docs-pre-ship-review skill before shipping. These are separate passes.
When linking to another docs page, the link text should describe what the reader will find at that destination — not the concept you're discussing.
If you have UI screenshots for controls or settings, use them instead of (or alongside) a description table. A table of control names and descriptions without visuals feels hollow. Individual screenshots with a one-line description are more useful:
**Source selector** — filter the map to a specific trace source.
<Image img={source_selector} alt="Source selector in toolbar" size="lg"/>
Before committing, check the asset directory for unused files (screenshots
with default names, duplicates, .DS_Store). Clean them up.