Renew docs website

.github/workflows/deploy.yml

@@ -0,0 +1,44 @@
+name: Build and deploy
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - uses: actions/upload-pages-artifact@v3
+        if: github.ref == 'refs/heads/main'
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,2 +1,3 @@
 .idea/
-
+node_modules/
+_site/

README.md

@@ -1,13 +1,49 @@
-This projects contains the documentation website [docs.tactility.one](https://docs.tactilityproject.org).
+This project contains the documentation website at [docs.tactilityproject.org](https://docs.tactilityproject.org).
 
-It is built with [Docsify](https://docsify.js.org), which installs as follows:
+The pages are markdown files in `docs/`. [Eleventy](https://www.11ty.dev) turns them into static HTML. The setup and the theme are the same as those of the [Tactility website](https://github.com/TactilityProject/TactilityWebsite).
+
+Install the dependencies (Node.js 20 or newer):
 
 ```sh
-npm i docsify-cli -g
+npm install
 ```
 
-Develop with:
+Develop with a local server that reloads on changes:
 
 ```sh
-docsify serve docs
+npm start
 ```
+
+Build the site into `_site/`:
+
+```sh
+npm run build
+```
+
+## Where things are
+
+- `docs/<version>/`: the documentation of one Tactility version, e.g. `docs/main/` and `docs/v0.7.0/`. A page at `docs/main/app-development/ui.md` gets the URL `/main/app-development/ui/`.
+- `docs/<version>/index.md`: the start page of a version.
+- `docs/<version>/_sidebar.md`: the menu of a version, as a list of links with optional group titles.
+- `docs/index.md`: the landing page with the list of versions.
+- `docs/*.md`: pages that are shared by all versions (support, licenses).
+- `docs/_data/`: site name, community links and navigation.
+- `docs/_includes/`: page layouts.
+- `docs/assets/`: the stylesheet and the script (menus, copy buttons, search).
+
+## Versions
+
+Every folder in `docs/` that has a `_sidebar.md` is a version. `main` is the development version. The other folders are releases, and the one with the highest number is shown as the latest release.
+
+To add a release, copy `docs/main/` to a folder with the name of the release tag (e.g. `docs/v0.8.0/`). The landing page, the version menu and the search pick it up.
+
+## Writing pages
+
+- A page starts with a `# Title` heading.
+- Link to other pages with a path relative to the current file, e.g. `[Simulator](../os-development/simulator.md)` or `[Assets](fundamentals.md#assets)`.
+- `{{versionLabel}}` is replaced with the name of the version folder, which is useful for links to a branch or tag on GitHub.
+- Alerts: `> [!NOTE]` and `> [!WARNING]` blocks.
+- Tabbed card: wrap `::: tab <Title>` blocks in `:::: tabs` ... `::::`.
+- Diagrams: a `plantuml` code block is shown as an image, rendered by the PlantUML server.
+
+Pushing to `main` builds and publishes the site with GitHub Actions (`.github/workflows/deploy.yml`). For this, the repository's Pages settings must use "GitHub Actions" as the source.

docs/404.md

@@ -0,0 +1,7 @@
+---
+title: Page not found
+permalink: /404.html
+eleventyExcludeFromCollections: true
+---
+
+This page doesn't exist. Go to the [home page](index.md) to choose a version of the documentation.

docs/_data/nav.json

@@ -0,0 +1,12 @@
+{
+  "main": [
+    { "label": "Support", "url": "/support/" },
+    { "label": "Website", "url": "https://tactilityproject.org", "external": true }
+  ],
+  "footer": [
+    { "label": "Licenses & Copyrights", "url": "/licenses-and-copyrights/" },
+    { "label": "Support", "url": "/support/" },
+    { "label": "Tactility website", "url": "https://tactilityproject.org" },
+    { "label": "GitHub", "url": "https://github.com/TactilityProject" }
+  ]
+}

docs/_data/site.json

@@ -0,0 +1,13 @@
+{
+  "name": "Tactility Docs",
+  "tagline": "Documentation for the Tactility operating system",
+  "description": "Documentation for Tactility, an operating system for ESP32 devices: using it, developing apps, adding devices and drivers, and working on the OS itself.",
+  "url": "https://docs.tactilityproject.org",
+  "website": "https://tactilityproject.org",
+  "repo": "https://github.com/TactilityProject",
+  "community": [
+    { "name": "Matrix", "url": "https://matrix.to/#/#tactility:matrix.org" },
+    { "name": "Stoat", "url": "https://stt.gg/xwRTZEpX" },
+    { "name": "Discord", "url": "https://discord.gg/pXs2xGS6fs" }
+  ]
+}

docs/_includes/base.njk

@@ -0,0 +1,84 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  {%- if home %}
+  {%- set pageTitle = site.name + ": " + site.tagline %}
+  {%- elif docTitle %}
+  {%- set pageTitle = docTitle + ((" (" + version.id + ")") if (version and not version.development) else "") + " | " + site.name %}
+  {%- else %}
+  {%- set pageTitle = site.name %}
+  {%- endif %}
+  {%- set pageDescription = description or site.description %}
+  <title>{{ pageTitle }}</title>
+  <meta name="description" content="{{ pageDescription }}">
+  <meta name="color-scheme" content="dark">
+  <meta name="theme-color" content="#16171d">
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="{{ site.name }}">
+  <meta property="og:title" content="{{ pageTitle }}">
+  <meta property="og:description" content="{{ pageDescription }}">
+  <meta property="og:url" content="{{ site.url }}{{ page.url }}">
+  <link rel="canonical" href="{{ site.url }}{{ page.url }}">
+  <link rel="icon" href="/images/favicon.svg">
+  <link rel="mask-icon" href="/images/favicon-safari.svg" color="#000000">
+  <link rel="apple-touch-icon" href="/images/apple-touch-icon.svg">
+  <link rel="preload" href="/assets/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
+  <link rel="stylesheet" href="/assets/site.css">
+  {%- if home %}
+  <script>
+    // Links from the old site looked like /#/app-development/fundamentals?id=assets
+    (function () {
+      var m = /^#\/((?:[\w.-]+\/)*[\w.-]+?)(?:\.md)?\/?(?:\?id=([\w-]+))?$/.exec(location.hash);
+      if (!m) return;
+      var path = m[1].replace(/^\.\.\//, "");
+      var base = m[1] === path ? "/main/" : "/";
+      if (/(^|\/)README$/i.test(path)) path = path.replace(/\/?README$/i, "");
+      location.replace(base + (path ? path + "/" : "") + (m[2] ? "#" + m[2] : ""));
+    })();
+  </script>
+  {%- endif %}
+  <script src="/assets/site.js" defer></script>
+</head>
+<body>
+  <a class="skip" href="#main">Skip to content</a>
+  <header class="site-header">
+    <div class="wrap{% if version %} wrap-docs{% endif %}">
+      <a class="brand" href="/"><img src="/images/favicon.svg" width="28" height="28" alt="">{{ site.name }}</a>
+      {%- set searchVersion = version or (versions | first) %}
+      <div class="search" data-version="{{ searchVersion.id }}" hidden>
+        <input type="search" placeholder="Search {{ searchVersion.id }}" aria-label="Search the {{ searchVersion.id }} documentation" autocomplete="off" spellcheck="false">
+        <kbd aria-hidden="true">/</kbd>
+        <div class="search-results" role="region" aria-label="Search results" aria-live="polite" hidden></div>
+      </div>
+      <button class="nav-toggle" type="button" aria-controls="site-nav" aria-expanded="false" hidden>Menu</button>
+      <nav id="site-nav" aria-label="Main">
+        {%- for item in nav.main %}
+        <a href="{{ item.url }}"{% if not item.external and page.url.startsWith(item.url) %} aria-current="page"{% endif %}>{{ item.label }}{% if item.external %}<span aria-hidden="true"> ↗</span>{% endif %}</a>
+        {%- endfor %}
+        <a class="nav-repo" href="{{ site.repo }}">GitHub</a>
+      </nav>
+    </div>
+  </header>
+
+  <main id="main">
+    {{ content | safe }}
+  </main>
+
+  <footer class="site-footer">
+    <div class="wrap{% if version %} wrap-docs{% endif %}">
+      <ul>
+        {%- for item in nav.footer %}
+        <li><a href="{{ item.url }}">{{ item.label }}</a></li>
+        {%- endfor %}
+      </ul>
+      <ul>
+        {%- for item in site.community %}
+        <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+        {%- endfor %}
+      </ul>
+    </div>
+  </footer>
+</body>
+</html>

docs/_includes/home.njk

@@ -0,0 +1,34 @@
+---
+layout: base
+home: true
+---
+<section class="hero">
+  <div class="wrap">
+    <h1>{{ tagline }}</h1>
+    <p class="lead">{{ lead }}</p>
+  </div>
+</section>
+
+<section class="wrap versions" id="versions">
+  <h2>Choose a version</h2>
+  <div class="version-cards">
+    {%- for version in versions %}{% if version.development or version.latest %}
+    <a class="card" href="{{ version.url }}">
+      <h3>{{ version.id }} <span class="badge {% if version.development %}badge-warn{% else %}badge-yes{% endif %}">{% if version.development %}Development{% else %}Latest release{% endif %}</span></h3>
+      <p>{% if version.development %}{{ developmentText }}{% else %}{{ latestText }}{% endif %}</p>
+    </a>
+    {%- endif %}{% endfor %}
+  </div>
+  <h3>Older releases</h3>
+  <ul class="version-list">
+    {%- for version in versions %}{% if not version.development and not version.latest %}
+    <li><a href="{{ version.url }}">{{ version.id }}</a></li>
+    {%- endif %}{% endfor %}
+  </ul>
+</section>
+
+{%- if content | trim %}
+<section class="wrap home-body prose">
+  {{ content | safe }}
+</section>
+{%- endif %}

docs/_includes/page.njk

@@ -0,0 +1,63 @@
+---
+layout: base
+---
+{%- if version %}
+{%- set headings = content | headings %}
+{%- set around = version | neighbours(page.url) %}
+<div class="wrap wrap-docs docs{% if headings.length > 1 %} has-toc{% endif %}">
+  <aside class="sidebar">
+    <button class="sidebar-toggle" type="button" aria-controls="doc-nav" aria-expanded="false" hidden>Pages in {{ version.id }}</button>
+    <div id="doc-nav" class="sidebar-body">
+      <details class="version-picker">
+        <summary><span>Version</span> <strong>{{ version.id }}</strong></summary>
+        <ul>
+          {%- for other in versions %}
+          <li><a href="{{ page.inputPath | inVersion(other) }}"{% if other.id == version.id %} aria-current="true"{% endif %}>{{ other.id }}{% if other.development %} <small>development</small>{% elif other.latest %} <small>latest release</small>{% endif %}</a></li>
+          {%- endfor %}
+        </ul>
+      </details>
+      <nav aria-label="Documentation">
+        {%- for section in version.sections %}
+        {%- if section.title %}<p>{{ section.title }}</p>{% endif %}
+        <ul>
+          {%- for item in section.items %}
+          <li><a href="{{ item.url }}"{% if item.url == page.url %} aria-current="page"{% endif %}>{{ item.label }}</a></li>
+          {%- endfor %}
+        </ul>
+        {%- endfor %}
+      </nav>
+    </div>
+  </aside>
+  <article class="prose" data-pagefind-body data-pagefind-filter="version:{{ version.id }}">
+    {%- if not version.development and not version.latest %}
+    {%- set newest = versions | first %}
+    <p class="version-note" data-pagefind-ignore>This page is about Tactility {{ version.id }}, an old release. <a href="{{ page.inputPath | inVersion(newest) }}">Go to the {{ newest.id }} documentation</a>.</p>
+    {%- endif %}
+    {%- if title %}<h1>{{ title }}</h1>{% endif %}
+    {{ content | safe }}
+    {%- if around.previous or around.next %}
+    <nav class="pager" aria-label="Previous and next page" data-pagefind-ignore>
+      {%- if around.previous %}<a class="pager-previous" href="{{ around.previous.url }}"><small>Previous</small>{{ around.previous.label }}</a>{% endif %}
+      {%- if around.next %}<a class="pager-next" href="{{ around.next.url }}"><small>Next</small>{{ around.next.label }}</a>{% endif %}
+    </nav>
+    {%- endif %}
+  </article>
+  {%- if headings.length > 1 %}
+  <aside class="toc" aria-label="On this page">
+    <p>On this page</p>
+    <ul>
+      {%- for heading in headings %}
+      <li{% if heading.level == 3 %} class="toc-sub"{% endif %}><a href="#{{ heading.id }}">{{ heading.text | safe }}</a></li>
+      {%- endfor %}
+    </ul>
+  </aside>
+  {%- endif %}
+</div>
+{%- else %}
+<div class="wrap page">
+  <article class="prose">
+    {%- if title %}<h1>{{ title }}</h1>{% endif %}
+    {{ content | safe }}
+  </article>
+</div>
+{%- endif %}