Documentation

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

TL;DR: Here’s a summary about frequently used commands:

Command	Action
pnpm install	Installs dependencies
pnpm dev	Starts local dev server at localhost:4321
pnpm build	Build your production site to ./dist/
pnpm preview	Preview your build locally, before deploying
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.

Develop and View Locally

To view the docs site locally, you must first the needed dependencies:

pnpm install

Thereafter, build a development version of the docs:

pnpm dev

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

Build for Production

Create a production build as follows:

pnpm build

Preview the generated files by spinning up a web server:

pnpm preview

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

We create a production build in CI. Check out our GitHub workflow for the gory 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 lint: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.

Auto-Updated Files

Important: Some files in this repository are automatically updated by CI and should never be manually edited. Manual changes to these files will be overwritten the next time the update workflow runs.

Automatically Updated Files

The following files are synchronized from upstream repositories:

Tenzir Node Documentation:

• src/content/docs/changelog/node is generated from individual changelog entries
• src/content/docs/reference/functions is synced from tenzir/tenzir at docs/functions/
• src/content/docs/reference/operators is synced from tenzir/tenzir at docs/operators/
• src/content/docs/reference/functions.mdx is generated from individual function files
• src/content/docs/reference/operators.mdx is generated from individual operator files
• src/sidebar-reference.js is generated from individual function and operator files for programmatic sidebar navigation
• src/content/apis/openapi.node.yaml is the API specification for Tenzir Node and generated from the node’s source code
• tenzir.yaml.example is the node’s example configuration file

Tenzir Platform Documentation:

• src/content/docs/changelog/platform is generated from individual changelog entries
• src/content/docs/reference/platform-cli.mdx is synced from tenzir/platform at docs/platform-cli.mdx

Making Changes to Auto-Updated Content

If you need to update content in these files:

1. For Functions/Operators: Make changes in the tenzir/tenzir repository
2. For Platform CLI: Make changes in the tenzir/platform repository
3. For generation logic: Modify the scripts in scripts/ or the update workflow

Our CI will automatically prevent pull requests that modify auto-updated files. If you encounter this error, revert your changes and make them in the appropriate upstream repository instead.

Edit Diagrams

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

When exporting Excalidraw scenes, always use light mode and choose SVG as export format, as we have some CSS magic in place that automatically inverts colors SVGs so that they also look nicely when using 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.