first commit

2026-10-20 09:41:46 -06:00
commit 2f9031492e
116 changed files with 3737 additions and 0 deletions
@@ -0,0 +1,57 @@
+# Federated Core documentation
+
+A Hugo site documenting the applications Federated Computer hosts for customers on Federated Core. It uses a custom built-in theme (no external theme or CDN dependencies; fonts are self-hosted).
+
+## Requirements
+
+Hugo **extended**, v0.146 or newer (built and tested with v0.168.0).
+
+## Run locally
+
+    hugo server
+
+Then open http://localhost:1313. Build for production with `hugo --minify`; the output is in `public/`.
+
+Set `baseURL` in `hugo.toml` to the address the site will be published at.
+
+## Structure
+
+    content/
+      getting-started/      How Federated Core works, sign-in, Superpanel, command-line access, help
+      apps/                 One page per application
+    layouts/                Templates (baseof, home, list, single, partials, shortcodes)
+    assets/css/main.css     All styles (light and dark mode)
+    assets/js/site.js       Search, mobile menu, "On this page" highlighting
+    static/fonts/           Public Sans and IBM Plex Mono (SIL Open Font License)
+
+## Writing app pages
+
+Create a new page with:
+
+    hugo new content apps/myapp.md
+
+Front matter drives the page header and the home page directory:
+
+| Field | Purpose |
+| --- | --- |
+| `category` | Group in the sidebar and directory. Must match a `params.appGroups` name in `hugo.toml`. |
+| `tagline` | One-sentence summary. |
+| `replaces` | Proprietary services the app can replace (shown struck through). |
+| `address` | Typical web address for the app. |
+| `website`, `upstreamDocs` | Project site and official documentation. |
+| `links` | "Further reading" list of `name` / `url` pairs. |
+
+## Shortcodes
+
+- `{{< note >}}…{{< /note >}}`: helpful tip. Optional `title="…"`.
+- `{{< warning >}}…{{< /warning >}}`: something that could cause data loss or downtime.
+- `{{< enterprise >}}…{{< /enterprise >}}`: a task that needs command-line access (Enterprise installs only). Adds a standard footer explaining this.
+- `{{< superpanel >}}…{{< /superpanel >}}`: a callout for a Superpanel step.
+- `{{< screenshot src="app/name.png" alt="…" caption="…" >}}`: a screenshot from `assets/screenshots/`, converted to WebP and linked to the full-size PNG. Indent it three spaces to place it inside a numbered step. Screenshots are taken on a Federated Core test server with `example.com` substituted for the real domain. Add `demo="true"` for the few taken on an upstream public demo; the caption then says so.
+- `{{< review "what to check" >}}`: an editorial marker that renders nothing. List all of them with:
+
+      grep -rn '< review' content/
+
+## Before publishing
+
+Superpanel option names, the address pattern for each app, and a few Federated Core specifics (for example SSH access to Gitea, the Headscale login address, and how customers edit DNS records) were written in general terms and are flagged with `review` markers. Confirm them against the current Federated Core release and remove the markers.