initial: zero-trust markdown tutorials site
Single-binary Go service that renders markdown pages from a runtime volume mount. Targeted at public, no-auth, no-WAF deployment behind a TLS ingress; security posture is defense-in-depth at every layer: - goldmark with no WithUnsafe — raw HTML in author markdown is stripped - CSP without 'unsafe-inline', plus HSTS, COOP, CORP, Permissions-Policy - static handler rejects non-GET/HEAD, directory listings, dotfiles, traversal - content loader rejects symlinks that escape the content root, dotfiles, and .md files larger than 1 MiB - per-page template trees (cloned from layout) so define-blocks don't collide between home/category/page - SIGHUP triggers atomic library swap — live edits on volume, no rebuild Locale layout content/<locale>/<category>/<slug>.md. Categories without _index.md still appear on the home page with a humanized name. Search is a ~70-line vanilla JS scan over /search.json?lang=<locale>; swap for a real indexer if the corpus ever balloons. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
+12
@@ -0,0 +1,12 @@
|
||||
# compiled binary (root only — don't shadow cmd/automc-tutorials/)
|
||||
/automc-tutorials
|
||||
|
||||
# test artifacts
|
||||
*.test
|
||||
*.out
|
||||
coverage.txt
|
||||
|
||||
# editor + os
|
||||
.vscode/
|
||||
.idea/
|
||||
.DS_Store
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
# --- build stage ---
|
||||
FROM golang:1.25-alpine AS build
|
||||
WORKDIR /src
|
||||
COPY go.mod go.sum ./
|
||||
RUN go mod download
|
||||
COPY . .
|
||||
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags='-s -w' \
|
||||
-o /out/automc-tutorials ./cmd/automc-tutorials
|
||||
|
||||
# --- runtime stage ---
|
||||
# Image carries only the binary. Content is provided at runtime via a volume
|
||||
# mount at /content (typically a Longhorn RWX PVC populated by `git pull` or
|
||||
# rsync from an admin shell). Live edits + SIGHUP reload = no rebuild needed.
|
||||
FROM gcr.io/distroless/static-debian12:nonroot
|
||||
WORKDIR /app
|
||||
COPY --from=build /out/automc-tutorials /app/automc-tutorials
|
||||
EXPOSE 8080
|
||||
ENV ADDR=:8080 CONTENT_DIR=/content DEFAULT_LOCALE=en
|
||||
VOLUME ["/content"]
|
||||
USER 65532:65532
|
||||
ENTRYPOINT ["/app/automc-tutorials"]
|
||||
@@ -0,0 +1,19 @@
|
||||
.PHONY: build run dev test vet docker
|
||||
|
||||
build:
|
||||
go build -o automc-tutorials ./cmd/automc-tutorials
|
||||
|
||||
run: build
|
||||
./automc-tutorials
|
||||
|
||||
dev:
|
||||
go run ./cmd/automc-tutorials
|
||||
|
||||
test:
|
||||
go test ./...
|
||||
|
||||
vet:
|
||||
go vet ./...
|
||||
|
||||
docker:
|
||||
docker build -t git.timemachine.center/timemachine/automc-tutorials:latest .
|
||||
@@ -0,0 +1,92 @@
|
||||
# automc-tutorials
|
||||
|
||||
Public-facing tutorials site for the automc Minecraft platform. Renders markdown from a mounted volume as a localized static-ish web app. No auth, no database, no state — exposed to the open internet behind TLS, hardened for zero-trust.
|
||||
|
||||
## Stack
|
||||
|
||||
- **Go** + `net/http` + `html/template` — single binary
|
||||
- **goldmark** — markdown → HTML (GFM + footnotes + auto heading IDs)
|
||||
- **Plain CSS** — no framework, dark mode via `prefers-color-scheme`
|
||||
- **Vanilla JS** — ~70-line client-side substring search, no dependency
|
||||
- Content lives on a mounted volume; reload via SIGHUP
|
||||
|
||||
## Layout
|
||||
|
||||
```
|
||||
cmd/automc-tutorials/main.go — entry: flags, signals, SIGHUP reload
|
||||
internal/content/ — loader + path-traversal guard for content/<locale>/<category>/<slug>.md
|
||||
internal/render/ — goldmark wrapper (HTML escaping on)
|
||||
internal/server/ — mux, handlers, embedded templates + /static/ bundle
|
||||
content/<locale>/<category>/ — markdown source. _index.md is the category landing page (optional).
|
||||
```
|
||||
|
||||
## Adding or editing a tutorial
|
||||
|
||||
The image carries only the binary. Markdown sits on a volume mounted at `/content` (default in the image; override with `CONTENT_DIR`). Workflow:
|
||||
|
||||
1. Open an admin shell on the host that owns the PVC (or shell into a pod that mounts the same RWX volume).
|
||||
2. Drop / edit `.md` files under `<volume>/<locale>/<category>/`.
|
||||
3. Add YAML frontmatter:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Page title
|
||||
summary: One-sentence preview shown on category list.
|
||||
order: 1
|
||||
---
|
||||
```
|
||||
|
||||
4. Write markdown. GFM tables, fenced code, footnotes, autolinks, task lists all work. Raw HTML in markdown is **escaped** — don't try to embed `<script>` or `<iframe>`, they'll render as text.
|
||||
5. Reload without restart: `kill -HUP $(pidof automc-tutorials)` inside the container, or `kubectl exec deploy/automc-tutorials -- kill -HUP 1`.
|
||||
|
||||
No rebuild, no rollout. The atomic library swap means in-flight requests keep serving the old library; new requests see the new one.
|
||||
|
||||
## Localization
|
||||
|
||||
Each top-level directory under the content root is a locale. Pages are independent per locale — translations are not auto-mapped. The header has a locale switcher that just changes `/<locale>/` in the URL.
|
||||
|
||||
If a page exists in `en` but not `cs`, switching to `cs` lands on the `cs` home (no automatic redirect, no fallback render).
|
||||
|
||||
## Search
|
||||
|
||||
Client-side substring search over `title`, `summary`, and `body`. Index served at `GET /search.json?lang=<locale>` — flat array of `{path, title, summary, body}`. `static/search.js` does a case-insensitive linear scan with crude scoring (title hit = 100, summary = 10, body = 1) and shows the top 8.
|
||||
|
||||
This is fine for a few hundred pages. If the corpus ever balloons, swap the in-browser scan for a real indexer — the endpoint contract is stable.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Var | Default | Purpose |
|
||||
|---|---|---|
|
||||
| `ADDR` | `:8080` | HTTP listen address |
|
||||
| `CONTENT_DIR` | `/content` | Path to content root (volume mount in production, `./content` in dev) |
|
||||
| `DEFAULT_LOCALE` | `en` | Locale used when none in URL (`/` → `/<locale>/`) |
|
||||
|
||||
## Zero-trust posture
|
||||
|
||||
The service is intended to sit behind TLS (k8s ingress) on the open internet, with no auth and no WAF. Hardening:
|
||||
|
||||
- **No HTML in markdown.** `goldmark.WithUnsafe()` is not enabled, so raw HTML in `.md` is escaped.
|
||||
- **CSP** restricts everything to `'self'`; `'unsafe-inline'` is absent (templates carry no inline styles or scripts). Frame ancestors blocked, base/form-action pinned to self.
|
||||
- **HSTS, COOP, CORP, Permissions-Policy** all set conservatively.
|
||||
- **No directory listing** on `/static/`; only GET/HEAD; hidden files (`/.foo`) blocked.
|
||||
- **Content loader** rejects symlinks that escape the content root, hidden files, and `.md` files larger than 1 MiB.
|
||||
- **HTTP timeouts** are set on read header, read body, write, and idle.
|
||||
- **Distroless static, runs as 65532:65532**, no shell, no package manager.
|
||||
- **No outbound calls** — the service never reaches out to anything.
|
||||
|
||||
## Build
|
||||
|
||||
```fish
|
||||
make build # binary
|
||||
make dev # go run, no build artifact
|
||||
make test # go test ./...
|
||||
make docker # Docker image
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
Single binary, distroless image, port 8080, no persistent state. Deploy as a normal k8s `Deployment` + `Service` + `Ingress` for `tutorials.timemachine.center`. Mount the content PVC read-only at `/content`. No DB, no auth, no secrets.
|
||||
|
||||
## Repo
|
||||
|
||||
Standalone Gitea repo at `git.timemachine.center/Timemachine/automc-tutorials`. Sibling of the automc orchestration repo.
|
||||
@@ -0,0 +1,63 @@
|
||||
// Command automc-tutorials serves a public, localized markdown-driven tutorials site.
|
||||
// Content lives in content/<locale>/<slug>/<page>.md and is loaded into memory at startup;
|
||||
// SIGHUP triggers a reload without restarting the server.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"flag"
|
||||
"log/slog"
|
||||
"os"
|
||||
"os/signal"
|
||||
"syscall"
|
||||
|
||||
"git.timemachine.center/Timemachine/automc-tutorials/internal/content"
|
||||
"git.timemachine.center/Timemachine/automc-tutorials/internal/server"
|
||||
)
|
||||
|
||||
func main() {
|
||||
addr := flag.String("addr", envOr("ADDR", ":8080"), "HTTP listen address")
|
||||
contentDir := flag.String("content", envOr("CONTENT_DIR", "content"), "Path to content/ directory")
|
||||
defaultLocale := flag.String("default-locale", envOr("DEFAULT_LOCALE", "en"), "Locale used when none requested")
|
||||
flag.Parse()
|
||||
|
||||
library, err := content.Load(*contentDir)
|
||||
if err != nil {
|
||||
slog.Error("loading content", "err", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
slog.Info("content loaded", "locales", library.Locales(), "pages", library.PageCount())
|
||||
|
||||
srv := server.New(library, *defaultLocale)
|
||||
|
||||
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer cancel()
|
||||
|
||||
// SIGHUP → reload content without restart. Useful in dev and for live edits in
|
||||
// container environments where rebuilding the binary is overkill.
|
||||
hup := make(chan os.Signal, 1)
|
||||
signal.Notify(hup, syscall.SIGHUP)
|
||||
go func() {
|
||||
for range hup {
|
||||
fresh, err := content.Load(*contentDir)
|
||||
if err != nil {
|
||||
slog.Error("reloading content", "err", err)
|
||||
continue
|
||||
}
|
||||
srv.SwapLibrary(fresh)
|
||||
slog.Info("content reloaded", "pages", fresh.PageCount())
|
||||
}
|
||||
}()
|
||||
|
||||
if err := srv.Run(ctx, *addr); err != nil {
|
||||
slog.Error("server error", "err", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
func envOr(key, fallback string) string {
|
||||
if v := os.Getenv(key); v != "" {
|
||||
return v
|
||||
}
|
||||
return fallback
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Instalace Minecraft klienta
|
||||
summary: Nainstaluj si Minecraft a připoj se na naše servery.
|
||||
order: 1
|
||||
---
|
||||
|
||||
# Instalace Minecraft klienta
|
||||
|
||||
Vyber edici podle toho, co máš (nebo co chceš hrát offline):
|
||||
|
||||
- **Java Edition** — oficiální launcher od Mojangu. Nutný pro naše Fabric/Paper servery.
|
||||
- **Bedrock Edition** — Windows/konzole/mobil. **Nepodporováno** na našich serverech.
|
||||
|
||||
Pokud Minecraft nevlastníš, podívej se na **offline (cracked) klient** — pořád si můžeš zahrát na serverech, které offline režim povolí (po registraci přes Discord).
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Java Edition (oficiální launcher)
|
||||
summary: Nainstaluj Mojang launcher a ověř, že tvůj účet funguje.
|
||||
order: 1
|
||||
---
|
||||
|
||||
# Java Edition (oficiální launcher)
|
||||
|
||||
Mojang/Microsoft launcher je jediná oficiálně podporovaná cesta jak hrát Java Edition.
|
||||
|
||||
## Stažení
|
||||
|
||||
1. Jdi na [minecraft.net/download](https://www.minecraft.net/cs-cz/download).
|
||||
2. Stáhni launcher pro tvůj OS:
|
||||
- **Windows:** `.msi` instalátor.
|
||||
- **macOS:** `.dmg` obraz disku.
|
||||
- **Linux:** `.deb`, `.tar.gz`, nebo přes balíčkovací systém distra (např. `sudo pacman -S minecraft-launcher` na Archu).
|
||||
3. Spusť instalátor a launcher.
|
||||
|
||||
## Přihlášení
|
||||
|
||||
Potřebuješ **Microsoft účet** s licencí Minecraftu. Pokud jsi koupil Minecraft před rokem 2020 a stále používáš Mojang účet, launcher tě vyzve k migraci — postupuj podle pokynů. Migrace je zdarma.
|
||||
|
||||
Pokud vidíš "Failed to authenticate":
|
||||
|
||||
- Zkontroluj, že tvůj Microsoft účet nebyl přepnut na dětský účet nebo přesunut do rodinné skupiny bez přístupu k Minecraftu.
|
||||
- Zkus [account.live.com/Authorize](https://account.live.com/Authorize) pro vyčištění tokenů.
|
||||
|
||||
## Vyber verzi
|
||||
|
||||
Naše servery běží na **Minecraft 1.21.4**. V launcheru:
|
||||
|
||||
1. Klikni **Installations** (nahoře).
|
||||
2. **New installation**.
|
||||
3. **Version** nastav na `release 1.21.4`.
|
||||
4. Ulož — launcher si verzi stáhne při prvním spuštění.
|
||||
|
||||
## Připojení na server
|
||||
|
||||
1. V launcheru klikni **Play** na tvé `1.21.4` instalaci.
|
||||
2. V Minecraftu: **Multiplayer** → **Add Server**.
|
||||
3. Server name: cokoliv (např. "Survival").
|
||||
4. Server address: adresa od admina (např. `survival.g.timemachine.center`).
|
||||
5. **Done** → vyber server → **Join Server**.
|
||||
|
||||
## Co dál
|
||||
|
||||
- Pokud máš placený (Java) účet: nic — server tě rozezná automaticky a spawneš se do světa.
|
||||
- Pokud placený účet nemáš: viz [offline klient](./offline-client).
|
||||
- Tak jako tak — nejprve si zaregistruj jméno na Discordu — server tě o to požádá ještě než tě pustí dovnitř.
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Offline (cracked) klient
|
||||
summary: Zahraj si bez nákupu Minecraftu — open-source launcher.
|
||||
order: 2
|
||||
---
|
||||
|
||||
# Offline (cracked) klient
|
||||
|
||||
Pokud Minecraft nemáš, můžeš hrát na serverech, které offline režim povolí. Doporučujeme **Prism Launcher** — open-source, zdarma, dobře udržovaný.
|
||||
|
||||
> **Pozn.:** offline účty se nepřipojí na oficiální servery (Hypixel atd.). Fungují jen na serverech, které je explicitně povolí. Naše platforma podporuje obojí — při registraci na Discordu si vybereš typ účtu.
|
||||
|
||||
## Stažení Prism Launcher
|
||||
|
||||
1. Jdi na [prismlauncher.org](https://prismlauncher.org/).
|
||||
2. Stáhni pro tvůj OS — Windows, macOS, Linux.
|
||||
3. Nainstaluj a otevři.
|
||||
|
||||
## První spuštění
|
||||
|
||||
Při prvním spuštění Prism požaduje účet. Klikni **Skip** — offline profil přidáme za chvíli.
|
||||
|
||||
1. Vpravo nahoře: **Accounts** → **Add Offline**.
|
||||
2. Username: musí odpovídat tomu, co si zaregistruješ na našem Discordu (3–16 znaků, písmena/čísla/podtržítka).
|
||||
3. Ulož.
|
||||
|
||||
## Přidej Minecraft instalaci
|
||||
|
||||
1. Hlavní pohled: **Add Instance**.
|
||||
2. Vyber **Vanilla** (nebo **Fabric**, pokud admin řekne).
|
||||
3. Verze: **1.21.4**.
|
||||
4. Pojmenuj (např. "automc Survival").
|
||||
5. **OK**.
|
||||
|
||||
## Spuštění + připojení
|
||||
|
||||
1. Dvojklik na instanci.
|
||||
2. Prism stáhne potřebné soubory (~100 MB).
|
||||
3. V Minecraftu: **Multiplayer** → **Add Server** → adresa od admina.
|
||||
4. Připoj se.
|
||||
|
||||
## Nejdřív registrace na Discordu
|
||||
|
||||
Než se připojíš, musíš si zaregistrovat jméno na našem Discordu:
|
||||
|
||||
1. Připoj se na Discord server (odkaz od admina).
|
||||
2. Spusť `/register`.
|
||||
3. Bot ti pošle DM — vyber **Offline** typ účtu.
|
||||
4. Napiš stejné jméno, jaké máš v Prism.
|
||||
5. Bot vygeneruje heslo — také ho pošle DM. Ulož si ho.
|
||||
|
||||
Po připojení na MC server se ozve LibreLogin — napíšeš `/login <heslo>` v chatu.
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Install Minecraft client
|
||||
summary: Get a working Minecraft client to connect to our servers.
|
||||
order: 1
|
||||
---
|
||||
|
||||
# Install Minecraft client
|
||||
|
||||
Pick the edition that matches what you bought (or want to play offline):
|
||||
|
||||
- **Java Edition** — official launcher from Mojang. Required for our Fabric/Paper servers.
|
||||
- **Bedrock Edition** — Windows/console/mobile. Currently **not supported** by our servers.
|
||||
|
||||
If you don't own Minecraft, see the **offline (cracked) client** guide — you can still play on servers that allow offline mode after registering through Discord.
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Java Edition (official launcher)
|
||||
summary: Install the Mojang launcher and verify your account works.
|
||||
order: 1
|
||||
---
|
||||
|
||||
# Java Edition (official launcher)
|
||||
|
||||
The Mojang/Microsoft launcher is the only officially supported way to play Java Edition.
|
||||
|
||||
## Download
|
||||
|
||||
1. Go to [minecraft.net/download](https://www.minecraft.net/en-us/download).
|
||||
2. Download the launcher for your OS:
|
||||
- **Windows:** `.msi` installer.
|
||||
- **macOS:** `.dmg` disk image.
|
||||
- **Linux:** `.deb`, `.tar.gz`, or via your distro's package manager (e.g. `sudo pacman -S minecraft-launcher` on Arch).
|
||||
3. Run the installer and launch it.
|
||||
|
||||
## Sign in
|
||||
|
||||
You need a **Microsoft account** with a Minecraft license attached. If you bought Minecraft before 2020 and still use a Mojang account, the launcher will prompt you to migrate — follow the steps. Migration is free.
|
||||
|
||||
If you see "Failed to authenticate":
|
||||
|
||||
- Check that your Microsoft account hasn't been switched to a child account or moved to a family group without Minecraft access.
|
||||
- Try [account.live.com/Authorize](https://account.live.com/Authorize) to clear stale tokens.
|
||||
|
||||
## Pick a version
|
||||
|
||||
Our servers run **Minecraft 1.21.4**. In the launcher:
|
||||
|
||||
1. Click **Installations** (top of the launcher).
|
||||
2. Click **New installation**.
|
||||
3. Set **Version** to `release 1.21.4`.
|
||||
4. Save — the launcher downloads it on first play.
|
||||
|
||||
## Connect to a server
|
||||
|
||||
1. From the launcher, click **Play** on your `1.21.4` installation.
|
||||
2. In Minecraft: **Multiplayer** → **Add Server**.
|
||||
3. Server name: anything (e.g. "Survival").
|
||||
4. Server address: the address you got from the admin (e.g. `survival.g.timemachine.center`).
|
||||
5. **Done** → select the server → **Join Server**.
|
||||
|
||||
## What's next
|
||||
|
||||
- If you have a paid (Java) account: nothing — the server recognizes you automatically and you'll spawn into the world.
|
||||
- If you don't have a paid account: see the [offline client](./offline-client) guide.
|
||||
- Either way, register your username on Discord first — the server will ask you to before it lets you in.
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
title: Offline (cracked) client
|
||||
summary: Play without buying Minecraft, using a free open-source launcher.
|
||||
order: 2
|
||||
---
|
||||
|
||||
# Offline (cracked) client
|
||||
|
||||
If you don't own Minecraft, you can still play on our servers that allow offline mode. We recommend **Prism Launcher** — it's open-source, free, and well-maintained.
|
||||
|
||||
> **Note:** offline accounts can't connect to Mojang's official servers (Hypixel, etc.). They work only on servers that explicitly allow them. Our platform supports both — when you register on Discord, you choose "Offline" account type.
|
||||
|
||||
## Download Prism Launcher
|
||||
|
||||
1. Go to [prismlauncher.org](https://prismlauncher.org/).
|
||||
2. Download for your OS — Windows, macOS, Linux.
|
||||
3. Install + open.
|
||||
|
||||
## First-time setup
|
||||
|
||||
On first launch, Prism asks for an account. Click **Skip** for now — we'll add an offline profile after.
|
||||
|
||||
1. Top right: **Accounts** → **Add Offline**.
|
||||
2. Username: must match what you'll register on our Discord (3–16 characters, letters/numbers/underscore).
|
||||
3. Save.
|
||||
|
||||
## Add a Minecraft installation
|
||||
|
||||
1. Main view: click **Add Instance**.
|
||||
2. Pick **Vanilla** (or **Fabric** if the admin tells you to).
|
||||
3. Version: **1.21.4**.
|
||||
4. Name it something memorable (e.g. "automc Survival").
|
||||
5. Click **OK**.
|
||||
|
||||
## Launch + connect
|
||||
|
||||
1. Double-click your instance.
|
||||
2. Prism downloads the assets first time (~100 MB).
|
||||
3. In Minecraft: **Multiplayer** → **Add Server** → enter the address the admin gave you.
|
||||
4. Connect.
|
||||
|
||||
## Register on Discord first
|
||||
|
||||
Before connecting, you must register your username on our Discord:
|
||||
|
||||
1. Join the Discord server (link from the admin).
|
||||
2. Run `/register`.
|
||||
3. The bot DMs you — pick **Offline** account type.
|
||||
4. Type the same username you set in Prism.
|
||||
5. The bot saves a password — also DMs it. Keep it.
|
||||
|
||||
When you join the MC server, it'll ask for the password in chat: type `/login <password>`.
|
||||
@@ -0,0 +1,8 @@
|
||||
module git.timemachine.center/Timemachine/automc-tutorials
|
||||
|
||||
go 1.25
|
||||
|
||||
require (
|
||||
github.com/yuin/goldmark v1.7.8
|
||||
gopkg.in/yaml.v3 v3.0.1
|
||||
)
|
||||
@@ -0,0 +1,6 @@
|
||||
github.com/yuin/goldmark v1.7.8 h1:iERMLn0/QJeHFhxSt3p6PeN9mGnvIKSpG9YYorDMnic=
|
||||
github.com/yuin/goldmark v1.7.8/go.mod h1:uzxRWxtg69N339t3louHJ7+O03ezfj6PlliRlaOzY1E=
|
||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
|
||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
|
||||
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
@@ -0,0 +1,322 @@
|
||||
// Package content loads and indexes markdown tutorial pages from disk.
|
||||
//
|
||||
// Layout on disk:
|
||||
//
|
||||
// content/
|
||||
// <locale>/ — e.g. en, cs
|
||||
// <category>/ — e.g. install-client, registration, troubleshooting
|
||||
// _index.md — category landing page (optional)
|
||||
// <slug>.md — individual tutorial page
|
||||
//
|
||||
// Each markdown file may have YAML frontmatter delimited by `---`:
|
||||
//
|
||||
// ---
|
||||
// title: Install Minecraft Java Edition
|
||||
// order: 1
|
||||
// summary: Step-by-step for installing the official launcher.
|
||||
// ---
|
||||
// # heading...
|
||||
//
|
||||
// Pages without frontmatter use the filename as title and order=999.
|
||||
package content
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strings"
|
||||
|
||||
"gopkg.in/yaml.v3"
|
||||
)
|
||||
|
||||
// Library is an in-memory index of all loaded pages. Construct via Load.
|
||||
// Read-only after construction; the server swaps whole Library values on reload.
|
||||
type Library struct {
|
||||
pages map[string]*Page // key: <locale>/<category>/<slug>
|
||||
byPath map[string][]*Page // key: <locale>/<category>, value: pages sorted by Order then Title
|
||||
locales []string // sorted, unique
|
||||
categs map[string]map[string]*Page // <locale> → <category> → category-index page (or nil if no _index.md)
|
||||
}
|
||||
|
||||
// maxPageBytes caps the size of a single markdown file. Loader skips bigger files with a stderr warning.
|
||||
// Content is operator-controlled (volume mount), but this prevents a stray dump from ballooning memory.
|
||||
const maxPageBytes = 1 << 20 // 1 MiB
|
||||
|
||||
// Page is one markdown document.
|
||||
type Page struct {
|
||||
Locale string // "en", "cs"
|
||||
Category string // "install-client"
|
||||
Slug string // "java-edition", "_index"
|
||||
Title string
|
||||
Summary string
|
||||
Order int
|
||||
Source []byte // raw markdown body (no frontmatter)
|
||||
Path string // <locale>/<category>/<slug>
|
||||
}
|
||||
|
||||
type frontmatter struct {
|
||||
Title string `yaml:"title"`
|
||||
Summary string `yaml:"summary"`
|
||||
Order int `yaml:"order"`
|
||||
}
|
||||
|
||||
// Load walks contentDir and returns a populated Library.
|
||||
// Returns an error only on filesystem-level failures; individual malformed pages are skipped with a warning written to stderr.
|
||||
//
|
||||
// Zero-trust posture: the content dir is volume-mounted in production. The loader
|
||||
// resolves the absolute path of contentDir once and rejects any entry (dir or file)
|
||||
// whose evaluated symlink target falls outside it. This prevents a misconfigured
|
||||
// volume (or an operator slipping in a symlink) from reading host files.
|
||||
func Load(contentDir string) (*Library, error) {
|
||||
info, err := os.Stat(contentDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("stat content dir %q: %w", contentDir, err)
|
||||
}
|
||||
if !info.IsDir() {
|
||||
return nil, fmt.Errorf("content path %q is not a directory", contentDir)
|
||||
}
|
||||
rootAbs, err := filepath.Abs(contentDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("abs content dir: %w", err)
|
||||
}
|
||||
rootAbs, err = filepath.EvalSymlinks(rootAbs)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("eval root symlinks: %w", err)
|
||||
}
|
||||
|
||||
lib := &Library{
|
||||
pages: make(map[string]*Page),
|
||||
byPath: make(map[string][]*Page),
|
||||
categs: make(map[string]map[string]*Page),
|
||||
}
|
||||
|
||||
localeEntries, err := os.ReadDir(contentDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read content dir: %w", err)
|
||||
}
|
||||
for _, lEntry := range localeEntries {
|
||||
name := lEntry.Name()
|
||||
if strings.HasPrefix(name, ".") || !lEntry.IsDir() {
|
||||
continue
|
||||
}
|
||||
localeDir := filepath.Join(contentDir, name)
|
||||
if !withinRoot(rootAbs, localeDir) {
|
||||
fmt.Fprintf(os.Stderr, "[content] skipping locale %q: escapes content root\n", name)
|
||||
continue
|
||||
}
|
||||
lib.locales = append(lib.locales, name)
|
||||
lib.categs[name] = make(map[string]*Page)
|
||||
|
||||
categEntries, err := os.ReadDir(localeDir)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("read locale %q: %w", name, err)
|
||||
}
|
||||
for _, cEntry := range categEntries {
|
||||
cName := cEntry.Name()
|
||||
if strings.HasPrefix(cName, ".") || !cEntry.IsDir() {
|
||||
continue
|
||||
}
|
||||
categDir := filepath.Join(localeDir, cName)
|
||||
if !withinRoot(rootAbs, categDir) {
|
||||
fmt.Fprintf(os.Stderr, "[content] skipping %s/%s: escapes content root\n", name, cName)
|
||||
continue
|
||||
}
|
||||
// Register the category even if _index.md is missing; it'll show up
|
||||
// on the home page with a humanized name.
|
||||
if _, ok := lib.categs[name][cName]; !ok {
|
||||
lib.categs[name][cName] = nil
|
||||
}
|
||||
if err := lib.loadCategory(rootAbs, name, cName, categDir); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
sort.Strings(lib.locales)
|
||||
for k := range lib.byPath {
|
||||
pages := lib.byPath[k]
|
||||
sort.SliceStable(pages, func(i, j int) bool {
|
||||
if pages[i].Order != pages[j].Order {
|
||||
return pages[i].Order < pages[j].Order
|
||||
}
|
||||
return pages[i].Title < pages[j].Title
|
||||
})
|
||||
lib.byPath[k] = pages
|
||||
}
|
||||
return lib, nil
|
||||
}
|
||||
|
||||
// withinRoot returns true if p, after resolving symlinks, is rootAbs or a descendant.
|
||||
// Used to reject volume entries that point outside the content directory.
|
||||
func withinRoot(rootAbs, p string) bool {
|
||||
abs, err := filepath.Abs(p)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
resolved, err := filepath.EvalSymlinks(abs)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
rel, err := filepath.Rel(rootAbs, resolved)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
return rel == "." || (!strings.HasPrefix(rel, "..") && !filepath.IsAbs(rel))
|
||||
}
|
||||
|
||||
func (l *Library) loadCategory(rootAbs, locale, category, dir string) error {
|
||||
files, err := os.ReadDir(dir)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
pathKey := locale + "/" + category
|
||||
for _, f := range files {
|
||||
name := f.Name()
|
||||
if strings.HasPrefix(name, ".") || f.IsDir() || !strings.HasSuffix(name, ".md") {
|
||||
continue
|
||||
}
|
||||
fp := filepath.Join(dir, name)
|
||||
if !withinRoot(rootAbs, fp) {
|
||||
fmt.Fprintf(os.Stderr, "[content] skipping %s: escapes content root\n", fp)
|
||||
continue
|
||||
}
|
||||
// Use Stat on the resolved path to enforce size cap before reading.
|
||||
info, err := os.Stat(fp)
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "[content] stat %s: %v\n", fp, err)
|
||||
continue
|
||||
}
|
||||
if info.Size() > maxPageBytes {
|
||||
fmt.Fprintf(os.Stderr, "[content] skipping %s: %d bytes exceeds %d cap\n", fp, info.Size(), maxPageBytes)
|
||||
continue
|
||||
}
|
||||
slug := strings.TrimSuffix(name, ".md")
|
||||
raw, err := os.ReadFile(fp)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
page, err := parsePage(raw, locale, category, slug)
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "[content] skipping %s: %v\n", fp, err)
|
||||
continue
|
||||
}
|
||||
key := page.Path
|
||||
l.pages[key] = page
|
||||
if slug == "_index" {
|
||||
l.categs[locale][category] = page
|
||||
} else {
|
||||
l.byPath[pathKey] = append(l.byPath[pathKey], page)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func parsePage(raw []byte, locale, category, slug string) (*Page, error) {
|
||||
body := raw
|
||||
fm := frontmatter{Order: 999}
|
||||
if bytes := raw; len(bytes) >= 4 && string(bytes[:3]) == "---" {
|
||||
// Find closing fence on its own line.
|
||||
rest := bytes[3:]
|
||||
idx := strings.Index(string(rest), "\n---")
|
||||
if idx >= 0 {
|
||||
head := rest[:idx]
|
||||
if err := yaml.Unmarshal(head, &fm); err != nil {
|
||||
return nil, fmt.Errorf("frontmatter: %w", err)
|
||||
}
|
||||
body = rest[idx+4:]
|
||||
body = trimLeadingNewline(body)
|
||||
}
|
||||
}
|
||||
if fm.Title == "" {
|
||||
fm.Title = slugToTitle(slug)
|
||||
}
|
||||
return &Page{
|
||||
Locale: locale,
|
||||
Category: category,
|
||||
Slug: slug,
|
||||
Title: fm.Title,
|
||||
Summary: fm.Summary,
|
||||
Order: fm.Order,
|
||||
Source: body,
|
||||
Path: locale + "/" + category + "/" + slug,
|
||||
}, nil
|
||||
}
|
||||
|
||||
func trimLeadingNewline(b []byte) []byte {
|
||||
if len(b) > 0 && b[0] == '\n' {
|
||||
return b[1:]
|
||||
}
|
||||
return b
|
||||
}
|
||||
|
||||
func slugToTitle(slug string) string {
|
||||
s := strings.ReplaceAll(slug, "-", " ")
|
||||
s = strings.ReplaceAll(s, "_", " ")
|
||||
if s == "" {
|
||||
return ""
|
||||
}
|
||||
return strings.ToUpper(s[:1]) + s[1:]
|
||||
}
|
||||
|
||||
// --- Accessors ---
|
||||
|
||||
func (l *Library) Locales() []string { return append([]string(nil), l.locales...) }
|
||||
func (l *Library) PageCount() int { return len(l.pages) }
|
||||
func (l *Library) HasLocale(loc string) bool {
|
||||
_, ok := l.categs[loc]
|
||||
return ok
|
||||
}
|
||||
|
||||
// Categories returns the categories in a locale, sorted by their _index.Order then name.
|
||||
type Category struct {
|
||||
Name string
|
||||
Index *Page // may be nil if no _index.md
|
||||
Pages []*Page
|
||||
}
|
||||
|
||||
func (l *Library) Categories(locale string) []Category {
|
||||
cats, ok := l.categs[locale]
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
var out []Category
|
||||
for name := range cats {
|
||||
idx := cats[name]
|
||||
out = append(out, Category{
|
||||
Name: name,
|
||||
Index: idx,
|
||||
Pages: l.byPath[locale+"/"+name],
|
||||
})
|
||||
}
|
||||
// Stable order: by index Order, then name.
|
||||
sort.SliceStable(out, func(i, j int) bool {
|
||||
oi, oj := 999, 999
|
||||
if out[i].Index != nil {
|
||||
oi = out[i].Index.Order
|
||||
}
|
||||
if out[j].Index != nil {
|
||||
oj = out[j].Index.Order
|
||||
}
|
||||
if oi != oj {
|
||||
return oi < oj
|
||||
}
|
||||
return out[i].Name < out[j].Name
|
||||
})
|
||||
return out
|
||||
}
|
||||
|
||||
// Page returns the page for a path or nil.
|
||||
func (l *Library) Page(locale, category, slug string) *Page {
|
||||
return l.pages[locale+"/"+category+"/"+slug]
|
||||
}
|
||||
|
||||
// AllPages returns every page; used by the search index endpoint.
|
||||
func (l *Library) AllPages() []*Page {
|
||||
out := make([]*Page, 0, len(l.pages))
|
||||
for _, p := range l.pages {
|
||||
out = append(out, p)
|
||||
}
|
||||
sort.Slice(out, func(i, j int) bool { return out[i].Path < out[j].Path })
|
||||
return out
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
// Package render converts markdown to HTML using goldmark.
|
||||
//
|
||||
// Zero-trust posture: raw HTML in markdown is escaped. Even though content comes from
|
||||
// an operator-mounted volume (not a request), defense-in-depth keeps a stray <script>
|
||||
// or <iframe> in a tutorial from running in a visitor's browser. Authors get goldmark
|
||||
// + GFM + footnotes; raw HTML in .md is rendered as text.
|
||||
package render
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
|
||||
"github.com/yuin/goldmark"
|
||||
"github.com/yuin/goldmark/extension"
|
||||
"github.com/yuin/goldmark/parser"
|
||||
)
|
||||
|
||||
var md = goldmark.New(
|
||||
goldmark.WithExtensions(
|
||||
extension.GFM, // tables, strikethrough, autolink, tasklist
|
||||
extension.Footnote,
|
||||
),
|
||||
goldmark.WithParserOptions(
|
||||
parser.WithAutoHeadingID(),
|
||||
),
|
||||
// No WithUnsafe() — raw HTML stays escaped.
|
||||
)
|
||||
|
||||
// Markdown renders a markdown body to HTML.
|
||||
func Markdown(source []byte) (string, error) {
|
||||
var buf bytes.Buffer
|
||||
if err := md.Convert(source, &buf); err != nil {
|
||||
return "", err
|
||||
}
|
||||
return buf.String(), nil
|
||||
}
|
||||
@@ -0,0 +1,344 @@
|
||||
// Package server is the HTTP layer: route mux, page handlers, search index endpoint.
|
||||
//
|
||||
// Routing:
|
||||
//
|
||||
// GET / → redirect to /<defaultLocale>/
|
||||
// GET /<locale>/ → home (lists categories)
|
||||
// GET /<locale>/<category>/ → category landing (lists pages)
|
||||
// GET /<locale>/<category>/<slug> → render single page
|
||||
// GET /search.json → ?lang=<locale> returns search index for client-side FlexSearch
|
||||
// GET /static/... → bundled CSS / htmx.min.js
|
||||
// GET /healthz → liveness
|
||||
package server
|
||||
|
||||
import (
|
||||
"context"
|
||||
"embed"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"html/template"
|
||||
"io/fs"
|
||||
"log/slog"
|
||||
"net/http"
|
||||
"strings"
|
||||
"sync/atomic"
|
||||
"time"
|
||||
|
||||
"git.timemachine.center/Timemachine/automc-tutorials/internal/content"
|
||||
"git.timemachine.center/Timemachine/automc-tutorials/internal/render"
|
||||
)
|
||||
|
||||
//go:embed all:templates
|
||||
var templatesFS embed.FS
|
||||
|
||||
//go:embed all:static
|
||||
var staticFS embed.FS
|
||||
|
||||
// Server holds the swappable library + per-page template trees + default locale.
|
||||
// SwapLibrary is used by SIGHUP-driven reload in main.go.
|
||||
//
|
||||
// Templates are parsed as one base tree (layout.html) plus a clone per page
|
||||
// template so that `{{define "title"}}` / `{{define "content"}}` blocks from
|
||||
// home/category/page don't overwrite each other. Rendering invokes the
|
||||
// "layout" template name from the page-specific tree.
|
||||
type Server struct {
|
||||
lib atomic.Pointer[content.Library]
|
||||
tmpls map[string]*template.Template
|
||||
defLocale string
|
||||
}
|
||||
|
||||
// New constructs a Server with the given library + default locale.
|
||||
func New(lib *content.Library, defaultLocale string) *Server {
|
||||
s := &Server{defLocale: defaultLocale, tmpls: make(map[string]*template.Template)}
|
||||
s.lib.Store(lib)
|
||||
|
||||
sub, err := fs.Sub(templatesFS, "templates")
|
||||
if err != nil {
|
||||
panic(fmt.Errorf("subFS templates: %w", err))
|
||||
}
|
||||
base := template.Must(template.New("base").Funcs(funcMap()).ParseFS(sub, "layout.html"))
|
||||
for _, name := range []string{"home.html", "category.html", "page.html"} {
|
||||
t := template.Must(base.Clone())
|
||||
template.Must(t.ParseFS(sub, name))
|
||||
s.tmpls[name] = t
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// SwapLibrary replaces the active library atomically (used by SIGHUP reload).
|
||||
func (s *Server) SwapLibrary(lib *content.Library) { s.lib.Store(lib) }
|
||||
|
||||
func (s *Server) currentLib() *content.Library { return s.lib.Load() }
|
||||
|
||||
// Run starts the HTTP server and blocks until ctx is cancelled.
|
||||
func (s *Server) Run(ctx context.Context, addr string) error {
|
||||
mux := http.NewServeMux()
|
||||
mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, _ *http.Request) {
|
||||
w.WriteHeader(http.StatusNoContent)
|
||||
})
|
||||
mux.HandleFunc("GET /search.json", s.handleSearch)
|
||||
mux.HandleFunc("GET /{$}", s.handleRoot)
|
||||
mux.HandleFunc("GET /{locale}/{$}", s.handleHome)
|
||||
mux.HandleFunc("GET /{locale}/{category}/{$}", s.handleCategory)
|
||||
mux.HandleFunc("GET /{locale}/{category}/{slug}", s.handlePage)
|
||||
|
||||
// /static/* is served BEFORE the mux to avoid pattern conflicts between
|
||||
// `/static/` and `/{locale}/{$}` (Go 1.22's mux can't pick a winner —
|
||||
// they overlap at exactly "/static/"). Wrapping order: securityHeaders
|
||||
// → staticFirst → mux.
|
||||
staticSub, err := fs.Sub(staticFS, "static")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
staticFileHandler := http.StripPrefix("/static/", http.FileServerFS(staticSub))
|
||||
staticHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
// Zero-trust posture: only GET/HEAD, no directory listings, no dotfiles.
|
||||
if r.Method != http.MethodGet && r.Method != http.MethodHead {
|
||||
w.Header().Set("Allow", "GET, HEAD")
|
||||
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
|
||||
return
|
||||
}
|
||||
path := r.URL.Path
|
||||
if strings.HasSuffix(path, "/") || strings.Contains(path, "/.") {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
w.Header().Set("Cache-Control", "public, max-age=3600")
|
||||
staticFileHandler.ServeHTTP(w, r)
|
||||
})
|
||||
|
||||
root := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if strings.HasPrefix(r.URL.Path, "/static/") {
|
||||
staticHandler.ServeHTTP(w, r)
|
||||
return
|
||||
}
|
||||
mux.ServeHTTP(w, r)
|
||||
})
|
||||
|
||||
srv := &http.Server{
|
||||
Addr: addr,
|
||||
Handler: securityHeaders(root),
|
||||
ReadHeaderTimeout: 10 * time.Second,
|
||||
ReadTimeout: 30 * time.Second,
|
||||
WriteTimeout: 60 * time.Second,
|
||||
IdleTimeout: 120 * time.Second,
|
||||
}
|
||||
|
||||
errCh := make(chan error, 1)
|
||||
go func() {
|
||||
slog.Info("listening", "addr", addr, "default_locale", s.defLocale)
|
||||
err := srv.ListenAndServe()
|
||||
if !errors.Is(err, http.ErrServerClosed) {
|
||||
errCh <- err
|
||||
return
|
||||
}
|
||||
errCh <- nil
|
||||
}()
|
||||
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||
defer cancel()
|
||||
_ = srv.Shutdown(shutdownCtx)
|
||||
return <-errCh
|
||||
case err := <-errCh:
|
||||
return err
|
||||
}
|
||||
}
|
||||
|
||||
// --- Handlers ---
|
||||
|
||||
func (s *Server) handleRoot(w http.ResponseWriter, r *http.Request) {
|
||||
http.Redirect(w, r, "/"+s.defLocale+"/", http.StatusFound)
|
||||
}
|
||||
|
||||
func (s *Server) handleHome(w http.ResponseWriter, r *http.Request) {
|
||||
locale := r.PathValue("locale")
|
||||
lib := s.currentLib()
|
||||
if !lib.HasLocale(locale) {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
s.render(w, "home.html", map[string]any{
|
||||
"Locale": locale,
|
||||
"Locales": lib.Locales(),
|
||||
"Categories": lib.Categories(locale),
|
||||
"Path": []crumb{},
|
||||
})
|
||||
}
|
||||
|
||||
func (s *Server) handleCategory(w http.ResponseWriter, r *http.Request) {
|
||||
locale := r.PathValue("locale")
|
||||
categoryName := r.PathValue("category")
|
||||
lib := s.currentLib()
|
||||
if !lib.HasLocale(locale) {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
var cat *content.Category
|
||||
for _, c := range lib.Categories(locale) {
|
||||
c := c
|
||||
if c.Name == categoryName {
|
||||
cat = &c
|
||||
break
|
||||
}
|
||||
}
|
||||
if cat == nil {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
|
||||
var indexHTML template.HTML
|
||||
if cat.Index != nil {
|
||||
out, err := render.Markdown(cat.Index.Source)
|
||||
if err == nil {
|
||||
indexHTML = template.HTML(out)
|
||||
}
|
||||
}
|
||||
s.render(w, "category.html", map[string]any{
|
||||
"Locale": locale,
|
||||
"Locales": lib.Locales(),
|
||||
"Category": cat,
|
||||
"IndexHTML": indexHTML,
|
||||
"Path": []crumb{
|
||||
{Label: titleFor(cat), URL: "/" + locale + "/" + cat.Name + "/"},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
func (s *Server) handlePage(w http.ResponseWriter, r *http.Request) {
|
||||
locale := r.PathValue("locale")
|
||||
category := r.PathValue("category")
|
||||
slug := r.PathValue("slug")
|
||||
lib := s.currentLib()
|
||||
page := lib.Page(locale, category, slug)
|
||||
if page == nil {
|
||||
http.NotFound(w, r)
|
||||
return
|
||||
}
|
||||
html, err := render.Markdown(page.Source)
|
||||
if err != nil {
|
||||
http.Error(w, "render error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
s.render(w, "page.html", map[string]any{
|
||||
"Locale": locale,
|
||||
"Locales": lib.Locales(),
|
||||
"Page": page,
|
||||
"BodyHTML": template.HTML(html),
|
||||
"Path": []crumb{
|
||||
{Label: humanize(category), URL: "/" + locale + "/" + category + "/"},
|
||||
{Label: page.Title, URL: ""},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
// handleSearch returns a flat JSON array of {path, title, summary, body} for FlexSearch
|
||||
// to index in the browser. Body is plain markdown source — small enough for the page set.
|
||||
func (s *Server) handleSearch(w http.ResponseWriter, r *http.Request) {
|
||||
lang := r.URL.Query().Get("lang")
|
||||
if lang == "" {
|
||||
lang = s.defLocale
|
||||
}
|
||||
lib := s.currentLib()
|
||||
type entry struct {
|
||||
Path string `json:"path"`
|
||||
Title string `json:"title"`
|
||||
Summary string `json:"summary,omitempty"`
|
||||
Body string `json:"body"`
|
||||
}
|
||||
var out []entry
|
||||
for _, p := range lib.AllPages() {
|
||||
if p.Locale != lang || p.Slug == "_index" {
|
||||
continue
|
||||
}
|
||||
out = append(out, entry{
|
||||
Path: "/" + p.Path,
|
||||
Title: p.Title,
|
||||
Summary: p.Summary,
|
||||
Body: string(p.Source),
|
||||
})
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
||||
w.Header().Set("Cache-Control", "public, max-age=300")
|
||||
_ = json.NewEncoder(w).Encode(out)
|
||||
}
|
||||
|
||||
// --- Helpers ---
|
||||
|
||||
type crumb struct {
|
||||
Label string
|
||||
URL string // empty for the active leaf
|
||||
}
|
||||
|
||||
func (s *Server) render(w http.ResponseWriter, name string, data map[string]any) {
|
||||
t, ok := s.tmpls[name]
|
||||
if !ok {
|
||||
slog.Error("template not found", "name", name)
|
||||
http.Error(w, "template error", http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
||||
if err := t.ExecuteTemplate(w, "layout", data); err != nil {
|
||||
slog.Error("template render", "name", name, "err", err)
|
||||
}
|
||||
}
|
||||
|
||||
func titleFor(c *content.Category) string {
|
||||
if c.Index != nil {
|
||||
return c.Index.Title
|
||||
}
|
||||
return humanize(c.Name)
|
||||
}
|
||||
|
||||
func humanize(s string) string {
|
||||
s = strings.ReplaceAll(s, "-", " ")
|
||||
s = strings.ReplaceAll(s, "_", " ")
|
||||
if s == "" {
|
||||
return ""
|
||||
}
|
||||
return strings.ToUpper(s[:1]) + s[1:]
|
||||
}
|
||||
|
||||
func funcMap() template.FuncMap {
|
||||
return template.FuncMap{
|
||||
"humanize": humanize,
|
||||
}
|
||||
}
|
||||
|
||||
// securityHeaders adds the hardening headers expected for a public, no-auth,
|
||||
// internet-facing service. The intent is zero-trust: every visitor is anonymous
|
||||
// and untrusted, and the only data we serve is rendered markdown plus the static
|
||||
// CSS/JS bundle in /static/. Headers are tuned for that surface specifically.
|
||||
//
|
||||
// - CSP is tight: 'self' for default/script/style/connect; images from data: + https:.
|
||||
// 'unsafe-inline' is deliberately absent — templates have no inline styles or
|
||||
// scripts, and goldmark output (with WithUnsafe disabled) contains neither.
|
||||
// - HSTS is set assuming TLS termination upstream (k8s ingress).
|
||||
// - COOP/CORP isolate the document from cross-origin actors.
|
||||
// - Permissions-Policy disables every browser capability we don't use.
|
||||
func securityHeaders(next http.Handler) http.Handler {
|
||||
const csp = "default-src 'self'; " +
|
||||
"img-src 'self' data: https:; " +
|
||||
"style-src 'self'; " +
|
||||
"script-src 'self'; " +
|
||||
"connect-src 'self'; " +
|
||||
"object-src 'none'; " +
|
||||
"base-uri 'self'; " +
|
||||
"form-action 'self'; " +
|
||||
"frame-ancestors 'none'"
|
||||
const permissionsPolicy = "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"
|
||||
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
h := w.Header()
|
||||
h.Set("X-Content-Type-Options", "nosniff")
|
||||
h.Set("X-Frame-Options", "DENY")
|
||||
h.Set("Referrer-Policy", "no-referrer")
|
||||
h.Set("Strict-Transport-Security", "max-age=31536000; includeSubDomains")
|
||||
h.Set("Cross-Origin-Opener-Policy", "same-origin")
|
||||
h.Set("Cross-Origin-Resource-Policy", "same-origin")
|
||||
h.Set("Content-Security-Policy", csp)
|
||||
h.Set("Permissions-Policy", permissionsPolicy)
|
||||
next.ServeHTTP(w, r)
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
// search.js — minimal client-side search.
|
||||
// Loads /search.json?lang=<locale>, builds an in-memory index, renders results
|
||||
// as the user types in the header search box.
|
||||
//
|
||||
// Deliberately tiny — no FlexSearch dependency yet (the page set is small,
|
||||
// linear scan with case-insensitive substring is plenty). Swap in FlexSearch
|
||||
// or Lunr if the corpus grows past a few hundred pages.
|
||||
(function () {
|
||||
const input = document.getElementById('search-input');
|
||||
const results = document.getElementById('search-results');
|
||||
if (!input || !results) return;
|
||||
|
||||
const lang = document.documentElement.lang || 'en';
|
||||
let pages = [];
|
||||
let loaded = false;
|
||||
|
||||
function loadIndex() {
|
||||
if (loaded) return Promise.resolve();
|
||||
return fetch('/search.json?lang=' + encodeURIComponent(lang))
|
||||
.then(r => r.json())
|
||||
.then(data => { pages = data || []; loaded = true; })
|
||||
.catch(() => { /* silent — search just stays empty */ });
|
||||
}
|
||||
|
||||
function escapeHtml(s) {
|
||||
return String(s).replace(/[&<>"']/g, c => ({'&':'&','<':'<','>':'>','"':'"',"'":'''}[c]));
|
||||
}
|
||||
|
||||
function search(q) {
|
||||
if (!q || q.length < 2) return [];
|
||||
const needle = q.toLowerCase();
|
||||
const out = [];
|
||||
for (const p of pages) {
|
||||
const titleHit = p.title && p.title.toLowerCase().includes(needle);
|
||||
const summaryHit = p.summary && p.summary.toLowerCase().includes(needle);
|
||||
const bodyHit = p.body && p.body.toLowerCase().includes(needle);
|
||||
if (titleHit || summaryHit || bodyHit) {
|
||||
// crude scoring: title > summary > body
|
||||
const score = (titleHit ? 100 : 0) + (summaryHit ? 10 : 0) + (bodyHit ? 1 : 0);
|
||||
out.push({ ...p, score });
|
||||
}
|
||||
if (out.length >= 50) break;
|
||||
}
|
||||
out.sort((a, b) => b.score - a.score);
|
||||
return out.slice(0, 8);
|
||||
}
|
||||
|
||||
function render(matches) {
|
||||
if (!matches.length) { results.hidden = true; results.innerHTML = ''; return; }
|
||||
results.innerHTML = matches.map(m =>
|
||||
`<li><a href="${escapeHtml(m.path)}">
|
||||
<span class="title">${escapeHtml(m.title)}</span>
|
||||
${m.summary ? `<span class="summary">${escapeHtml(m.summary)}</span>` : ''}
|
||||
</a></li>`
|
||||
).join('');
|
||||
results.hidden = false;
|
||||
}
|
||||
|
||||
let timer = null;
|
||||
input.addEventListener('focus', loadIndex);
|
||||
input.addEventListener('input', () => {
|
||||
clearTimeout(timer);
|
||||
timer = setTimeout(() => {
|
||||
loadIndex().then(() => render(search(input.value.trim())));
|
||||
}, 80);
|
||||
});
|
||||
input.addEventListener('blur', () => {
|
||||
// Delay so click on a result registers before hiding.
|
||||
setTimeout(() => { results.hidden = true; }, 150);
|
||||
});
|
||||
})();
|
||||
@@ -0,0 +1,152 @@
|
||||
/* automc-tutorials — minimal opinionated CSS, no framework. */
|
||||
* { box-sizing: border-box; }
|
||||
html { font: 16px/1.55 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; color: #222; background: #fff; }
|
||||
body { margin: 0; }
|
||||
a { color: #2c5fa3; text-decoration: none; }
|
||||
a:hover { text-decoration: underline; }
|
||||
|
||||
.site-header {
|
||||
display: flex; align-items: center; gap: 1rem;
|
||||
padding: 0.75rem 1.25rem;
|
||||
border-bottom: 1px solid #e5e5e5;
|
||||
background: #fafafa;
|
||||
position: sticky; top: 0; z-index: 10;
|
||||
}
|
||||
.brand { font-weight: 700; font-size: 1.05rem; color: #222; }
|
||||
.brand:hover { text-decoration: none; }
|
||||
|
||||
.search { position: relative; flex: 1; max-width: 28rem; }
|
||||
.search input {
|
||||
width: 100%; padding: 0.4rem 0.6rem;
|
||||
border: 1px solid #ccc; border-radius: 6px;
|
||||
font: inherit;
|
||||
}
|
||||
#search-results {
|
||||
position: absolute; top: 100%; left: 0; right: 0;
|
||||
margin: 0.25rem 0 0; padding: 0; list-style: none;
|
||||
background: #fff; border: 1px solid #ddd; border-radius: 6px;
|
||||
max-height: 18rem; overflow-y: auto;
|
||||
box-shadow: 0 4px 12px rgba(0,0,0,0.08);
|
||||
}
|
||||
#search-results li { padding: 0; }
|
||||
#search-results a {
|
||||
display: block; padding: 0.5rem 0.75rem;
|
||||
border-bottom: 1px solid #f0f0f0;
|
||||
color: #222;
|
||||
}
|
||||
#search-results a:hover { background: #f4f7fb; text-decoration: none; }
|
||||
#search-results .title { font-weight: 600; }
|
||||
#search-results .summary { display: block; font-size: 0.85rem; color: #666; }
|
||||
|
||||
.locale-switch a.lang {
|
||||
display: inline-block;
|
||||
padding: 0.25rem 0.5rem;
|
||||
margin-left: 0.25rem;
|
||||
border-radius: 4px;
|
||||
text-transform: uppercase;
|
||||
font-size: 0.8rem;
|
||||
color: #555;
|
||||
}
|
||||
.locale-switch a.lang.active { background: #2c5fa3; color: #fff; }
|
||||
|
||||
.breadcrumbs {
|
||||
padding: 0.5rem 1.25rem;
|
||||
font-size: 0.9rem; color: #666;
|
||||
border-bottom: 1px solid #f0f0f0;
|
||||
}
|
||||
.breadcrumbs .sep { margin: 0 0.4rem; color: #aaa; }
|
||||
.breadcrumbs .active { color: #222; }
|
||||
|
||||
main {
|
||||
max-width: 50rem;
|
||||
margin: 0 auto;
|
||||
padding: 2rem 1.25rem;
|
||||
}
|
||||
|
||||
h1 { font-size: 1.75rem; margin: 0 0 0.5rem; }
|
||||
h2 { font-size: 1.35rem; margin: 1.5rem 0 0.5rem; }
|
||||
.lead { font-size: 1.1rem; color: #555; margin: 0.5rem 0 1.5rem; }
|
||||
|
||||
.category-list { list-style: none; padding: 0; display: grid; gap: 1rem; }
|
||||
.category-item a {
|
||||
display: block;
|
||||
padding: 1rem 1.25rem;
|
||||
border: 1px solid #e0e0e0;
|
||||
border-radius: 8px;
|
||||
color: #222;
|
||||
transition: border-color 0.15s, box-shadow 0.15s;
|
||||
}
|
||||
.category-item a:hover {
|
||||
border-color: #2c5fa3;
|
||||
box-shadow: 0 2px 8px rgba(44,95,163,0.1);
|
||||
text-decoration: none;
|
||||
}
|
||||
.category-item h2 { margin: 0 0 0.25rem; font-size: 1.15rem; }
|
||||
.category-item p { margin: 0.25rem 0; color: #555; }
|
||||
.category-item .page-count { font-size: 0.85rem; color: #888; }
|
||||
|
||||
.page-list { list-style: none; padding: 0; }
|
||||
.page-list li { margin-bottom: 0.5rem; }
|
||||
.page-list a {
|
||||
display: block;
|
||||
padding: 0.6rem 0.8rem;
|
||||
border-left: 3px solid transparent;
|
||||
border-radius: 4px;
|
||||
}
|
||||
.page-list a:hover { border-left-color: #2c5fa3; background: #f7f9fc; text-decoration: none; }
|
||||
.page-list strong { color: #222; }
|
||||
.page-list .summary { display: block; font-size: 0.9rem; color: #666; margin-top: 0.15rem; }
|
||||
|
||||
.page-header { margin-bottom: 1.5rem; }
|
||||
.page-header .summary { color: #555; font-size: 1.05rem; }
|
||||
|
||||
.prose { line-height: 1.7; }
|
||||
.prose code {
|
||||
background: #f4f4f5; padding: 0.1rem 0.35rem; border-radius: 3px;
|
||||
font-size: 0.9em; font-family: ui-monospace, "SF Mono", Menlo, monospace;
|
||||
}
|
||||
.prose pre {
|
||||
background: #1e1e2e; color: #cdd6f4;
|
||||
padding: 1rem; border-radius: 8px; overflow-x: auto;
|
||||
font-size: 0.9rem; line-height: 1.5;
|
||||
}
|
||||
.prose pre code { background: transparent; padding: 0; color: inherit; }
|
||||
.prose img { max-width: 100%; border-radius: 8px; }
|
||||
.prose blockquote {
|
||||
border-left: 4px solid #2c5fa3;
|
||||
margin: 1rem 0; padding: 0.5rem 1rem;
|
||||
background: #f7f9fc;
|
||||
}
|
||||
.prose table { border-collapse: collapse; width: 100%; margin: 1rem 0; }
|
||||
.prose th, .prose td { border: 1px solid #e0e0e0; padding: 0.5rem 0.75rem; text-align: left; }
|
||||
.prose th { background: #fafafa; }
|
||||
|
||||
.site-footer {
|
||||
margin-top: 4rem;
|
||||
padding: 1.5rem 1.25rem;
|
||||
border-top: 1px solid #e5e5e5;
|
||||
text-align: center;
|
||||
font-size: 0.85rem;
|
||||
color: #888;
|
||||
}
|
||||
|
||||
@media (prefers-color-scheme: dark) {
|
||||
html { color: #ddd; background: #1a1a1a; }
|
||||
.site-header { background: #222; border-color: #333; }
|
||||
.brand { color: #ddd; }
|
||||
a { color: #6aa2dc; }
|
||||
.search input { background: #2a2a2a; border-color: #444; color: #ddd; }
|
||||
#search-results { background: #222; border-color: #444; }
|
||||
#search-results a { color: #ddd; border-color: #2f2f2f; }
|
||||
#search-results a:hover { background: #2a2f3a; }
|
||||
.breadcrumbs { color: #999; border-color: #333; }
|
||||
.breadcrumbs .active { color: #eee; }
|
||||
.category-item a { background: #222; border-color: #333; color: #ddd; }
|
||||
.category-item a:hover { border-color: #6aa2dc; }
|
||||
.page-list a:hover { background: #2a2a2a; }
|
||||
.prose code { background: #2a2a2a; color: #f4f4f5; }
|
||||
.prose blockquote { background: #222; }
|
||||
.prose th { background: #222; }
|
||||
.prose th, .prose td { border-color: #333; }
|
||||
.site-footer { border-color: #333; color: #777; }
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{{define "title"}}{{if .Category.Index}}{{.Category.Index.Title}}{{else}}{{humanize .Category.Name}}{{end}} · automc tutorials{{end}}
|
||||
{{define "content"}}
|
||||
<article class="category">
|
||||
<h1>{{if .Category.Index}}{{.Category.Index.Title}}{{else}}{{humanize .Category.Name}}{{end}}</h1>
|
||||
{{with .IndexHTML}}<div class="prose">{{.}}</div>{{end}}
|
||||
|
||||
<ul class="page-list">
|
||||
{{range .Category.Pages}}
|
||||
<li>
|
||||
<a href="/{{$.Locale}}/{{.Category}}/{{.Slug}}">
|
||||
<strong>{{.Title}}</strong>
|
||||
{{with .Summary}}<span class="summary">{{.}}</span>{{end}}
|
||||
</a>
|
||||
</li>
|
||||
{{end}}
|
||||
</ul>
|
||||
</article>
|
||||
{{end}}
|
||||
@@ -0,0 +1,17 @@
|
||||
{{define "title"}}automc tutorials{{end}}
|
||||
{{define "content"}}
|
||||
<h1>Tutorials</h1>
|
||||
<p class="lead">Pick a topic. New here? Start with <strong>install client</strong>, then <strong>register</strong>.</p>
|
||||
|
||||
<ul class="category-list">
|
||||
{{range .Categories}}
|
||||
<li class="category-item">
|
||||
<a href="/{{$.Locale}}/{{.Name}}/">
|
||||
<h2>{{if .Index}}{{.Index.Title}}{{else}}{{humanize .Name}}{{end}}</h2>
|
||||
{{with .Index}}{{with .Summary}}<p>{{.}}</p>{{end}}{{end}}
|
||||
<span class="page-count">{{len .Pages}} page{{if ne (len .Pages) 1}}s{{end}}</span>
|
||||
</a>
|
||||
</li>
|
||||
{{end}}
|
||||
</ul>
|
||||
{{end}}
|
||||
@@ -0,0 +1,43 @@
|
||||
{{define "layout"}}<!doctype html>
|
||||
<html lang="{{.Locale}}">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>{{block "title" .}}automc tutorials{{end}}</title>
|
||||
<link rel="stylesheet" href="/static/style.css">
|
||||
</head>
|
||||
<body>
|
||||
<header class="site-header">
|
||||
<a class="brand" href="/{{.Locale}}/">automc tutorials</a>
|
||||
<div class="search">
|
||||
<input type="search" id="search-input" placeholder="Search..." autocomplete="off">
|
||||
<ul id="search-results" hidden></ul>
|
||||
</div>
|
||||
<nav class="locale-switch">
|
||||
{{range .Locales}}
|
||||
<a href="/{{.}}/" class="lang {{if eq . $.Locale}}active{{end}}">{{.}}</a>
|
||||
{{end}}
|
||||
</nav>
|
||||
</header>
|
||||
|
||||
{{with .Path}}
|
||||
<nav class="breadcrumbs">
|
||||
<a href="/{{$.Locale}}/">home</a>
|
||||
{{range .}}
|
||||
<span class="sep">›</span>
|
||||
{{if .URL}}<a href="{{.URL}}">{{.Label}}</a>{{else}}<span class="active">{{.Label}}</span>{{end}}
|
||||
{{end}}
|
||||
</nav>
|
||||
{{end}}
|
||||
|
||||
<main>
|
||||
{{block "content" .}}{{end}}
|
||||
</main>
|
||||
|
||||
<footer class="site-footer">
|
||||
<span>automc-tutorials · <a href="https://git.timemachine.center/Timemachine/automc-tutorials">source</a></span>
|
||||
</footer>
|
||||
|
||||
<script src="/static/search.js" defer></script>
|
||||
</body>
|
||||
</html>{{end}}
|
||||
@@ -0,0 +1,10 @@
|
||||
{{define "title"}}{{.Page.Title}} · automc tutorials{{end}}
|
||||
{{define "content"}}
|
||||
<article class="page">
|
||||
<header class="page-header">
|
||||
<h1>{{.Page.Title}}</h1>
|
||||
{{with .Page.Summary}}<p class="summary">{{.}}</p>{{end}}
|
||||
</header>
|
||||
<div class="prose">{{.BodyHTML}}</div>
|
||||
</article>
|
||||
{{end}}
|
||||
Reference in New Issue
Block a user