docs: scaffold Docusaurus site

.github/workflows/documentation.yml

@@ -0,0 +1,13 @@
+name: Documentation
+
+on:
+  push:
+    branches: [documentation]
+  pull_request:
+    branches: [documentation]
+
+jobs:
+  deploy:
+    uses: ConductionNL/.github/.github/workflows/documentation.yml@main
+    with:
+      cname: app-versions.conduction.nl

docs/docusaurus.config.js

@@ -0,0 +1,147 @@
+// @ts-check
+
+/**
+ * App Versions 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, navbar items — are passed
+ * through createConfig() opts.
+ *
+ * App Versions lets Nextcloud administrators roll back to an earlier
+ * version of an installed app, or pin to a newer version for
+ * compatibility testing — across the Nextcloud App Store and external
+ * sources like GitHub releases. The app is in development; this docs
+ * site provides the brand landing surface and a journeydoc tutorial
+ * scaffold.
+ */
+
+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: 'App Versions',
+  tagline: 'Install any earlier or newer version of already installed Nextcloud apps. Essential for debugging, testing compatibility, and recovering from breaking changes.',
+  url: 'https://app-versions.conduction.nl',
+  baseUrl: '/',
+
+  organizationName: 'ConductionNL',
+  projectName: 'app-versions',
+
+  /* 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 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 app-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/app-versions/tree/development/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 the app's own (Documentation sidebar link,
+     GitHub link, locale dropdown). 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/app-versions',
+        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,56 @@
+---
+sidebar_position: 1
+---
+
+# App Versions
+
+Install any earlier or newer version of already installed Nextcloud
+apps. Essential for debugging, testing compatibility, and recovering
+from a breaking change in a minor release.
+
+> **Status: in development.** This documentation site is up so the
+> brand surface and the eventual journeydoc tutorials have a stable
+> home. Step-by-step walkthroughs and screenshots land as the admin UI
+> matures. Follow the [GitHub repository](https://github.com/ConductionNL/app-versions)
+> for milestones.
+
+## What does it do?
+
+App Versions gives Nextcloud admins a version picker over every
+installed app, with three things working together:
+
+- **Multi-source.** App Versions queries the Nextcloud App Store and,
+  per app, optionally a GitHub releases endpoint — public or, with a
+  stored personal access token, private. The version list is merged
+  and labelled by origin.
+- **Rollback or pin.** Picking a version replaces the currently
+  installed one. That works in both directions: roll back to a
+  known-good release after an update breaks production, or pin to a
+  newer release candidate to test compatibility before the rest of the
+  fleet catches up.
+- **Audit-trailed.** Every install, downgrade, or pin is logged with
+  who, what, and when — so a Friday-evening rollback by an on-call
+  admin is visible Monday morning without digging through server logs.
+
+The app is built around four specs (see the openspec tracker on
+GitHub):
+
+- [`version-management`](https://github.com/ConductionNL/app-versions/tree/development/openspec/specs/version-management) — list installed apps, pick a version, install.
+- [`external-sources`](https://github.com/ConductionNL/app-versions/tree/development/openspec/specs/external-sources) — GitHub releases as a source alongside the App Store.
+- [`pat-management`](https://github.com/ConductionNL/app-versions/tree/development/openspec/specs/pat-management) — encrypted PAT storage for private GitHub repos.
+- [`app-discovery`](https://github.com/ConductionNL/app-versions/tree/development/openspec/specs/app-discovery) — a single search aggregator over the App Store, your PAT-visible repos, and (opt-in) public GitHub topic search.
+
+## Getting started
+
+The admin UI is being built. Once the first usable build is tagged, the
+tutorials below will be filled in — they are placeholders today, marked
+clearly as such.
+
+- Setting things up? The **[Admin guide](/docs/category/admin-guide)**
+  will cover the first launch, picking a version, and connecting a
+  GitHub release source.
+- Curious how it works at the API level? The specs linked above are
+  the source of truth while the user-facing documentation catches up.
+
+Free and open source under the AGPL-3.0-or-later license. For support,
+contact support@conduction.nl.