60 lines
3.0 KiB
Markdown
60 lines
3.0 KiB
Markdown
# 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
|
|
ai-brain/ AI Brain (placeholder)
|
|
platform/ Federated Core Platform, imported from enterprise.federated.computer
|
|
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.
|