docsite

package
v0.9.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 14 Imported by: 0

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

View Source
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.

View Source
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.

View Source
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

View Source
var InstallLabels = []string{"Install script", "Homebrew", "Go", "npm", "npx"}

InstallLabels are the install methods, in tab order. The first is the default tab.

View Source
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

func Coverage(nav *Nav, docsDir string) []error

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

func FindRepoRoot(start string) (string, error)

FindRepoRoot walks up from start to the directory holding go.mod.

func InstallRegion

func InstallRegion(src string) (string, error)

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(src, fromPath string, cfg Config) (string, error)

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

func Slug(rel string) string

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

func Transform

func Transform(src, rel string, cfg Config) (string, error)

Transform turns one docs page into a Starlight content page: frontmatter followed by the body with its links rewritten.

func TransformInstallPage

func TransformInstallPage(src, rel string, cfg Config) (string, error)

TransformInstallPage transforms docs/installation.md like any page, except that the install region becomes <InstallTabs /> and the component's import is placed directly after the frontmatter.

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

type ExclusionEntry struct {
	Path   string `json:"path"`
	Reason string `json:"reason"`
}

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 struct {
	Base    string           `json:"base"`
	Exclude []ExclusionEntry `json:"exclude"`
	Groups  []NavGroup       `json:"groups"`
	// contains filtered or unexported fields
}

Nav is the parsed navigation manifest.

func ParseNav

func ParseNav(src []byte, name string) (*Nav, error)

ParseNav parses a manifest and validates its structure. name prefixes every error message so it points at the file a maintainer has to edit.

func (n *Nav) Excluded(rel string) bool

Excluded reports whether a docs-relative path matches any exclusion.

type NavEntry struct {
	Path  string
	Label string
	Group string
}

NavEntry is one concrete published page in sidebar order, globs expanded.

type NavGroup struct {
	Group string    `json:"group"`
	Pages []NavPage `json:"pages"`
	Links []NavLink `json:"links"`
}

NavGroup is one sidebar section.

type NavLink struct {
	Label string `json:"label"`
	URL   string `json:"url"`
}

NavLink is an external sidebar link.

type NavPage struct {
	Path  string `json:"path"`
	Label string `json:"label"`
}

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 (p *NavPage) UnmarshalJSON(data []byte) error

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"
	NavPath      string // navigation manifest
	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

func DefaultOptions(root string) Options

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

func ParsePage(src, rel string, cfg Config) (Page, error)

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

func (p Page) Frontmatter() string

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.

func Build

func Build(opts Options) (*Plan, error)

Build reads the docs and the manifest and returns the Plan for them.

func (*Plan) Check

func (p *Plan) Check(root string) ([]string, error)

Check compares the tracked outputs with the files under root and returns one line per drifted file. Gitignored outputs are not compared: they are rebuilt on every run and never committed.

func (*Plan) Write

func (p *Plan) Write(root string) ([]string, error)

Write clears the managed directories, so pages removed from docs/ disappear, then writes every planned file under root. Tracked files are rewritten only when their content changed. It returns the paths written, sorted.

type SidebarGroup

type SidebarGroup struct {
	Label string        `json:"label"`
	Items []SidebarItem `json:"items"`
}

SidebarGroup is one Starlight sidebar group.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL