internal/help

package help // import "git.griefed.de/griefed/repoman/internal/help"

Package help is repoman's in-app user manual. Each help topic's prose lives in
a Markdown file (web/help/<slug>.md, embedded via the frontend package) and is
rendered to HTML with goldmark at startup; the ordered Topics registry below
supplies the metadata that drives the /help index, the nav, and the contextual
"?" deep-links scattered through the UI. Keeping the registry in Go (not in the
Markdown front-matter) keeps it grep-able and lets a missing file fail the boot.

VARIABLES

var Topics = []Topic{
	{
		Slug:    "overview",
		Title:   "What is repoman?",
		Area:    AreaGettingStarted,
		Summary: "The big picture: what repoman does and the core concepts.",
	},
	{
		Slug:    "dashboard",
		Title:   "The dashboard",
		Area:    AreaGettingStarted,
		Summary: "Reading the home page: counts, schedules, and recent activity.",
	},
	{
		Slug:    "configs",
		Title:   "Migration configs",
		Area:    AreaConfigs,
		Summary: "Create and manage the configs that define what to import and where.",
	},
	{
		Slug:    "sources-and-tokens",
		Title:   "Sources & access tokens",
		Area:    AreaConfigs,
		Summary: "Per-source platforms, instance URLs, and how access tokens resolve.",
	},
	{
		Slug:    "outbound-sync",
		Title:   "Outbound sync & release HA",
		Area:    AreaConfigs,
		Summary: "Import-only vs pushing mirrors back out, and release parity across targets.",
	},
	{
		Slug:    "issue-hub",
		Title:   "Issue & comment sync",
		Area:    AreaConfigs,
		Summary: "The bidirectional issue hub between Forgejo and your sources.",
	},
	{
		Slug:    "runs",
		Title:   "Runs, dry-runs & the monitor",
		Area:    AreaRunning,
		Summary: "Triggering runs, what a dry-run does, and the live log monitor.",
	},
	{
		Slug:    "schedules",
		Title:   "Schedules",
		Area:    AreaRunning,
		Summary: "Cron expressions and how repoman decides the next scheduled run.",
	},
	{
		Slug:    "inventory",
		Title:   "Inventory & downloads",
		Area:    AreaData,
		Summary: "Browsing synced repositories and downloading restorable .zip mirrors.",
	},
	{
		Slug:    "notifications",
		Title:   "Notifications",
		Area:    AreaData,
		Summary: "The in-app notification feed and when email copies are sent.",
	},
	{
		Slug:      "settings",
		Title:     "Global settings",
		Area:      AreaAdmin,
		AdminOnly: true,
		Summary:   "Forgejo target, SMTP, auth policy, and token-expiry warnings.",
	},
	{
		Slug:      "backups-and-restore",
		Title:     "Backups & restore",
		Area:      AreaAdmin,
		AdminOnly: true,
		Summary:   "Scheduled snapshots, GFS retention, and the staged-restore flow.",
	},
	{
		Slug:      "users-and-roles",
		Title:     "Users, roles & permissions",
		Area:      AreaAdmin,
		AdminOnly: true,
		Summary:   "The admin/operator/read-only roles and what each one can do.",
	},
	{
		Slug:    "account",
		Title:   "Your profile",
		Area:    AreaAccount,
		Summary: "Password, two-factor auth, timezone, personal tokens, and themes.",
	},
	{
		Slug:    "themes",
		Title:   "Themes & the builder",
		Area:    AreaAccount,
		Summary: "Selecting themes, building your own, and submitting one to share.",
	},
}
    Topics is the ordered registry of every help page. Adding a topic = add an
    entry here and drop a matching web/help/<slug>.md file; Load fails the boot
    if the file is missing, so the two can never drift.


TYPES

type Area string
    Area groups related topics under one heading on the /help index. The order
    of the Area constants below is the order the index renders the groups in.

const (
	AreaGettingStarted Area = "Getting started"
	AreaConfigs        Area = "Migration configs"
	AreaRunning        Area = "Running migrations"
	AreaData           Area = "Your data"
	AreaAdmin          Area = "Administration"
	AreaAccount        Area = "Your profile"
)
    The topic areas, in index-display order.

type Group struct {
	Area   Area
	Topics []Topic
}
    Group is one Area's topics on the index page, in registry order.

type Manual struct {
	// Has unexported fields.
}
    Manual is the loaded, rendered help: the topic registry plus each topic's
    pre-rendered HTML. Built once at startup by Load and then read-only,
    mirroring the parse-once-at-boot policy used for templates and themes.

func Load(fsys fs.FS, dir string) (*Manual, error)
    Load reads and renders every registered topic's Markdown file from fsys
    under dir (e.g. "web/help"), returning the assembled Manual. It fails if the
    registry is malformed (empty/duplicate slug) or a topic's file is missing
    or unrenderable — so a boot-time Load surfaces content drift immediately
    instead of 404-ing live.

func (m *Manual) Groups() []Group
    Groups returns every topic grouped by Area in index-display order,
    preserving registry order within each group and omitting empty areas. Help
    text is not secret, so the index shows all topics to everyone; admin-only
    ones carry a badge (Topic.AdminOnly) rather than being filtered out.

func (m *Manual) HTML(slug string) (template.HTML, bool)
    HTML returns a topic's pre-rendered HTML and whether the topic exists.

func (m *Manual) Topic(slug string) (Topic, bool)
    Topic returns the topic with the given slug and whether it exists.

func (m *Manual) Topics() []Topic
    Topics returns every topic in registry order.

type Topic struct {
	Slug      string
	Title     string
	Area      Area
	AdminOnly bool
	Summary   string
}
    Topic is one help page: the metadata for a Markdown file under web/help.
    Slug is both the URL segment (/help/<slug>) and the file name (<slug>.md).
    AdminOnly badges the topic "Admin" on the index — purely informational,
    since help text is not secret; it does not gate access. Summary is the
    one-line blurb on the index.

Generated by docs/dev/gen.sh from go doc -all git.griefed.de/griefed/repoman/internal/help. Edit the doc comments in the source, not this file.