Documentation
¶
Overview ¶
Package docsite turns the canonical Markdown under docs/ into the content tree the Astro + Starlight site in website/ builds from.
docs/ is the single source of truth and is only ever read here. The site content (website/src/content/docs) and the sidebar and install data (website/src/generated) are gitignored and rebuilt by `go run ./cmd/gen-site`. The one tracked output is the install-methods region of README.md, kept byte-identical to the region in docs/installation.md.
The pipeline:
- nav.go: parse and validate docs/nav.yaml, and check every page is either listed or excluded.
- slug.go: map a docs-relative path to its site slug.
- markdown.go: derive Starlight frontmatter (title, description, editUrl) and mark pages generated by cmd/gen-reference.
- links.go: rewrite relative links to site URLs or GitHub blob URLs, and fail on targets that do not exist and on embedded images the site does not serve.
- install.go: parse the install-methods region and render the README block and the JSON the InstallTabs component reads.
- sidebar.go: build the Starlight sidebar from the manifest.
- generate.go: assemble a Plan, then Write it or Check it for drift.
Portions are adapted from Rune's internal/docsite (https://github.com/rune-task-runner/rune), used under the MIT License:
Copyright (c) Rune contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Index ¶
- Constants
- Variables
- func Coverage(nav *Nav, docsDir string) []error
- func FindRepoRoot(start string) (string, error)
- func InstallRegion(src string) (string, error)
- func RenderInstallJSON(methods []InstallMethod) ([]byte, error)
- func RewriteLinks(src, fromPath string, cfg Config) (string, error)
- func Slug(rel string) string
- func Transform(src, rel string, cfg Config) (string, error)
- func TransformInstallPage(src, rel string, cfg Config) (string, error)
- type Config
- type ExclusionEntry
- type InstallMethod
- type Nav
- type NavEntry
- type NavGroup
- type NavLink
- type NavPage
- type Options
- type Page
- type Plan
- type SidebarGroup
- type SidebarItem
Constants ¶
const ( InstallStart = "<!-- install-methods:start -->" InstallEnd = "<!-- install-methods:end -->" )
Region markers. The same pair delimits the region in docs/installation.md and in README.md.
const ( Site = "https://glapsfun.github.io" BasePath = "/gskill" BlobBase = "https://github.com/glapsfun/gskill/blob/main" EditBase = "https://github.com/glapsfun/gskill/edit/main/docs" )
Production addresses. astro.config.mjs mirrors Site and BasePath; a test in test/docs keeps the two in step.
const ExampleSkillSource = "github.com/glapsfun/gskill/examples/skills/hello-gskill"
ExampleSkillSource is the skill every runnable example adds. It lives in this repository under examples/skills/hello-gskill.
Variables ¶
var InstallLabels = []string{"Install script", "Homebrew", "Go", "npm", "npx"}
InstallLabels are the install methods, in tab order. The first is the default tab.
var RequiredGroups = []string{"Start here", "How-to guides", "Reference", "Explanation", "Contributing"}
RequiredGroups are the sidebar sections, in order. The manifest must declare exactly these.
Functions ¶
func Coverage ¶
Coverage checks the manifest against the Markdown pages actually present in docsDir and returns one error per problem: unlisted pages, missing or duplicate entries, pages both listed and excluded, and globs or exclusions that match nothing.
func FindRepoRoot ¶
FindRepoRoot walks up from start to the directory holding go.mod.
func InstallRegion ¶
InstallRegion returns the text between the install markers in src.
func RenderInstallJSON ¶
func RenderInstallJSON(methods []InstallMethod) ([]byte, error)
RenderInstallJSON renders the methods the InstallTabs component reads.
func RewriteLinks ¶
RewriteLinks rewrites every link, image, and reference definition target in src. fromPath is the docs-relative path of the page, used to resolve relative targets. Fenced code blocks and inline code spans are left alone.
func Slug ¶
Slug returns the site slug for a docs-relative page: the path without its .md extension, lowercased. The docs root README.md becomes "overview" (the site root belongs to the landing page), a README.md or index.md inside a directory becomes that directory, and a root index.md maps to "".
Types ¶
type Config ¶
type Config struct {
Site string
BasePath string
BlobBase string
EditBase string
// RepoRoot is the absolute repository root used to check that relative
// targets exist. Empty disables the check.
RepoRoot string
// Excluded reports whether a docs-relative page is unpublished. Links to
// such pages go to GitHub, since a site URL would 404.
Excluded func(rel string) bool
}
Config carries everything link rewriting and frontmatter depend on.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns the production addresses with no existence checks and no exclusions.
type ExclusionEntry ¶
ExclusionEntry keeps matching pages off the site. Reason is mandatory so a reviewer can see why a page is unpublished.
type InstallMethod ¶
type InstallMethod struct {
ID string `json:"id"`
Label string `json:"label"`
Prerequisites string `json:"prerequisites"`
Blocks []string `json:"blocks"`
}
InstallMethod is one way to install or run GSKILL. Each block is copied as a unit by the site's copy button.
func ParseInstall ¶
func ParseInstall(src string) ([]InstallMethod, error)
ParseInstall parses and validates the install region of src.
type Nav ¶
type Nav struct {
// contains filtered or unexported fields
}
Nav is the parsed navigation manifest.
type NavEntry ¶
type NavEntry struct {
}
NavEntry is one concrete published page in sidebar order, globs expanded.
type NavPage ¶
type NavPage struct {
}
NavPage is a docs-relative page path or glob, with an optional sidebar label. In YAML it is either a bare string or a {path, label} mapping.
func (*NavPage) UnmarshalJSON ¶
UnmarshalJSON accepts both the string and the mapping form of a page.
type Options ¶
type Options struct {
RepoRoot string
DocsDir string // canonical Markdown, e.g. "docs"
OutDir string // generated Starlight content tree
GeneratedDir string // generated data (sidebar, install methods)
AssetsDir string // images copied from DocsDir
LandingPath string // hand-written landing page, copied to OutDir/index.mdx
InstallPage string // docs-relative page holding the install-methods region
ReadmePath string // README kept in sync with the install region
Config Config
}
Options configures a run. Every path except RepoRoot is slash-separated and relative to RepoRoot.
func DefaultOptions ¶
DefaultOptions returns the layout this repository uses, rooted at root.
type Page ¶
type Page struct {
Title string
Description string
// EditURL is the GitHub edit link; empty renders editUrl: false.
EditURL string
// Body is the Markdown after the H1, leading blank lines removed.
Body string
}
Page is a docs page split into Starlight frontmatter fields and body.
func ParsePage ¶
ParsePage extracts the frontmatter fields from src. rel is the docs-relative path, used for the edit link and in error messages.
func (Page) Frontmatter ¶
Frontmatter renders the page's YAML frontmatter block.
type Plan ¶
type Plan struct {
Files map[string][]byte
Entries []NavEntry
// contains filtered or unexported fields
}
Plan is everything one run produces, keyed by repository-relative slash path. Only tracked files (committed outputs) are compared by Check.
type SidebarGroup ¶
type SidebarGroup struct {
Label string `json:"label"`
Items []SidebarItem `json:"items"`
}
SidebarGroup is one Starlight sidebar group.
func Sidebar ¶
func Sidebar(nav *Nav, entries []NavEntry) []SidebarGroup
Sidebar groups resolved entries under the manifest's groups, in manifest order, and appends each group's external links.
type SidebarItem ¶
type SidebarItem struct {
Label string `json:"label,omitempty"`
Slug string `json:"slug,omitempty"`
Link string `json:"link,omitempty"`
}
SidebarItem is either a page, referenced by Slug so Starlight resolves the base path and fails the build on a missing page, or an external Link. Label overrides the page title when set.