Speckle Docs – Authoring Guide

This repository contains the official documentation for Speckle. The goal is to make our docs clear, consistent, and useful for both new and experienced users.

Canonical doc rules for AI assistants live in AGENTS.md (always on) and the docs/agents/ docs it lists; agent skills live in agents/skills/ (see Agent config below).

Structure & Style

• Quick Reference A concise entry point for essential actions and terminology. Designed to give new users a fast orientation and provide experienced users with a rapid lookup.

• Your Speckle Workspace Guides that explain how to set up and manage workspaces, projects, and models. These are deliberately briefer than connector docs, focusing on universal web application features that every user touches. To balance brevity, they are supported with FAQs, best practices, and tips.

• Viewing & Sharing Instructions on how to explore models, create saved views, apply filters, and share data with others. Emphasis is on clarity and speed to first success, with optional callouts for tips and best practices.

• Publishing & Loading (formerly Connectors) Each connector follows the same skeleton: installation, sign-in, day-0 tasks (send/receive), followed by FAQs and troubleshooting.

  We deliberately describe this section as Publishing & Loading rather than "Connectors." This keeps the docs user-first and purpose-driven: users think in terms of publishing data into Speckle or loading it into another tool, not in terms of underlying plumbing. It frames the outcome (why) rather than the mechanism (how).

  Connector Documentation Structure:

  • Use main page sections for step-by-step guides (e.g., "Setting up Data Gateway")
  • Use accordions for FAQs and troubleshooting questions
  • Import and use standard components: <Setup>, <Load>, <Publish>, <SetupFaq>, <LoadFaq>, <PublishFaq>
  • Avoid "How to do X" accordion titles that contain step-by-step instructions—these should be main sections instead

Tone

• Direct, simple, and jargon-light.
• Instructions are imperative (“Click…”, “Select…”, “Run…”).
• Visual where possible: screenshots, diagrams, or short clips.

FAQs, Best Practices, and Tips

• FAQs: Maintained as the first stop for common issues and questions. They should be phrased in user language, short and atomic, and cover both obvious and edge-case scenarios. Use accordions for FAQs—they should answer specific questions, not provide step-by-step guides.
• Best Practices: Principles and recommendations that help users avoid pitfalls and make good choices. They should read as guidance, not rigid rules.
• Tips & Tricks: Small, optional enhancements or shortcuts. Presented as quick callouts, not workflows, and always optional to the main path.

When to use accordions vs. main sections:

• Accordions: For FAQs, troubleshooting questions, and quick reference information
• Main sections: For step-by-step guides, detailed procedures, and comprehensive workflows

Guardrails

• Keep tutorials separate. Tutorials are narrative, multi-step guides that live outside the core docs.
• Docs should remain reference-driven: quick answers, reproducible steps, clear explanations.

Balance Across Sections

Connector pages are naturally more detailed because they must cover multiple host tools, installation steps, and technical caveats. User guides, by contrast, should remain concise and focused on universal actions, but must be reinforced with FAQs, best practices, and tips to feel equally rich. This balance avoids the perception that non-connector content is “thin” by design, while still keeping it accessible.

How We Measure Quality

• Can a new user follow a page and succeed on day 0?
• Can an experienced user land on a page, scan for the answer, and leave in under a minute?
• Are FAQs current and accurate?
• Are best practices and tips useful without being prescriptive?

Note for Contributors

Development

• Ensure you have Node.js 22.17.1 or newer within the 22.x line installed (matching the engines field in package.json).
• pnpm install to install dependencies
• pnpm dev to start the local dev server

PR checks (CI)

Pull requests run .github/workflows/docs-pr-checks.yml as parallel jobs:

• Format and lint — pnpm format:check:changed + pnpm lint:md:changed (PR files only; blocking)
• Mintlify validate — pnpm valid (full site; blocking)
• Broken links — pnpm check-links (anchors + redirects + Snippet links; full site; blocking)
• Missing assets — pnpm check:assets (local image and download files; blocking)
• Structure — redirects, orphans, image framing (blocking)
• Accessibility — pnpm check:a11y (mint a11y; full site; blocking)
• Image placeholders — pnpm report:placeholders (outstanding {/* IMAGE_PLACEHOLDER: … */} comments; informational, always green)

Require the blocking jobs on main:

bash scripts/enable-required-pr-checks.sh

(Needs gh auth login with repo admin.) Or set branch protection manually to require status checks Mintlify validate, Broken links, Format and lint, and Accessibility.

Scheduled / manual (.github/workflows/docs-scheduled-checks.yml):

• External links — pnpm check-links:external (flaky; not on PRs)
• Agent readiness score — mint score when repo variable DOCS_SITE_URL is set

Pre-commit (format / lint)

After pnpm install, Husky installs a pre-commit hook that runs lint-staged on staged files only:

• Prettier --write — blocking (must format cleanly)
• markdownlint — blocking on staged markdown (same rules as CI changed-file lint)

Does not run validate, links, or a11y. Skip once: git commit --no-verify.

Locally (defaults match CI — changed files for format/lint):

pnpm check                 # same as check:changed (CI-equivalent)
pnpm check:format-lint     # Prettier + markdownlint on changed files only
pnpm check:validate        # Mintlify validate
pnpm check:links           # anchors, redirects, snippets
pnpm check:a11y            # accessibility
pnpm report:placeholders   # outstanding screenshot comments (not a gate)

Full-repo format/lint (not what CI runs on PRs):

pnpm check:all             # full-repo format/lint + validate + links + a11y
pnpm check:format-lint:all # Prettier + markdownlint on entire tree
pnpm lint:md:all           # markdownlint entire tree
pnpm format
pnpm lint:md:fix

Object-model drift checks (manual; not in CI because they read sibling checkouts in the speckle-atlas layout, $ATLAS_ROOT or ..):

pnpm check:bundle-spec             # relations.mdx names vs speckle-bundle-spec's rel_types catalog at origin/main (needs duckdb)
pnpm check:object-model-freshness  # pinned source files behind object-model facts still match origin/main
pnpm report:object-model-terms     # legacy glossary terms in next/ prose (not a gate)

All three take --checkout-root <path>; the two check: scripts take --warn-only. The workflow around them is the sync-object-model-docs skill.

Agent config

AGENTS.md is the always-on instruction file, read natively by Claude Code, Codex, Cursor and Grok. Area rules it points to live in docs/agents/, repo-local skills in agents/skills/<name>/SKILL.md. Edit those sources only.

In the standard layout (this repo cloned inside the speckle-atlas checkout, or ATLAS_ROOT set in mise.local.toml), mise run agents-sync — also run by the session-start hooks in .claude/settings.json, .codex/hooks.json and .omp/extensions/atlas-sync.js — copies the shared atlas skills and these local skills into the gitignored .claude/skills/ and .agents/skills/, writes .mcp.json / .codex/config.toml, and refreshes the shared block in AGENTS.md. Layout and opt-in MCP servers: ../atlas/agents/README.md.

Using doc rules in other AI tools

• ChatGPT / Claude (chat) / Copilot Chat: Paste the prompt seed below into Custom Instructions or your first message, or attach AGENTS.md. Optionally add at the top of the page you’re editing: <!-- style: mintlify components; FAQs=AccordionGroup; steps=no nested components -->

Prompt seed (paste once per session for tools that don't read AGENTS.md):

You are writing docs for Speckle. Follow the canonical rules in AGENTS.md and the docs/agents/ docs it lists for the area you edit.

Global: Mintlify components only; approachable, precise tone; short, imperative sentences; task-first; show outcomes; keep pages brief; visuals when they clarify; compact FAQ + best practices + 1–3 Tips; no tutorials in core docs; cross-link by user intent.

Steps: use <Steps> / <Step> for short sequences; verb-first titles; do not nest complex components; render callouts adjacent; fallback to ### + ordered list if needed.

FAQs: use <AccordionGroup> + <Accordion title="…">; answers are atomic; link out if longer; include an edge case.

Versioned snippets: when tabs or headings compare two releases, share one setup; only the changed call differs; tab titles use 2026.9 with no leading v.

Connectors: frame by purpose (publish/load), not connector names; H2 order = Install → Open and sign in → Publish → Load → Common tasks → FAQ → Troubleshooting → Known issues; add a header panel (versions, download, changelog); always show the web-app handoff.

Publishing Changes

Install our GitHub App to auto-propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.

Troubleshooting

• Mintlify dev isn’t running → Run mintlify install to re-install dependencies.
• Page loads as 404 → Make sure you are running in a folder with docs.json.

Optional: Using Devcontainers

This repository includes a Dev Container (Node 22, pnpm) aligned with CI and package.json.

• In VS Code / Cursor: Reopen in Container. The image builds, then pnpm install runs.
• Port 3333 is forwarded for the Mintlify preview.
• Mint comes from the project (pnpm install), not a global CLI baked into the image.

Start the preview with:

pnpm dev

Dev Containers are optional; useful for a consistent environment without managing Node or pnpm locally.