Documentation

The source code of the Tenzir documentation is at https://github.com/tenzir/docs. We use Astro with Starlight as our site framework.

Quick Reference

Essential Commands

Command	Action
pnpm install	Install dependencies
pnpm dev	Start local dev server at localhost:4321
pnpm build	Build production site to ./dist/
pnpm preview	Preview build locally before deploying
pnpm generate:changelog	Sync changelog from tenzir/news
pnpm generate:docs-map	Generate documentation map for AI agents
pnpm generate:excalidraw	Convert .excalidraw diagrams to SVG

Development Commands

Command	Action
pnpm lint:markdown	Lint all Markdown files
pnpm lint:prettier	Check code formatting
pnpm build:linkcheck	Validate all internal and external links
pnpm astro ...	Run CLI commands like astro add, astro check
pnpm astro -- --help	Get help using the Astro CLI

For anything beyond editing Markdown content, check out Starlight’s docs or read Astro’s documentation.

For git workflow, branching strategy, and commit message conventions, see our Git and GitHub Workflow guide.

Local Development

First-Time Setup

1. Clone the repository:

   git clone https://github.com/tenzir/docs.git
   cd docs

2. Install dependencies:

   pnpm install

3. Start development server:

   pnpm dev

4. View the site: Browse to http://localhost:4321/

The development server includes:

• 🔥 Hot module reloading for instant updates
• 📝 Live Markdown rendering
• 🔍 Error reporting in the browser

Production Build

Create and preview a production build:

# Build the site
pnpm build

# Preview the build
pnpm preview

Then browse to http://localhost:4321/ to view the production site.

CI/CD Pipeline

Production builds are automatically created in CI. Check out our GitHub workflow for implementation details.

Link Checking

The documentation includes automated link validation to ensure all internal and external links work correctly:

Local Link Checking

Before submitting changes, run link checking locally to catch broken links:

pnpm build:linkcheck

This will build the site with link validation enabled and report any broken links found.

CI Integration

Link checking runs automatically in our CI pipeline:

• All builds: Link validation is enabled for production builds
• Pull requests: Link checking runs as part of the lint workflow
• Scheduled maintenance: Weekly link checks run every Sunday to catch broken external links

How It Works

The link checker validates:

• Internal page references (e.g., /guides/quickstart)
• Anchor links within pages (e.g., /reference/operators#aggregate)
• External URLs (with appropriate timeout and retry logic)
• Relative links between documentation files

Fixing Broken Links

When the link checker finds issues:

1. Invalid internal links: Update the link to point to the correct page path
2. Missing anchor references: Ensure the target heading or element exists
3. Broken external links: Update URLs or remove outdated references
4. False positives: Add exclusions to the starlightLinksValidator configuration in astro.config.mjs

The link checker will cause builds to fail if broken links are detected, ensuring the documentation maintains high quality.

Optimize Images

To keep the repository size manageable, always optimize image files before committing them. This is especially important for formats like PNG, which can contain unnecessary metadata or use inefficient compression.

PNG Images

We recommend using pngquant, a command-line utility for lossy compression of PNG files. It significantly reduces file size while preserving image quality.

To compress a PNG file in-place:

pngquant --ext .png --force --quality=65-80 image.png

JPEG Images

Use jpegoptim, a utility for optimizing JPEGs without perceptible quality loss:

jpegoptim --strip-all --max=80 image.jpg

Alternatively, you can use mozjpeg for even better compression ratios.

SVG Images

Use svgo, a Node-based tool to optimize SVG files by removing unnecessary data:

svgo image.svg

This automatically rewrites the file in-place with redundant code removed and optimized structure.

Edit Diagrams

We use Excalidraw as primary tool to create sketches of architectural diagrams.

Creating New Diagrams

For new diagrams, save the .excalidraw source file directly in the content directory alongside your markdown:

1. Create your diagram in Excalidraw (use light mode)
2. Save as diagram-name.excalidraw in the same directory as your markdown file
3. Reference it in markdown: ![Alt text](diagram-name.excalidraw)
4. Run pnpm generate:excalidraw to generate the SVG

The build process converts .excalidraw files to .excalidraw.svg and inlines them directly into the HTML. This enables automatic dark mode support via CSS.

Generated .excalidraw.svg files are gitignored—only the .excalidraw source files are tracked.

Don’t commit exported SVGs

Always commit .excalidraw source files, not exported SVGs. Source files are editable, diffable, and the build generates optimized SVGs automatically.

AI-assisted diagramming

Our Excalidraw Claude plugin enables Claude to create and edit .excalidraw files directly. This is useful for generating diagrams from descriptions or making quick edits without leaving your editor.

Editing Existing SVGs

Some older diagrams exist only as exported SVGs. When exporting Excalidraw scenes manually, always use light mode and choose SVG as export format, as we have CSS in place that automatically inverts colors so diagrams look nice in dark mode.

Tenzir developers have access to our Excalidraw Documentation collection. For everyone else, please reach out to us on our Discord server to request changes to existing SVGs.

Writing Style and Formatting

This section covers the editorial and technical standards for contributing to the Tenzir documentation.

Writing Guidelines

We follow the Google Style Guide for clear and consistent technical documentation. Most notably:

• Use active voice in general.
• Avoid anthropomorphic language—don’t attribute human qualities to software or hardware.
• Include definite and indefinite articles (a, an, and the) in your writing. Don’t skip articles for brevity, including in headings and titles.
• In document titles and headings, use sentence case. Capitalize only the first word in the title, the first word in a subheading after a colon, and any proper nouns or other terms that are always capitalized a certain way.
• Capitalize product names.
• Write documentation in an informal tone—use common two-word contractions such as “you’re,” “don’t,” and “there’s.”
• Define technical terms and acronyms on first use. Don’t assume readers know specialized vocabulary.
• Put the most important information first. Don’t bury key details in the middle of paragraphs.
• Use consistent terminology throughout. Don’t use different words for the same concept (e.g., don’t alternate between “node” and “instance”).
• Avoid unclear pronouns like “it,” “this,” or “that” without clear antecedents. Be explicit about what you’re referring to.
• Choose strong, specific verbs over weak ones. Use “use” instead of “utilize,” “help” instead of “facilitate,” and “show” instead of “demonstrate.”
• Eliminate redundant phrases. Write “to” instead of “in order to,” “now” instead of “at this point in time,” and “because” instead of “due to the fact that.”
• Avoid vague qualifiers like “simply,” “just,” “easily,” or “obviously.” These don’t add clarity and may frustrate readers who find the task difficult.
• Provide context for why something matters. Don’t just explain what to do— explain when and why to do it.
• Use hyperlinks judiciously. Link to external tools, products, or resources when first mentioned, but avoid overlinking within the same document.

Formatting Standards

Follow these conventions to maintain consistency across all documentation files.

General

• Every file must end with a newline character, but avoid empty lines at the end of a file.

Markdown Content

• Break lines at 80 characters.
• When editing Markdown, run pnpm lint:markdown:fix and pnpm lint:prettier:fix when you’re done.

Code

• Avoid empty lines within functions.
• When editing source code (.js, .jsx, .ts, .tsx, .astro files), run pnpm lint:eslint:fix when you’re done.