Documentation
¶
Overview ¶
Package docpages renders a Git repository's docs directory as a static site, with versions for main and each release. File links work as they do on GitHub.
The layout of the docs directory makes the navigation:
README.md the first page logo.svg the logo of the header, optional favicon.svg the icon of the browser tab, optional style.css loaded after the stylesheet of docpages, optional template.templ an optional page template, like any .templ file go.mod the Go module of the templates, which requires docpages 1-get-started/ a group, "Get started" icon.svg the icon of the group, optional README.md the first page of the group, optional 1-installation.md a page, at get-started/installation 2-upgrading.md 2-tutorial/ versions/ the docs of the releases, optional v1.2/ a docs directory of the same layout, for v1.2.x
Numbers order groups and pages but are omitted from URLs and titles. Page front matter can set a title, suggest the page in search, show an external file with source, or create an external link with url. The docs README front matter also holds site settings; the module README lists its keys.
Docs .templ files use package docs and replace DefaultPage with templ DocpagesMain(p Page). The go command builds them in the Go module of the docs directory, with the running docpages, which must be compatible with the version that the module requires. See VersionError.
The docs directory describes main. Snapshot makes an editable release copy under versions/.
Index ¶
- Constants
- func Body(p Page) templ.Component
- func Contents(p Page) templ.Component
- func DefaultPage(p Page) templ.Component
- func Footer(p Page, end templ.Component) templ.Component
- func FooterLinks(p Page, links ...Link) templ.Component
- func GitRoot(dir string) (string, error)
- func Handler(o Options) http.Handler
- func Head(p Page) templ.Component
- func Header(p Page) templ.Component
- func HeaderLinks(p Page, links ...Link) templ.Component
- func Layout(p Page, parts Parts) templ.Component
- func Main(p Page) templ.Component
- func Navigation(p Page) templ.Component
- func RenderMain(page func(Page) templ.Component)
- func Search(p Page) templ.Component
- func Snapshot(o Options, tag string) (string, error)
- func ThemeSwitch() templ.Component
- func VersionSelect(p Page) templ.Component
- type ContentsLink
- type Link
- type NavGroup
- type NavLink
- type Options
- type Page
- type Parts
- type Site
- type Suggestion
- type VersionError
- type VersionLink
Constants ¶
const MainVersion = "main"
MainVersion names docs-directory pages and the repository-link branch they describe.
Variables ¶
This section is empty.
Functions ¶
func Body ¶
Body renders children in <body>. Styles use its class, search its root, and style.css its version. A skip link to <main> comes first.
func Contents ¶
Contents lists sections beside the text on wide screens; it renders nothing when there are none.
func DefaultPage ¶
DefaultPage is Layout with a "Docs" header link to the first page, used when docs have no template.templ.
func Footer ¶
Footer renders the site footer: repository, child links, llms.txt, then end if non-nil.
func FooterLinks ¶
FooterLinks shows Page.URL-resolved Layout footer links between the repository and llms.txt.
func Handler ¶
Handler serves o's site at output-relative paths, as Site.Write lays it out. It rereads docs after a read file changes, showing changes without a restart, and reloads pages. Styles and scripts stay unminified. Paths follow GitHub Pages: trailing "/" serves index.html; a missing path serves its ".html" file, even with a dot as in guide/v1.2-notes. Errors such as a missing link heading are reloadable pages too.
Links to repository files no page shows open working-tree files, not the host's pushed versions. Handler serves named files, directories, and their contents, excluding dot names such as .git. Text is plain text; directories list files.
func Head ¶
Head renders a page's <head>: title, description, favicon, site styles and scripts, then children so their styles win the cascade.
func Header ¶
Header renders the site logo, version menu, Navigation button, child links, repository, search, and theme controls.
func HeaderLinks ¶
HeaderLinks shows Layout header links resolved by Page.URL. On each page, it marks the link leading there, or a first-page link if none does.
func Main ¶
Main renders <main>: the version note, narrow-screen contents, page text, and previous/next links.
func Navigation ¶
Navigation is a wide-screen column and a narrow-screen overlay opened from Header.
func RenderMain ¶
RenderMain runs a renderer built from a docs directory's .templ files, with templ DocpagesMain passed as page. It reads docs selected by flags, renders them with page, and writes them to standard output for docpages.
func Search ¶
Search renders its button and dialog. docs.js lists search.json results, or suggestions for an empty field.
func Snapshot ¶
Snapshot copies o's docs into its versions directory for release tag, such as versions/v1.2/ for v1.2.3, and returns the o.Root-relative directory. The editable copy is its own docs directory, shared by later patch releases:
- It contains README.md, groups, and linked docs files. logo.svg, favicon, and style.css stay behind because every edition uses the docs versions.
- README.md front matter loses site settings and main's note.
- A sourced page contains its source text instead of its own.
- A link outside docs becomes the file's repository URL at tag, or opens the page showing that file.
- Root-based links and media paths such as /docs/a.md become relative paths to their copies.
- Page media outside docs is copied under media/ and shown from there.
An existing release directory is an error.
func ThemeSwitch ¶
ThemeSwitch offers system, light, and dark themes as wide-screen buttons and a narrow-screen menu.
func VersionSelect ¶
VersionSelect is the version menu; docs.js opens the page in the chosen version.
Types ¶
type ContentsLink ¶
type ContentsLink struct {
Href string
Title string
Level int // Of the heading, 1 for the level 1 heading.
}
ContentsLink is a link of the contents of a page.
type Link ¶
type Link struct {
Title string
// URL is accepted by [Page.URL], such as "README.md" or an absolute URL.
URL string
// Icon appears before the title, such as a template <svg>. Nil means none.
Icon templ.Component
}
Link is a link of the header or the footer. See HeaderLinks and FooterLinks.
type Options ¶
type Options struct {
// Root is the root directory of the repository.
Root string
// Dir is the docs directory, relative to Root, as "guide" or ".".
Dir string
}
Options select the documentation that Read reads.
type Page ¶
type Page struct {
// Title appears in navigation and the browser tab.
// It is the front-matter title or level 1 heading.
Title string
// Heading is the text of the level 1 heading.
Heading string
// Description is the text of the first paragraph.
Description string
// Body is the HTML of the Markdown of the page.
Body string
// Note is the version-note HTML, empty if unset.
Note string
// Site is the name of the project.
Site string
// Version is "main" or a release such as "v1.2".
Version string
// Root is the version-folder URL, such as "../".
Root string
// Home is the URL that the logo leads to.
Home string
// Logo is logo.svg markup, empty if absent.
Logo string
// Markdown is the URL of the Markdown copy of the page.
Markdown string
// Source is the page file's URL on the repository host.
Source string
// Repository is the repository URL; Host is its host name, such as "GitHub".
Repository, Host string
// Contents lists page sections; it is empty if there are none.
Contents []ContentsLink
// Prev and Next are adjacent navigation pages; a zero NavLink means none.
Prev, Next NavLink
// Versions lists releases latest-first, then main.
Versions []VersionLink
// Suggested lists pages offered before a search query.
Suggested []Suggestion
// Indexed reports whether search engines may index the page.
Indexed bool
// contains filtered or unexported fields
}
Page is one site page as shown by a template. Its page-relative URLs work in any folder.
func (Page) URL ¶
URL resolves dest from this page. dest uses docs/README.md link syntax: a docs Markdown file such as "2-guide/1-events.md#dispatch", another repository file (resolved on its host), or a URL. A main page missing from a release falls back to main. A missing destination file or heading fails the build.
type Parts ¶
type Parts struct {
// Head is appended to <head>, for example with template fonts or scripts.
Head templ.Component
// Banner opens <body> above the header, for example with a notice of a release.
Banner templ.Component
// HeaderLinks precedes the repository link, as written by [HeaderLinks].
HeaderLinks templ.Component
FooterLinks templ.Component
FooterEnd templ.Component
}
Parts are template additions to Layout. Nil parts add nothing.
type Site ¶
type Site struct {
// contains filtered or unexported fields
}
Site contains the docs for main and every release in the versions directory.
func (*Site) Description ¶
Description returns the text of the first paragraph of the first page of main.
func (*Site) Files ¶
Files returns site files by output-relative path. Each edition directory, main/ or a release such as v1.2/, contains its pages, Markdown copies, search.json, llms.txt, llms-full.txt, and page assets. Root index.html and llms.txt lead to the latest release, or main when there are none.
type Suggestion ¶
type Suggestion struct {
Group, Title string
// Href leads to the page or outside the site.
Href string
}
Suggestion is a page offered before a search query.
type VersionError ¶
type VersionError struct {
GoMod string // Path of go.mod from the repository root, as "docs/go.mod".
Required string // Version of docpages that go.mod requires, as "v1.3.0".
Running string // Version of the running docpages, as "v1.2.0".
}
VersionError reports a docs module that requires a version of docpages that the running docpages isn't compatible with.
func (*VersionError) Error ¶
func (e *VersionError) Error() string
type VersionLink ¶
type VersionLink struct {
Version string
Current bool // Whether the page belongs to this version.
// Href is the same page in this version.
Href string
// Fallback is this version's first page, opened by docs.js if the page is absent.
Fallback string
}
VersionLink is a version in the version menu.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
docpages
command
Command docpages renders a GitHub repository's docs Markdown as a static site.
|
Command docpages renders a GitHub repository's docs Markdown as a static site. |
|
internal
|
|
|
genmorpheus
command
Command genmorpheus writes the page bundle to static/morpheus/: [components] and their dependencies plus [icons].
|
Command genmorpheus writes the page bundle to static/morpheus/: [components] and their dependencies plus [icons]. |