Skip to content

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:

CommandAction
pnpm installInstalls dependencies
pnpm devStarts local dev server at localhost:4321
pnpm buildBuild your production site to ./dist/
pnpm previewPreview your build locally, before deploying
pnpm astro ...Run CLI commands like astro add, astro check
pnpm astro -- --helpGet help using the Astro CLI

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

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

Terminal window
pnpm install

Thereafter, build a development version of the docs:

Terminal window
pnpm dev

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

Create a production build as follows:

Terminal window
pnpm build

Preview the generated files by spinning up a web server:

Terminal window
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.

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

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

Terminal window
pnpm lint:linkcheck

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

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

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

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.

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.

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:

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

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

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

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

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

Terminal window
svgo image.svg

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

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.

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

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.

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.

Last updated: