Authoring guide

The one rule

Content updates are Pages deploys, never plugin releases. A typo fix, a new troubleshooting entry, a whole new section — push to the site, done. If you find yourself wanting a plugin release to fix documentation, the content is in the wrong place.

Adding a topic

1. Create a markdown file under help-site/content/{area}/ — numeric prefixes (3.dt-resync.md) control sidebar order and are stripped from URLs.
2. Frontmatter: title and description are required (they render the page header and feed search). Optional: minPluginVersion (version gating) and openQuestions (unverified claims to resolve before tightening prose).
3. The URL contract is frozen. New pages are fine; renaming or moving an existing page requires a 301 in public/_redirects — the plugin embeds deep links in error messages and palette help affordances.

Find markers

Point a topic at the live ribbon with an inline marker:

On the ribbon: **JobEngine → Palette → Knowledge Base** :find{target="ACADDT_TGL_KB" label="Knowledge Base"}

• target must be a pinned ribbon id from content/_data/ribbon-ids.json — bun run test fails on unknown ids. Refresh the snapshot from UI/Ribbon/RibbonDefinitions.cs when the ribbon changes.
• Markers render nothing for readers without a connected AutoCAD session, so author them freely.

Voice

• Engineer-facing, plain language. No internal jargon: no track ids, no decision numbers, no repo paths in published copy.
• Plugin messages quoted verbatim where possible (engineers paste error text into search).
• One to two failure modes per command page; exhaustive message coverage belongs in troubleshooting.

Screenshots

PNG, dark theme, 2× DPI, under public/img/{area}/. Crop to the relevant control plus enough context to find it.