docpages

package module
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 66 Imported by: 0

README

docpages

CI Go Reference

docpages is a simplicity-oriented static site generator that renders Markdown files from a docs folder of a Git repository as a CDN-hostable documentation site, optionally with a version for main and for each release. The folders and file names make the navigation, links work as they do on GitHub, and a link to a file or a heading that doesn't exist fails the build.

The generated site has search in the browser, opt-in offline viewing, light and dark themes, and llms.txt for language models.

go run github.com/romshark/docpages/cmd/docpages@latest -serve 127.0.0.1:7340 docs

-serve previews the site and reloads it on changes, and -o site writes it. docpages needs Go 1.27.4 or later.

Compared to other tools

docpages Hugo Docusaurus VitePress Starlight MkDocs Zensical mdBook
Ecosystem Go Go npm npm npm pip pip Cargo
Structure Folder and file names Folders and weight sidebars.js or folders Config Config or folders mkdocs.yml or folders zensical.toml or folders SUMMARY.md
Relative .md links Yes With a render hook Yes Yes With a plugin Yes Yes Yes
Versions* Yes No Yes With a plugin With a plugin With mike With mike No
Search Yes With a theme Algolia or a plugin Yes Yes Yes Yes Yes
Offline** Yes With a module With a plugin With a plugin With a plugin No No No
Plugins Not yet 🚧 Yes Yes Yes Yes Yes Built-in only Yes
Templates templ Go templates React components Vue components Astro components Jinja Jinja Handlebars

* Versions are the docs at each release tag, with a menu that switches between them.

** Offline is a copy of the site that a service worker keeps in the browser, to read without a network. MkDocs, Zensical and mdBook can instead build the site as files to open from disk.

Documentation

The documentation is a docpages site itself, at romshark.github.io/docpages, built from docs/:

example/cli and example/library are complete docs folders, each in a style of its own. See https://romshark.github.io/docpages/example/cli/ and https://romshark.github.io/docpages/example/library/

Development

make gen writes the Go code of the templ templates, static/style.min.css, the Morpheus bundle, and static/docs.min.js and static/sw.min.js, which esbuild compiles from web/style.css and the TypeScript of web/docs.ts and web/sw/sw.ts. They are committed, and CI fails when they are out of date. Building docpages needs only Go. make fmt formats the Go code with gofumpt, which CI checks too.

make check lints and format-checks the TypeScript and web/style.css with Biome, and type-checks the TypeScript with tsc, as CI does. It needs Node 24, pnpm and a pnpm install in web/. pnpm run format there formats the TypeScript.

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

View Source
const MainVersion = "main"

MainVersion names docs-directory pages and the repository-link branch they describe.

Variables

This section is empty.

Functions

func Body

func Body(p Page) templ.Component

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

func Contents(p Page) templ.Component

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

func ContentsBar(p Page) templ.Component

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

func DefaultPage(p Page) templ.Component

DefaultPage is Layout with a "Docs" header link to the first page, used when docs have no template.templ.

func Footer(p Page, end templ.Component) templ.Component

Footer renders the site footer: repository, child links, llms.txt, then end if non-nil.

func FooterLinks(p Page, links ...Link) templ.Component

FooterLinks shows Page.URL-resolved Layout footer links between the repository and llms.txt.

func GitRoot

func GitRoot(dir string) (string, error)

GitRoot returns the root directory of the Git repository that holds dir.

func Handler

func Handler(o Options) http.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(p Page) templ.Component

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(p Page) templ.Component

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(p Page, links ...Link) templ.Component

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

func HeaderWithoutContents(p Page) templ.Component

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 Layout

func Layout(p Page, parts Parts) templ.Component

Layout is the built-in page with template parts.

func Main

func Main(p Page) templ.Component

Main renders <main>: the version note, page text, and previous/next links.

func Navigation(p Page) templ.Component

Navigation is a wide-screen column and a narrow-screen overlay opened from Header.

func Offline added in v0.3.0

func Offline(p Page) templ.Component

Offline renders the button that saves p's version for offline viewing, or nothing with Options.NoOffline.

func RenderMain

func RenderMain(page func(Page) templ.Component)

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(p Page) templ.Component

Search renders its button and dialog. docs.ts lists search.json results, or suggestions for an empty field.

func ThemeSwitch

func ThemeSwitch() templ.Component

ThemeSwitch offers system, light, and dark themes as wide-screen buttons and a narrow-screen menu.

func VersionSelect

func VersionSelect(p Page) templ.Component

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 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 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 NavGroup struct {
	Title string
	Icon  string // SVG markup, empty without an icon.
	Links []NavLink
}

NavGroup is a group of the navigation.

type NavLink struct {
	Title    string
	Href     string
	Current  bool // Whether the link leads to the page that shows it.
	External bool // Whether the link leaves the site.
}

NavLink is a navigation, previous, or next link.

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 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
	Navigation       []NavGroup
	// 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

func (p Page) URL(dest string) (string, error)

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 sits between the repository and llms.txt, as written by [FooterLinks].
	FooterLinks templ.Component
	// FooterEnd appears at the end of the footer, for example with a license.
	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

func Read(o Options) (*Site, error)

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

func (s *Site) Description() string

Description returns the text of the first paragraph of the first page of main.

func (*Site) Files

func (s *Site) Files() (map[string][]byte, error)

Files returns the site's files by output-relative path, a directory per version, as main/ or v1.2/, plus index.html and llms.txt, which lead to the latest release or main.

func (*Site) Write

func (s *Site) Write(out string) error

Write writes the site to out. It first removes prior generated files, including edition directories, so deleted docs leave no stale pages.

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

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

Jump to

Keyboard shortcuts

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