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.

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.

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.