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
Section titled “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
Section titled “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
Section titled “Link Checking”The documentation includes automated link validation to ensure all internal and external links work correctly:
Local Link Checking
Section titled “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
Section titled “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
Section titled “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
Section titled “Fixing Broken Links”When the link checker finds issues:
- Invalid internal links: Update the link to point to the correct page path
- Missing anchor references: Ensure the target heading or element exists
- Broken external links: Update URLs or remove outdated references
- False positives: Add exclusions to the
starlightLinksValidator
configuration inastro.config.mjs
The link checker will cause builds to fail if broken links are detected, ensuring the documentation maintains high quality.
Optimize Images
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “Automatically Updated Files”The following files are synchronized from upstream repositories:
Tenzir Node Documentation:
src/content/docs/changelog/node
is generated from individual changelog entriessrc/content/docs/reference/functions
is synced from tenzir/tenzir atdocs/functions/
src/content/docs/reference/operators
is synced from tenzir/tenzir atdocs/operators/
src/content/docs/reference/functions.mdx
is generated from individual function filessrc/content/docs/reference/operators.mdx
is generated from individual operator filessrc/sidebar-reference.js
is generated from individual function and operator files for programmatic sidebar navigationsrc/content/apis/openapi.node.yaml
is the API specification for Tenzir Node and generated from the node’s source codetenzir.yaml.example
is the node’s example configuration file
Tenzir Platform Documentation:
src/content/docs/changelog/platform
is generated from individual changelog entriessrc/content/docs/reference/platform-cli.mdx
is synced from tenzir/platform atdocs/platform-cli.mdx
Making Changes to Auto-Updated Content
Section titled “Making Changes to Auto-Updated Content”If you need to update content in these files:
- For Functions/Operators: Make changes in the tenzir/tenzir repository
- For Platform CLI: Make changes in the tenzir/platform repository
- 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
Section titled “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.