refactor: replace mkdocs with zensical (#2667)

* move docs to zensical

* fix requirements

* fixes

* remove manual font loading

does not work properly with mike

* switch back to pymdownx.blocks.admonition

* revert back

* remove css

* add note about privacy plugin

* pr review findings

.gitignore

@@ -1,3 +1,6 @@
 .DS_Store
 *.swp
-node_modules
+node_modules
+
+docs/site
+docs/.cache

.vscode/settings.json

@@ -26,5 +26,8 @@
   "i18n-ally.sortKeys": false,
   "i18n-ally.keepFulfilled": false,
   "i18n-ally.keystyle": "nested",
-  "editor.gotoLocation.multipleDefinitions": "goto"
+  "editor.gotoLocation.multipleDefinitions": "goto",
+  "[toml]": {
+    "editor.defaultFormatter": "tamasfe.even-better-toml"
+  }
 }

docs/content/advanced/api.md

@@ -5,6 +5,7 @@ title: API
 /// warning | Breaking Changes
 
 This API is not yet stable and may change in the future. The API is currently in development and is subject to change without notice. The API is not yet documented, but we will add documentation as the API stabilizes.
+
 ///
 
 You can use the API to interact with the application programmatically. The API is available at `/api` and supports both GET and POST requests. The API is designed to be simple and easy to use, with a focus on providing a consistent interface for all endpoints.

docs/content/advanced/config/amnezia.md

@@ -39,14 +39,14 @@ If a parameter is not set, it will not be added to the configuration. If all Amn
 
 ### Parameter Compatibility Table
 
-| Parameter | Can differ between server and client | Configurable on server | Configurable on client  |
-| --------- | ------------------------------------ | ---------------------- | ----------------------- |
-| Jc        | ✅ Yes                               | ✅                     | ✅                      |
-| Jmin      | ✅ Yes                               | ✅                     | ✅                      |
-| Jmax      | ✅ Yes                               | ✅                     | ✅                      |
-| S1-S4     | ❌ No, must match                    | ✅                     | ❌ (copied from server) |
-| H1-H4     | ❌ No, must match                    | ✅                     | ❌ (copied from server) |
-| I1-I5     | ✅ Yes                               | ✅                     | ✅                      |
+| Parameter | Can differ between server and client | Configurable on server | Configurable on client   |
+| --------- | ------------------------------------ | ---------------------- | ------------------------ |
+| Jc        | :white_check_mark: Yes               | :white_check_mark:     | :white_check_mark:       |
+| Jmin      | :white_check_mark: Yes               | :white_check_mark:     | :white_check_mark:       |
+| Jmax      | :white_check_mark: Yes               | :white_check_mark:     | :white_check_mark:       |
+| S1-S4     | :x: No, must match                   | :white_check_mark:     | :x: (copied from server) |
+| H1-H4     | :x: No, must match                   | :white_check_mark:     | :x: (copied from server) |
+| I1-I5     | :white_check_mark: Yes               | :white_check_mark:     | :white_check_mark:       |
 
 ## Client Applications
 

docs/content/advanced/config/external-authentication.md

@@ -24,7 +24,7 @@ To automatically register users that log in with an OAuth provider, set the foll
 
 | Env                   | Required | Default | Description              |
 | --------------------- | -------- | ------- | ------------------------ |
-| `OAUTH_AUTO_REGISTER` | ✖️       | `false` | Enable auto-registration |
+| `OAUTH_AUTO_REGISTER` | :x:      | `false` | Enable auto-registration |
 
 When enabled:
 
@@ -46,7 +46,7 @@ To only allow users with an email address from a specific domain to log in, set
 
 | Env                     | Required | Default | Description           |
 | ----------------------- | -------- | ------- | --------------------- |
-| `OAUTH_ALLOWED_DOMAINS` | ✖️       | -       | Allowed email domains |
+| `OAUTH_ALLOWED_DOMAINS` | :x:      | -       | Allowed email domains |
 
 You can allow multiple domains by separating them with a comma:
 
@@ -58,7 +58,7 @@ To automatically launch the OAuth login flow when visiting the login page, set t
 
 | Env                 | Required | Default | Description                   |
 | ------------------- | -------- | ------- | ----------------------------- |
-| `OAUTH_AUTO_LAUNCH` | ✖️       | -       | Auto launch an OAuth provider |
+| `OAUTH_AUTO_LAUNCH` | :x:      | -       | Auto launch an OAuth provider |
 
 When enabled:
 
@@ -83,10 +83,10 @@ If your provider does not support multiple redirect URIs (e.g. GitHub) but allow
 
 #### Google
 
-| Env                          | Required | Description          |
-| ---------------------------- | -------- | -------------------- |
-| `OAUTH_GOOGLE_CLIENT_ID`     | ✔️       | Google Client ID     |
-| `OAUTH_GOOGLE_CLIENT_SECRET` | ✔️       | Google Client Secret |
+| Env                          | Required           | Description          |
+| ---------------------------- | ------------------ | -------------------- |
+| `OAUTH_GOOGLE_CLIENT_ID`     | :white_check_mark: | Google Client ID     |
+| `OAUTH_GOOGLE_CLIENT_SECRET` | :white_check_mark: | Google Client Secret |
 
 <h5>Setup</h5>
 
@@ -97,10 +97,10 @@ If your provider does not support multiple redirect URIs (e.g. GitHub) but allow
 
 #### GitHub
 
-| Env                          | Required | Description          |
-| ---------------------------- | -------- | -------------------- |
-| `OAUTH_GITHUB_CLIENT_ID`     | ✔️       | GitHub Client ID     |
-| `OAUTH_GITHUB_CLIENT_SECRET` | ✔️       | GitHub Client Secret |
+| Env                          | Required           | Description          |
+| ---------------------------- | ------------------ | -------------------- |
+| `OAUTH_GITHUB_CLIENT_ID`     | :white_check_mark: | GitHub Client ID     |
+| `OAUTH_GITHUB_CLIENT_SECRET` | :white_check_mark: | GitHub Client Secret |
 
 <h5>Setup</h5>
 
@@ -122,12 +122,12 @@ The provider needs to support:
 
 The provider needs to be available with HTTPS and have a valid certificate.
 
-| Env                        | Required | Default | Example                    | Description        |
-| -------------------------- | -------- | ------- | -------------------------- | ------------------ |
-| `OAUTH_OIDC_SERVER`        | ✔️       | -       | `https://auth.example.com` | OIDC Server        |
-| `OAUTH_OIDC_CLIENT_ID`     | ✔️       | -       | -                          | OIDC Client ID     |
-| `OAUTH_OIDC_CLIENT_SECRET` | ✔️       | -       | -                          | OIDC Client Secret |
-| `OAUTH_OIDC_NAME`          | ✖️       | OIDC    | `Authelia`                 | Provider Name      |
+| Env                        | Required           | Default | Example                    | Description        |
+| -------------------------- | ------------------ | ------- | -------------------------- | ------------------ |
+| `OAUTH_OIDC_SERVER`        | :white_check_mark: | -       | `https://auth.example.com` | OIDC Server        |
+| `OAUTH_OIDC_CLIENT_ID`     | :white_check_mark: | -       | -                          | OIDC Client ID     |
+| `OAUTH_OIDC_CLIENT_SECRET` | :white_check_mark: | -       | -                          | OIDC Client Secret |
+| `OAUTH_OIDC_NAME`          | :x:                | OIDC    | `Authelia`                 | Provider Name      |
 
 ##### Authelia Setup
 
@@ -167,7 +167,7 @@ To disable password-based authentication and only allow login via OAuth provider
 
 | Env                     | Required | Default | Description                     |
 | ----------------------- | -------- | ------- | ------------------------------- |
-| `DISABLE_PASSWORD_AUTH` | ✖️       | `false` | Disable password authentication |
+| `DISABLE_PASSWORD_AUTH` | :x:      | `false` | Disable password authentication |
 
 When enabled:
 

docs/content/advanced/config/unattended-setup.md

@@ -23,6 +23,7 @@ These will only be used during the first start of the container. After that, the
 If variables are in the same group, you have to set all of them. For example, if you set `INIT_IPV4_CIDR`, you also have to set `INIT_IPV6_CIDR`.
 
 If you want to skip the setup process, you have to configure group `1`
+
 ///
 
 /// note | Security
@@ -30,4 +31,5 @@ If you want to skip the setup process, you have to configure group `1`
 The initial username and password is not checked for complexity. Make sure to set a long enough username and password. Otherwise, the user won't be able to log in.
 
 It's recommended to remove the variables after the setup is done to prevent the password from being exposed.
+
 ///

docs/content/advanced/metrics/prometheus.md

@@ -39,4 +39,5 @@ You can use the following Grafana dashboard to visualize the metrics:
 
 The Grafana dashboard is not official and is not maintained by the `wg-easy` team. If you have any issues with the dashboard, please contact the author of the dashboard.
 See [#1299](https://github.com/wg-easy/wg-easy/pull/1299) for more information.
+
 ///

docs/content/contributing/issues-and-pull-requests.md

@@ -9,6 +9,7 @@ This project is Open Source. That means that you can contribute on enhancements,
 /// note | Attention
 
 **Before opening an issue**, read the [`README`][github-file-readme] carefully, study the docs for your version (maybe [latest][docs-latest]) and your search engine you trust. The issue tracker is not meant to be used for unrelated questions!
+
 ///
 
 When opening an issue, please provide details use case to let the community reproduce your problem.
@@ -16,6 +17,7 @@ When opening an issue, please provide details use case to let the community repr
 /// note | Attention
 
 **Use the issue templates** to provide the necessary information. Issues which do not use these templates are not worked on and closed.
+
 ///
 
 By raising issues, I agree to these terms and I understand, that the rules set for the issue tracker will help both maintainers as well as everyone to find a solution.
@@ -39,6 +41,7 @@ When an option is marked with "not officially supported" / "unsupported", then s
 /// question | Motivation
 
 You want to add a feature? Feel free to start creating an issue explaining what you want to do and how you're thinking doing it. Other users may have the same need and collaboration may lead to better results.
+
 ///
 
 ### Submit a Pull-Request

docs/content/examples/tutorials/adguard.md

@@ -9,9 +9,11 @@ This tutorial is a follow-up to the official [Traefik tutorial](./traefik.md). I
 - A working [wg-easy](./basic-installation.md) and [Traefik](./traefik.md) setup from the previous guides.
 
 /// warning | Important: Following this guide will reset your WireGuard configuration.
+
 The process involves re-creating the `wg-easy` container and its data, which means **all existing WireGuard clients and settings will be deleted.**
 
 You will need to create your clients again after completing this guide.
+
 ///
 
 ## Add `adguard` configuration
@@ -152,13 +154,15 @@ networks:
 2. Navigate to `https://adguard.$example.com$` to begin the AdGuard Home setup.
 
 /// warning | Important: Configure AdGuard Home Admin Web Interface Port
+
 During the initial AdGuard Home setup on the `Step 2/5` page, you **must** set the **Admin Web Interface Port** to **3000**. Do not use the default port 80, as it will not work with the Traefik configuration.
 
 After completing the setup, the AdGuard UI might appear unresponsive. This is expected. **Simply reload the page**, and the panel will display correctly.
-///
 
 > If you accidentally left it default (80), you will need to manually edit the `docker-compose.yml` file for AdGuard Home (`/etc/docker/containers/adguard/docker-compose.yml`) and change the line `traefik.http.services.adguard.loadbalancer.server.port=3000` to `traefik.http.services.adguard.loadbalancer.server.port=80`. After making this change, restart AdGuard Home by navigating to `/etc/docker/containers/adguard` and running `sudo docker compose up -d`.
 
+///
+
 ## Final System Checks
 
 ### Firewall

docs/content/examples/tutorials/caddy.md

@@ -5,6 +5,7 @@ title: Caddy
 /// note | Opinionated
 
 This guide is opinionated. If you use other conventions or folder layouts, feel free to change the commands and paths.
+
 ///
 
 We're using [Caddy](https://caddyserver.com/) here as reverse proxy to serve `wg-easy` on [https://wg-easy.example.com](https://wg-easy.example.com) via TLS.

docs/content/examples/tutorials/reverse-proxyless.md

@@ -7,6 +7,7 @@ title: No Reverse Proxy
 This is insecure. You should use a reverse proxy to secure the connection.
 
 Only use this method if you know what you are doing.
+
 ///
 
 If you only allow access to the web UI from your local network, you can skip the reverse proxy setup. This is not recommended, but it is possible.

docs/content/examples/tutorials/routed.md

@@ -61,6 +61,7 @@ Pick an IPv4 and IPv6 subnet for your clients and add static routes on your rout
 /// note | 2001:db8::/32
 
 The _documentation prefix_ `2001:db8::/32` (RFC 3849) used in this example is not meant for production use, replace it with your own ISP-assigned IPv6 prefix (GUA) or local prefix (ULA)
+
 ///
 
 I want my WireGuard clients in `192.168.0.0/24` and `2001:db8:abc:0::/64`.

docs/content/examples/tutorials/traefik.md

@@ -5,6 +5,7 @@ title: Traefik
 /// note | Opinionated
 
 This guide is opinionated. If you use other conventions or folder layouts, feel free to change the commands and paths.
+
 ///
 
 ## Create docker compose project

docs/content/getting-started.md

@@ -24,6 +24,7 @@ There are a few requirements for a suitable host system:
 
 On the host, you need to have a suitable container runtime (like _Docker_ or _Podman_) installed. We assume [_Docker Compose_][docker-compose] is [installed][docker-compose-installation]. We have aligned file names and configuration conventions with the latest [Docker Compose specification][docker-compose-specification].
 If you're using podman, make sure to read the related [documentation][docs-podman].
+
 ///
 
 [docker-compose]: https://docs.docker.com/compose/
@@ -69,6 +70,7 @@ When publishing a tag we follow the [Semantic Versioning][semver] specification.
 /// danger | Use the Correct Commands For Stopping and Starting `wg-easy`
 
 **Use `sudo docker compose up / down`, not `sudo docker compose start / stop`**. Otherwise, the container is not properly destroyed and you may experience problems during startup because of inconsistent state.
+
 ///
 
 **That's it! It really is that easy**.

docs/content/guides/admin.md

@@ -23,7 +23,9 @@ This feature is currently experimental. While functional, it should be thoroughl
 - The feature cannot be enabled if these tools are not available
 
 /// note
+
 Most Linux distributions include iptables by default. If you're running in a minimal container environment, you may need to install the `iptables` package on the host system.
+
 ///
 
 **Enable this feature if you want to:**

docs/content/guides/clients.md

@@ -62,7 +62,9 @@ Protocol specifiers (`/tcp` or `/udp`) require a port number. The following form
 - **Disable for specific client**: To disable firewall filtering for a single client while keeping it enabled for others, add `0.0.0.0/0, ::/0` to allow all traffic
 
 /// note
+
 To allow clients to reach the VPN server itself (e.g. for DNS), include the server's VPN address in the firewall allowed IPs.
+
 ///
 
 **Use Case Examples**:

docs/content/index.md

@@ -9,6 +9,7 @@ hide:
 /// info | This Documentation is Versioned
 
 **Make sure** to select the correct version of this documentation! It should match the version of the image you are using. The default version corresponds to [the most recent stable release][docs-tagging].
+
 ///
 
 This documentation provides you not only with the basic setup and configuration of `wg-easy` but also with advanced configuration, elaborate usage scenarios, detailed examples, hints and more.

docs/mkdocs.yml

@@ -1,87 +0,0 @@
-site_name: 'wg-easy'
-site_description: 'The easiest way to run WireGuard VPN + Web-based Admin UI.'
-site_author: 'WireGuard Easy'
-copyright: >
-    <p>
-    &copy <a href="https://github.com/wg-easy"><em>Wireguard Easy</em></a><br/>
-    <span>This project is licensed under AGPL-3.0-only.</span><br/>
-    <span>This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Jason A. Donenfeld, ZX2C4 or Edge Security</span><br/>
-    <span>"WireGuard" and the "WireGuard" logo are registered trademarks of Jason A. Donenfeld</span>
-    </p>
-
-repo_url: https://github.com/wg-easy/wg-easy
-repo_name: wg-easy
-
-edit_uri: 'edit/master/docs/content'
-
-docs_dir: 'content/'
-
-site_url: https://wg-easy.github.io/wg-easy
-
-theme:
-    name: material
-    favicon: assets/logo/favicon.png
-    logo: assets/logo/logo.png
-    icon:
-        repo: fontawesome/brands/github
-    features:
-        - navigation.tabs
-        - navigation.top
-        - navigation.expand
-        - navigation.instant
-        - content.action.edit
-        - content.action.view
-        - content.code.annotate
-    palette:
-        # Light mode
-        - media: '(prefers-color-scheme: light)'
-          scheme: default
-          primary: grey
-          accent: red
-          toggle:
-              icon: material/weather-night
-              name: Switch to dark mode
-        # Dark mode
-        - media: '(prefers-color-scheme: dark)'
-          scheme: slate
-          primary: grey
-          accent: red
-          toggle:
-              icon: material/weather-sunny
-              name: Switch to light mode
-
-extra:
-    version:
-        provider: mike
-
-markdown_extensions:
-    - toc:
-          anchorlink: true
-    - abbr
-    - attr_list
-    - pymdownx.blocks.admonition:
-          types:
-              - danger
-              - note
-              - info
-              - question
-              - warning
-    - pymdownx.details
-    - pymdownx.superfences:
-          custom_fences:
-              - name: mermaid
-                class: mermaid
-                format: !!python/name:pymdownx.superfences.fence_code_format
-    - pymdownx.tabbed:
-          alternate_style: true
-          slugify: !!python/object/apply:pymdownx.slugs.slugify
-              kwds:
-                  case: lower
-    - pymdownx.tasklist:
-          custom_checkbox: true
-    - pymdownx.magiclink
-    - pymdownx.inlinehilite
-    - pymdownx.tilde
-    - pymdownx.emoji:
-          emoji_index: !!python/name:material.extensions.emoji.twemoji
-          emoji_generator: !!python/name:material.extensions.emoji.to_svg

docs/requirements.txt

@@ -1,4 +1,2 @@
-mkdocs-material
-pillow
-cairosvg
-mike
+zensical==0.0.45
+git+https://github.com/squidfunk/mike.git

docs/zensical.toml

@@ -0,0 +1,97 @@
+[project]
+site_name = "wg-easy"
+site_description = "The easiest way to run WireGuard VPN + Web-based Admin UI."
+site_author = "WireGuard Easy"
+copyright = """
+<p>
+&copy <a href="https://github.com/wg-easy"><em>Wireguard Easy</em></a><br/>
+<span>This project is licensed under AGPL-3.0-only.</span><br/>
+<span>This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Jason A. Donenfeld, ZX2C4 or Edge Security</span><br/>
+<span>"WireGuard" and the "WireGuard" logo are registered trademarks of Jason A. Donenfeld</span>
+</p>
+"""
+
+repo_url = "https://github.com/wg-easy/wg-easy"
+repo_name = "wg-easy"
+
+edit_uri = "edit/master/docs/content"
+
+docs_dir = "content/"
+
+site_url = "https://wg-easy.github.io/wg-easy"
+
+[project.theme]
+variant = "modern"
+favicon = "assets/logo/favicon.png"
+logo = "assets/logo/logo.png"
+features = [
+  "navigation.instant",
+  "navigation.tabs",
+  "navigation.expand",
+  "navigation.path",
+  "navigation.top",
+  "content.action.edit",
+  "content.action.view",
+  "content.code.copy",
+  "content.code.annotate",
+]
+
+[project.theme.icon]
+repo = "fontawesome/brands/github"
+
+# Palette toggle for automatic mode
+[[project.theme.palette]]
+media = "(prefers-color-scheme)"
+toggle.icon = "lucide/sun-moon"
+toggle.name = "Switch to light mode"
+
+# Palette toggle for light mode
+[[project.theme.palette]]
+media = "(prefers-color-scheme: light)"
+scheme = "default"
+primary = "grey"
+accent = "red"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to dark mode"
+
+# Palette toggle for dark mode
+[[project.theme.palette]]
+media = "(prefers-color-scheme: dark)"
+scheme = "slate"
+primary = "grey"
+accent = "red"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to system preference"
+
+# [project.plugins.privacy]
+
+[project.extra.version]
+provider = "mike"
+
+[project.markdown_extensions.pymdownx.blocks.admonition]
+types = ["danger", "note", "info", "question", "warning"]
+
+[project.markdown_extensions.md_in_html]
+
+[project.markdown_extensions.toc]
+permalink = true
+
+[project.markdown_extensions.pymdownx.details]
+
+[project.markdown_extensions.pymdownx.emoji]
+emoji_generator = "zensical.extensions.emoji.to_svg"
+emoji_index = "zensical.extensions.emoji.twemoji"
+
+[project.markdown_extensions.pymdownx.highlight]
+anchor_linenums = true
+line_spans = "__span"
+pygments_lang_class = true
+
+[project.markdown_extensions.pymdownx.inlinehilite]
+
+[project.markdown_extensions.pymdownx.smartsymbols]
+
+[project.markdown_extensions.pymdownx.superfences]
+custom_fences = [
+  { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" },
+]

package.json

@@ -5,7 +5,7 @@
     "dev": "docker compose -f docker-compose.dev.yml up wg-easy --build",
     "cli:dev": "docker compose -f docker-compose.dev.yml run --build --rm -it wg-easy cli:dev",
     "build": "docker build -t wg-easy .",
-    "docs:preview": "docker run --rm -it -p 8080:8080 -v ./docs:/docs squidfunk/mkdocs-material serve -a 0.0.0.0:8080",
+    "docs:preview": "docker run --rm -it -p 8080:8080 -v ./docs:/docs zensical/zensical serve -a 0.0.0.0:8080",
     "scripts:version": "bash scripts/version.sh",
     "scripts:i18n": "bash scripts/i18n.sh",
     "format:check:docs": "prettier --check docs"