feat: documentation website using Vitepress

Adds documentation website using https://vitepress.dev.

Some decisions are questionable, for example creation of a symbolic link
for the README in the `docs/`. I wanted to preserve the ability to read
docs using Github. Maybe not needed.

Another issue, is the page outline for the `NixOS` chapter is too
narrow.

But should serve as a scaffold/basis for doing it properly.
This commit is contained in:
Igor Ramazanov
2025-08-09 21:35:27 +00:00
committed by Aarnav Tale
parent fdbfe584c5
commit 9192013bfe
24 changed files with 1487 additions and 66 deletions
+43
View File
@@ -0,0 +1,43 @@
import { defineConfig } from "vitepress";
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: "Headplane",
description: "Documentation",
// base: "https://headplane.net",
ignoreDeadLinks: ["/docs/Integrated-Mode", "/docs/Simple-Mode"],
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
nav: [{ text: "Home", link: "/" }],
sidebar: [
{
text: "Chapters",
items: [
{ text: "Getting Started", link: "/README" },
{ text: "Configuration", link: "/Configuration" },
{ text: "Bare-Metal Mode", link: "/Bare-Metal" },
{ text: "Integrated Mode", link: "/Integrated-Mode" },
{ text: "Simple Mode", link: "/Simple-Mode" },
{ text: "Nix", link: "/Nix" },
{ text: "NixOS", link: "/NixOS-options" },
{ text: "Security", link: "/SECURITY" },
{ text: "Contributing", link: "/CONTRIBUTING" },
{ text: "Changelog", link: "/CHANGELOG" },
],
},
],
socialLinks: [
{ icon: "github", link: "https://github.com/tale/headplane" },
],
lastUpdated: {
text: "Updated at",
formatOptions: {
dateStyle: "full",
timeStyle: "medium",
},
},
},
});
+2 -2
View File
@@ -42,7 +42,7 @@ The structure of this folder is very important and should not be tampered with.
### Integrated Mode
Since you are running Headplane in Bare-Metal, you most likely also are running
Headscale in Bare-Metal. Refer to the [**Integrated Mode**](/docs/Integrated-Mode.md)
Headscale in Bare-Metal. Refer to the [**Integrated Mode**](./Integrated-Mode.md)
guide for instructions on setting up the integrated mode in Native Linux (/proc).
### Changing the Admin Path
@@ -58,7 +58,7 @@ Just keep in mind that the admin path is not configurable at runtime, so you
will need to rebuild the project if you want to change it. Also, anything aside
from `/admin` is not officially supported and could break in future versions.
> Refer to the [**Configuration**](/docs/Configuration.md) guide for help with
> Refer to the [**Configuration**](./Configuration.md) guide for help with
> setting up your `config.yaml` file to the appropriate values.
### Systemd Unit
+1
View File
@@ -0,0 +1 @@
./../CHANGELOG.md
+1 -1
View File
@@ -3,7 +3,7 @@
> Since 0.5, you will need to manually migrate your configuration to the new format.
Headplane uses a configuration file to manage its settings
([**config.example.yaml**](../config.example.yaml)). By default, Headplane looks
([**config.example.yaml**](https://github.com/tale/headplane/blob/main/config.example.yaml)). By default, Headplane looks
for a the file at `/etc/headplane/config.yaml`. This can be changed using the
**`HEADPLANE_CONFIG_PATH`** environment variable to point to a different location.
+5 -5
View File
@@ -3,15 +3,15 @@
<picture>
<source
media="(prefers-color-scheme: dark)"
srcset="../assets/dns-dark.png"
srcset="./assets/dns-dark.png"
>
<source
media="(prefers-color-scheme: light)"
srcset="../assets/dns-light.png"
srcset="./assets/dns-light.png"
>
<img
alt="Integration Preview"
src="../assets/dns-dark.png"
src="./assets/dns-dark.png"
>
</picture>
@@ -21,7 +21,7 @@ deployment method for most users, as it provides a more feature-complete
experience.
## Deployment
> If you are not looking to deploy with Docker, follow the [**Bare-Metal**](/docs/Bare-Metal.md) deployment guide.
> If you are not looking to deploy with Docker, follow the [**Bare-Metal**](./Bare-Metal.md) deployment guide.
> Refer to the `Integrated Mode` section at the bottom for caveats.
Requirements:
@@ -73,7 +73,7 @@ This will result in the Headplane UI being available at the `/admin` path of the
server you deployed it on. The `/admin` path is currently not configurable unless
you build the container yourself or run Headplane in Bare-Metal mode.
> Refer to the [**Configuration**](/docs/Configuration.md) guide for help with
> Refer to the [**Configuration**](./Configuration.md) guide for help with
> setting up your `config.yaml` file to the appropriate values.
## Docker Integration
+2 -2
View File
@@ -1,7 +1,7 @@
# Nix
[flake.nix](../flake.nix) provided:
```
[flake.nix](https://github.com/tale/headplane/blob/main/flake.nix) provided:
```sh
$ nix flake show github:tale/headplane --all-systems
github:tale/headplane/ec6d455461955242393b60d9ce60c5123fa9784f?narHash=sha256-CM/vXzUiOed7i1Pp15KyV4FuIvumRlXnpF33dSWZZH4%3D
├───checks
+37 -37
View File
@@ -20,7 +20,7 @@ boolean
` true `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -41,7 +41,7 @@ package
` pkgs.headplane `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -60,7 +60,7 @@ boolean
` false `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -82,7 +82,7 @@ submodule
` { } `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -103,7 +103,7 @@ submodule
` { } `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -132,7 +132,7 @@ null or absolute path
` "/etc/headscale/config.yaml" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -155,7 +155,7 @@ boolean
` true `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -183,7 +183,7 @@ null or absolute path
` "/var/lib/headplane/extra_records.json" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -209,7 +209,7 @@ null or string
` "https://headscale.example.com" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -235,7 +235,7 @@ null or absolute path
` "config.sops.secrets.tls_cert.path" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -264,7 +264,7 @@ string
` "https://headscale.example.com" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -285,7 +285,7 @@ submodule
` { } `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -306,7 +306,7 @@ submodule
` { } `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -329,7 +329,7 @@ boolean
` false `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -350,7 +350,7 @@ package
` pkgs.headplane-agent `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -371,7 +371,7 @@ absolute path
` "/var/lib/headplane/agent_cache.json" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -393,7 +393,7 @@ signed integer
` 180000 `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -414,7 +414,7 @@ string
` "headplane-agent" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -442,7 +442,7 @@ null or absolute path
` "config.sops.secrets.agent_pre_authkey.path" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -465,7 +465,7 @@ absolute path
` "/var/lib/headplane/agent" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -486,7 +486,7 @@ submodule
` { } `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -510,7 +510,7 @@ boolean
` true `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -531,7 +531,7 @@ submodule
` { } `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -557,7 +557,7 @@ string
` "your-client-id" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -583,7 +583,7 @@ null or absolute path
` "config.sops.secrets.oidc_client_secret.path" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -604,7 +604,7 @@ boolean
` false `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -630,7 +630,7 @@ null or absolute path
` "config.sops.secrets.headscale_api_key.path" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -656,7 +656,7 @@ string
` "https://provider.example.com/issuer-url" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -683,7 +683,7 @@ string
` "https://headscale.example.com/admin/oidc/callback" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -704,7 +704,7 @@ one of “client_secret_post”, “client_secret_basic”, “client_secret_jwt
` "client_secret_post" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -730,7 +730,7 @@ absolute path
` "/var/lib/headplane/users.json" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -751,7 +751,7 @@ submodule
` { } `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -778,7 +778,7 @@ null or absolute path
` "config.sops.secrets.headplane_cookie.path" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -801,7 +801,7 @@ boolean
` true `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -829,7 +829,7 @@ absolute path
` "/var/lib/headplane" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -855,7 +855,7 @@ string
` "0.0.0.0" `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
@@ -876,6 +876,6 @@ The port to listen on\.
` 3000 `
*Declared by:*
- [/nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options\.nix](file:///nix/store/k8cbmm2xy0s8gk2kggksxy6zffzry4jg-source/nix/options.nix)
- [nix/options.nix](https://github.com/tale/headplane/blob/main/nix/options.nix)
+1
View File
@@ -0,0 +1 @@
./../README.md
+3 -3
View File
@@ -4,10 +4,10 @@ Simple mode enables you to quickly deploy Headplane and is recommended for any
testing or simple environments. It does not include the automatic management of
DNS and Headplane settings, requiring manual editing and reloading when making
changes. If you're looking for a more feature-complete deployment method, check
out [**Integrated Mode**](/docs/Integrated-Mode.md).
out [**Integrated Mode**](./Integrated-Mode.md).
## Deployment
> If you are not looking to deploy with Docker, follow the [**Bare-Metal**](/docs/Bare-Metal.md) deployment guide.
> If you are not looking to deploy with Docker, follow the [**Bare-Metal**](./Bare-Metal.md) deployment guide.
Requirements:
- Docker and Docker Compose
@@ -33,5 +33,5 @@ This will result in the Headplane UI being available at the `/admin` path of the
server you deployed it on. The `/admin` path is currently not configurable unless
you build the container yourself or run Headplane in Bare-Metal mode.
> Refer to the [**Configuration**](/docs/Configuration.md) guide for help with
> Refer to the [**Configuration**](./Configuration.md) guide for help with
> setting up your `config.yaml` file to the appropriate values.
Binary file not shown.

After

Width:  |  Height:  |  Size: 118 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 118 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 110 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 111 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 127 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 128 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 108 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 107 KiB

+22
View File
@@ -0,0 +1,22 @@
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
hero:
name: "A feature-complete Web UI for Headscale"
text: "Documentation"
tagline: "A feature-complete Web UI for Headscale"
actions:
- theme: brand
text: Getting Started
link: /README
features:
- title: Web SSH
details: Connect to machines directly from your browser
- title: OIDC
details: Login through your favourite SSO provider
- title: And many more
details: Setup ACLs, DNS, pre-auth keys, etc.
---