# 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.