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/ fixes of releases, optional v1.2/ files in place of those at the tag of 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. The releases setting, as from: v1.2, makes the Git tag of the latest patch of each feature version from v1.2 on a release, read from the docs directory at that tag.
Index ¶
- Constants
- func Body(p Page) templ.Component
- func Contents(p Page) templ.Component
- func ContentsBar(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 HeaderWithoutContents(p Page) templ.Component
- func Layout(p Page, parts Parts) templ.Component
- func Main(p Page) templ.Component
- func Navigation(p Page) templ.Component
- func Offline(p Page) templ.Component
- func RenderMain(page func(Page) templ.Component)
- func Search(p Page) templ.Component
- 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. With Options.NoOffline, data-offline="false" makes docs.ts remove the worker and saved files of an earlier build. A page without Offline alone keeps them, as a template may leave it out of some pages.
func Contents ¶
Contents lists sections beside the text on wide screens, and ContentsBar on narrower ones; it renders nothing when there are none.
func ContentsBar ¶ added in v0.3.0
ContentsBar opens the contents of p over the text on screens too narrow for Contents, and renders nothing when there are none. It shows the page title until docs.ts replaces it with the current section title. Outside Header it sticks at the top of its parent, below the header on narrow screens.
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. 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, canonical link, Open Graph tags for link previews, 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, then ContentsBar.
One <neo-autohide> holds the header and the bar. On narrow screens it sticks with the navigation row and the bar in view, and hides on scroll down; docs.ts enables the hiding there, which leaves it off without scripts. On wider screens the bar sticks alone.
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 HeaderWithoutContents ¶ added in v0.3.0
HeaderWithoutContents is Header without ContentsBar, for a page that shows the bar elsewhere. On narrow screens the header sticks but doesn't hide, as the bar elsewhere can't hide with it.
func Navigation ¶
Navigation is a wide-screen column and a narrow-screen overlay opened from Header.
func Offline ¶ added in v0.3.0
Offline renders the button that saves p's version for offline viewing, or nothing with Options.NoOffline.
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.ts lists search.json results, or suggestions for an empty field.
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.ts opens the page in the chosen version. A site without releases has only main, and no menu.
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
// NoOffline omits sw.js, offline.json and [Offline].
NoOffline bool
}
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: at the tag of a
// release, or on main for main and for a file of a release folder.
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
// Canonical is the URL of the page that search engines show for this one:
// the same page in the latest release, if it has it, or this page.
// Empty for a page that search engines don't index. Absolute with
// the setting address, relative without it.
Canonical string
// 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.
func Read ¶
Read reads the documentation of o.Dir in o.Root and converts it. Releases need the git command and the tags of the repository.
func (*Site) Description ¶
Description returns the text of the first paragraph of the first page of main.
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.ts 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]. |