MAIF · Mcdostone · Dec 3, 2025 · Dec 1, 2025
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -239,6 +239,16 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - name: Build documentation
         run: cargo doc --no-deps --document-private-items --verbose
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache-dependency-path: docs/package-lock.json
+          cache: npm
+      - name: Install dependencies
+        run: npm install --prefix docs
+      - name: Build with VitePress
+        run: npm run build --prefix docs
 
   lychee:
     name: Lychee

diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -0,0 +1,53 @@
+name: Deploy VitePress site to Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: npm ci --prefix docs
+      - name: Build with VitePress
+        run: npm run build --prefix docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -27,3 +27,6 @@ docs/schemas/kafka.properties
 .jj
 mutants.out
 mutants.out.old
+docs/.vitepress/dist
+docs/.vitepress/cache
+docs/node_modules
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 <p align="center" style="width: 150px">
 <picture>
-    <source width="150" media="(prefers-color-scheme: dark)" srcset="https://github.com/MAIF/yozefu/raw/main/docs/assets/logo.svg">
-    <img width="150" alt=" Pixel art portrait of a serious-faced person in grayscale above the text 'Yozefu'" src="https://github.com/MAIF/yozefu/raw/main/docs/assets/logo.svg">
+    <source width="150" media="(prefers-color-scheme: dark)" srcset="https://github.com/MAIF/yozefu/raw/main/docs/public/logo.svg">
+    <img width="150" alt=" Pixel art portrait of a serious-faced person in grayscale above the text 'Yozefu'" src="https://github.com/MAIF/yozefu/raw/main/docs/public/logo.svg">
   </picture>
 </p>
 
@@ -123,18 +123,18 @@ yozf -c localhost
 <table>
   <tr>
     <td>
-      <img alt=" A TUI displays a list of topics on the left, a search bar below, and records with timestamps and values in a table on the right. " src="https://raw.githubusercontent.com/MAIF/yozefu/refs/heads/main/docs/assets/topics.png">
+      <img alt=" A TUI displays a list of topics on the left, a search bar below, and records with timestamps and values in a table on the right. " src="https://raw.githubusercontent.com/MAIF/yozefu/refs/heads/main/docs/public/topics.png">
     </td>
     <td>
-      <img alt="A TUI listing the consumed kafka records with their timestamps, their partition, their offset and an excerpt of the key and the value." src="https://raw.githubusercontent.com/MAIF/yozefu/refs/heads/main/docs/assets/records.png">
+      <img alt="A TUI listing the consumed kafka records with their timestamps, their partition, their offset and an excerpt of the key and the value." src="https://raw.githubusercontent.com/MAIF/yozefu/refs/heads/main/docs/public/records.png">
     </td>
   </tr>
   <tr>
     <td>
-      <img alt="View of a selected kafka records" src="https://raw.githubusercontent.com/MAIF/yozefu/refs/heads/main/docs/assets/record.png">
+      <img alt="View of a selected kafka records" src="https://raw.githubusercontent.com/MAIF/yozefu/refs/heads/main/docs/public/record.png">
     </td>
     <td>
-      <img alt="View of the help page" src="https://raw.githubusercontent.com/MAIF/yozefu/refs/heads/main/docs/assets/help.png">
+      <img alt="View of the help page" src="https://raw.githubusercontent.com/MAIF/yozefu/refs/heads/main/docs/public/help.png">
     </td>
   </tr>
 </table>

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -0,0 +1,62 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+
+  title: "Yōzefu",
+  description: "Interactive TUI to explore Kafka clusters and data",
+
+  themeConfig: {
+    search: {
+      provider: 'local'
+    },
+    nav: [
+      { text: 'Documentation', link: '/getting-started/' },
+      { text: 'docs.rs', link: 'https://docs.rs/crate/yozefu/latest' },
+      { text: 'crates.io', link: 'https://crates.io/crates/yozefu' }
+    ],
+     footer: {
+      message: `
+      <a href="https://maif.github.io/"><img class="footer-maif" src="/maif.svg" /></a><br /><a href="https://maif.github.io/">OSS by MAIF</a>, released under Apache License, Version 2.0</p>`,
+    },
+    sidebar: [
+      {
+        text: 'Introduction',
+        items: [
+          { text: 'What is Yōzefu?', link: '/what-is-yozefu/' },
+          { text: 'Getting Started', link: '/getting-started/' },
+          { text: 'Keybindings', link: '/keybindings/' },
+
+        ]
+      },
+      {
+        text: 'Configuration',
+        items: [
+          { text: 'General', link: '/configuration/' },
+          { text: 'TLS', link: '/tls/' },
+          { text: 'Schema Registry', link: '/schema-registry/' },
+          { text: 'Themes', link: '/themes/' },
+          { text: 'URL Templates', link: '/url-templates/' },
+        ]
+      },
+      {
+        text: 'Search',
+        items: [
+
+          { text: 'Creating a search filter', link: '/search-filter/' },
+          { text: 'Examples', link: '/query-language/' },
+        ]
+      },
+      {
+        text: 'Internals',
+        items: [
+          { text: 'JSON schemas', link: '/json-schemas/' },
+        ]
+      },
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/MAIF/yozefu' }
+    ]
+  }
+})
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
@@ -0,0 +1,17 @@
+html.dark .light-only {
+  display: none !important;
+}
+
+html:not(.dark) .dark-only {
+  display: none !important;
+}
+
+.gif {
+  border-radius: 12px;
+}
+
+
+.footer-maif {
+  height: 2rem;
+  margin: 0 auto;
+}
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme
diff --git a/docs/configuration/README.md b/docs/configuration/README.md
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
@@ -0,0 +1,50 @@
+# Configuration
+
+Yōzefu uses a workspace directory to store its configuration file, logs, and other data. By default, this directory is located at `yozf config get dir`. You can change the workspace directory using the `--config-dir` command-line option or the `YOZEFU_CONFIG_DIR` environment variable.
+
+
+
+|               | Default                           |      CLI option |        Env variable |  Configuration file |
+| ------------- | --------------------------------- | --------------: | ------------------: | ------------------: |
+| Workspace     | `~/.config/io.maif.yozefu/`       |  `--config-dir` | `YOZEFU_CONFIG_DIR` |                  No |
+| Configuration | `${workspace}/config.json`        | `--config-file` |                 N/A |                  No |
+| Logs          | `${workspace}/application.log`    |    `--log-file` |   `YOZEFU_LOG_FILE` |         `/log_file` |
+| Export folder | `$PWD/export-{datetime-now}.json` |      `--output` |                  No | `/export_directory` |
+
+
+
+
+## `config.json` file
+
+
+Yōzefu uses a JSON configuration file to set various options. By default, it looks for a file named `config.json` in the workspace directory.
+
+
+| Key                                                                                      | Type                  | Examples                                                |
+| ---------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------- |
+| `default_url_template` <br/> Placeholder URL to open a Kafka record in the browser.      | String                | `http://localhost/cluster/{topic}/{partition}/{offset}` |
+| `initial_query`        <br/> Initial search query when starting the UI.                  | String                | `from end - 10`                                         |
+| `theme`                <br/> TUI theme.                                                  | String                | `light`                                                 |
+| `highlighter_theme`    <br/> Theme for syntax highlighting.                              | String                | `InspiredGitHub`                                        |
+| `clusters`             <br/> Kafka properties per  <a href="#kafka-cluster">cluster</a>. | Object                | —                                                       |
+| `consumer`             <br/> Default configuration for the Kafka consumer.               | Object                | `{ buffer_capacity: 1000, timeout_in_ms: 10 }`          |
+| `default_kafka_config` <br/> Default Kafka properties inherited by every cluster.        | Map\<String, String\> | `{"fetch.min.bytes": "10000"}`                          |
+| `history`              <br/> Past search queries.                                        | Array\<string\>       | `["from end - 10"]`                                     |
+| `show_shortcuts`       <br/> Whether to show shortcuts.                                  | Boolean               | `true`                                                  |
+| `export_directory`     <br/> Directory for exports.                                      | String                | `./yozefu-exports`                                      |
+| `log_file`             <br/> File path to write logs.                                    | String                | `/path/to/log/file.log`                                 |
+| `timestamp_format`     <br/> Display timestamps as date-time or relative.                | `DateTime` or `Ago`   | `DateTime`                                              |
+
+
+## Kafka cluster
+
+
+| Key                                                                             | Type                  | Examples                                          |
+| ------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------- |
+| `url_template`    <br/>  Placeholder URL to open a Kafka record in the browser. | String                | `http://dev/cluster/{topic}/{partition}/{offset}` |
+| `schema_registry` <br/> Schema registry settings for this cluster.              | Object                | `{}`                                              |
+| `kafka`           <br/> Kafka consumer properties for this cluster              | Map\<String, String\> | `{}`                                              |
+| `consumer`        <br/> configuration for the Yozefu consumer.                  | Object                | `{ buffer_capacity: 10, timeout_in_ms: 1 }`        |
+
+
+For more details, see the [configuration json schema](../json-schemas/).
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
@@ -0,0 +1,96 @@
+# Getting started
+
+
+Give Yōzefu a try in your terminal with the following command:
+
+```shell
+# It clones this repository, starts a docker kafka node and produces json records
+curl -L "https://raw.githubusercontent.com/MAIF/yozefu/refs/heads/main/docs/try-it.sh" | bash
+yozf -c localhost
+```
+
+
+## Install
+
+
+### Prerequisites
+
+
+
+::: code-group
+
+```sh [cargo]
+RUSTFLAGS="--cfg tokio_unstable" cargo install --locked yozefu
+```
+
+```sh [git]
+git clone git@github.com:MAIF/yozefu.git
+cargo run -- --localhost
+```
+
+```sh [brew]
+brew install yozefu
+
+```
+
+```sh [yay]
+yay -S yozefu
+```
+
+```sh [nix]
+nix run github:MAIF/yozefu
+```
+:::
+
+
+### Configuration
+
+Once installed, you can configure Yōzefu to connect to your Kafka clusters.
+
+
+::: tip NOTE
+
+Yōzefu has a default cluster named `localhost` pointing to `localhost:9092`. You can use it to quickly try Yōzefu with a local Kafka instance.
+
+:::
+
+```shell
+# Path of the configuration file
+yozf config get path
+
+# Open the configuration file with your favorite editor
+yozf configure --editor 'vim'
+```
+
+And then add your cluster configuration. Here is an example for a Aiven cluster:
+```json{8-18}
+{
+  "default_url_template": "...",
+  "initial_query": "from end - 10",
+  "clusters": {
+    "localhost": {
+        ...
+    },
+    "production": {
+      "url_template": "https://console.aiven.io/<acme>/topics/{topic}/messages?offset={offset}&partition={partition}&format=json",
+      "kafka": {
+        "bootstrap.servers": "kafka.aivencloud.com:24624",
+        "security.protocol": "sasl_ssl",
+        "sasl.mechanism": "SCRAM-SHA-256",
+        "sasl.username": "user",
+        "sasl.password": "password",
+        "ssl.ca.location": "~/path/to/ca.pem"
+      }
+    }
+  }
+}
+```
+
+## Run it
+
+Once configured, you can start using Yōzefu to query your Kafka topics.
+
+```shell
+# Connect to the 'production' cluster
+yozf --cluster production
+```
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,36 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Yōzefu,"
+  text: "A TUI to explore Kafka clusters"
+  image:
+    src: /dd.svg
+    alt: Yozefu
+
+  actions:
+    - theme: brand
+      text: Getting started
+      link: /getting-started/
+
+features:
+  - icon: 🔌
+    title: Real-time + Multi-topic
+    details: Live access to records and search across multiple topics.
+  - icon: 🔎
+    title: Powerful Querying
+    details: SQL-inspired query language with fine-grained filters, extensible via WebAssembly.
+    link: /query-language/
+  - icon: 🖥️
+    title: Dual Modes
+    details: Use as interactive TUI or CLI with the `--headless` flag.
+    link: /what-is-yozefu/#a-tui-and-cli
+  - icon: 📤
+    title: One-key Export
+    details: Quickly export Kafka records for deeper analysis.
+---
+
+
+![The user selects a topic and sees and real time new records published to Kafka.](https://vhs.charm.sh/vhs-UpIJD2h92vKkj01XSS0r0.gif){.dark-only .gif}
+![The user selects a topic and sees and real time new records published to Kafka.](https://vhs.charm.sh/vhs-1oh0ovd0DaUfvKLTx4iZTo.gif){.light-only .gif}