docs: stand up the Docusaurus docs site

.github/workflows/documentation.yml

@@ -2,12 +2,14 @@ name: Documentation
 
 on:
   push:
-    branches: [documentation]
+    branches: [main]
   pull_request:
-    branches: [documentation]
+    branches: [main]
 
 jobs:
   deploy:
+    # Reusable workflow defaults the source folder to `docs/` — the
+    # Docusaurus site now lives there (journeydoc / ADR-030).
     uses: ConductionNL/.github/.github/workflows/documentation.yml@main
     with:
-      cname: app-template.app
+      cname: deskdesk.conduction.nl

.gitignore

@@ -71,6 +71,21 @@ docker/dolphin/models/
 /docusaurus/node_modules/
 /docusaurus/build/
 /docusaurus/.docusaurus/
+
+# Docusaurus documentation site (docs/ — journeydoc / ADR-030)
+/docs/node_modules/
+/docs/build/
+/docs/.docusaurus/
+/docs/.cache-loader/
+# Generated translation files — re-enable when a Dutch translation pass ships
+/docs/i18n/nl/
+
+# Playwright (journeydoc capture + future e2e)
+/tests/e2e/test-results/
+/tests/e2e/playwright-report/
+/playwright-report/
+/playwright/.cache/
+
 # Test screenshots — images generated by browser test commands (test-app, run-test-scenario)
 # Only images are ignored; markdown reports and scenario files are kept in git.
 test-results/**/*.png

docs/docusaurus.config.js

@@ -0,0 +1,145 @@
+// @ts-check
+
+/**
+ * DeskDesk documentation site.
+ *
+ * Built on @conduction/docusaurus-preset for brand defaults (tokens,
+ * theme swizzles for Navbar / Footer, i18n scaffolding, KvK / BTW
+ * copyright). Site-specific overrides — locale (en only), sidebar
+ * path, mermaid theme, custom prism themes, deskdesk-only navbar
+ * items — are passed through createConfig() opts.
+ *
+ * Scaffolded via /journeydoc-init (ADR-030). Adapted from the
+ * decidesk docs site. DeskDesk previously had no Docusaurus site at
+ * all (only `docs/adr-audit.md`); this config is a best-effort
+ * starting point — review and tune as needed.
+ */
+
+const { createConfig, baseFooterLinks } = require('@conduction/docusaurus-preset');
+
+/* createConfig replaces themes wholesale when `themes:` is passed, so
+   we re-include the brand theme plugin alongside @docusaurus/theme-mermaid.
+   Without the brand theme entry the Navbar/Footer swizzles and
+   brand.css auto-load would silently drop. */
+const BRAND_THEME = require.resolve('@conduction/docusaurus-preset/theme');
+
+const config = createConfig({
+  title: 'DeskDesk',
+  tagline: 'Flexible desk booking for open-office environments — pick a desk on a floor, book a slot, sync to Nextcloud Calendar, and surface booking how-tos from the company wiki',
+  url: 'https://deskdesk.conduction.nl',
+  baseUrl: '/',
+
+  organizationName: 'ConductionNL',
+  projectName: 'deskdesk',
+
+  /* English-only for now (ADR-030). The brand preset ships a
+     multi-locale i18n block (nl/en/de/fr), but enabling locales
+     without translated markdown breaks SSR on doc pages — stale
+     locale metadata trips `Cannot read properties of undefined`.
+     Re-enable 'nl' once a Dutch translation pass has shipped the
+     `i18n/nl/docusaurus-plugin-content-docs/current/` markdown. */
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+    localeConfigs: {
+      en: { label: 'English' },
+    },
+  },
+
+  /* The deskdesk docs source lives at the repo root of `docs/` rather
+     than under a `docs/` subfolder, so we override the preset's default
+     `presets:` block to point `docs.path` at './' and disable the blog
+     plugin. customCss carries deskdesk-specific CSS only — brand tokens
+     and the theme swizzles are auto-loaded by the brand theme entry in
+     `themes:` below. */
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          path: './',
+          /* docs.path: './' makes plugin-content-docs scan every file
+             in docs/, which collides with plugin-content-pages's own
+             scan of docs/src/pages/. Exclude src/ (pages live there)
+             plus the standard node_modules bucket. */
+          exclude: ['**/node_modules/**', 'src/**'],
+          sidebarPath: require.resolve('./sidebars.js'),
+          editUrl: 'https://github.com/ConductionNL/deskdesk/tree/main/docs/',
+        },
+        blog: false,
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      },
+    ],
+  ],
+
+  themes: [BRAND_THEME, '@docusaurus/theme-mermaid'],
+
+  /* Brand navbar provides locale dropdown + GitHub by default; we
+     replace items[] with deskdesk's own (Documentation sidebar link,
+     deskdesk GitHub link). Object.assign in createConfig is shallow,
+     so items: replaces wholesale. */
+  navbar: {
+    items: [
+      {
+        type: 'docSidebar',
+        sidebarId: 'tutorialSidebar',
+        position: 'left',
+        label: 'Documentation',
+      },
+      {
+        href: 'https://github.com/ConductionNL/deskdesk',
+        label: 'GitHub',
+        position: 'right',
+      },
+      { type: 'localeDropdown', position: 'right' },
+    ],
+  },
+
+  /* Per-property footer override (preset 1.2.0+): we pass `links` only,
+     so the brand `style: 'dark'` and the brand KvK/BTW/IBAN/address
+     copyright string both inherit unchanged. */
+  footer: {
+    links: [
+      ...baseFooterLinks().filter((column) => column.title === 'Conduction'),
+    ],
+  },
+
+  /* Drop the canal-footer mini-games on this product-page footer
+     (preset 1.3.0+). The static skyline + canal decoration are kept;
+     the interactive layer goes away. */
+  minigames: false,
+
+  /* themeConfig is shallow-merged into the preset's defaults
+     (colorMode + navbar + footer). prism + mermaid land alongside. */
+  themeConfig: {
+    prism: {
+      theme: require('prism-react-renderer/themes/github'),
+      darkTheme: require('prism-react-renderer/themes/dracula'),
+    },
+    mermaid: {
+      theme: { light: 'default', dark: 'dark' },
+    },
+  },
+});
+
+/* createConfig doesn't pass-through arbitrary top-level fields; assign
+   markdown + onBrokenAnchors directly so they make it into the final
+   Docusaurus config. trailingSlash is left at the preset's default. */
+config.onBrokenAnchors = 'warn';
+config.markdown = {
+  mermaid: true,
+  /* Tutorial pages reference screenshots populated by
+     `tests/e2e/docs-screenshots.spec.ts`. The Playwright capture run
+     is separate from the docs build, so the build needs to succeed
+     even when a fresh checkout doesn't have every PNG yet. Warn
+     instead of failing — the absence is visible at preview time and
+     the capture spec brings everything back on demand. Flip to
+     'throw' once screenshots are committed. */
+  hooks: {
+    onBrokenMarkdownImages: 'warn',
+  },
+};
+
+module.exports = config;

docs/intro.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 1
+---
+
+# DeskDesk
+
+Flexible desk booking for open-office environments — pick a desk on a floor,
+book a slot, see it appear in your Nextcloud Calendar, and pull the booking
+how-tos straight from the company wiki. No separate booking tool, no second
+login.
+
+## What is DeskDesk?
+
+DeskDesk turns desk booking into a first-class part of the Nextcloud workspace.
+Browse the floor plan, see which desks are free for the slot you want, reserve
+one, and the booking lands in your Nextcloud Calendar automatically. Set up a
+recurring booking for the days you're always in. Open a desk and read the
+how-to articles for it — wiring, lockers, screen size — surfaced live from the
+company wiki via OpenConnector and xWiki.
+
+DeskDesk is also a reference app for the Conduction stack: all data lives as
+typed OpenRegister objects with a per-record audit trail, knowledge is
+federated through OpenConnector, and the UI follows the NL Design System. Use
+it as the starting point for building your own register-backed Nextcloud app.
+
+- **Floors, zones, desks** — model the building once; bookings hang off it
+- **Slot booking** — full-day, AM/PM, or custom slots, with conflict checks
+- **Calendar sync** — every booking mirrored into Nextcloud Calendar
+- **Recurring bookings** — claim "every Tuesday" without re-booking
+- **Desk knowledge** — how-to articles per desk, federated from the wiki
+
+## Getting started
+
+Install DeskDesk from the [Nextcloud app store](https://apps.nextcloud.com/apps/deskdesk)
+or enable it in your Nextcloud admin settings, then set up your floors, zones
+and desks on the settings page.
+
+- New here? Start with the **[User guide](./tutorials/user/)** — open the app,
+  browse desks by floor, book a slot, set up a recurring booking, and see it in
+  your calendar.
+- Setting things up for your office? See the **[Admin guide](./tutorials/admin/)**
+  — model the building, connect the wiki knowledge source, tune settings.
+
+Free and open source under the EUPL-1.2 license. For support, contact
+support@conduction.nl.