docpages

package module
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 57 Imported by: 0

README

docpages

CI Go Reference

docpages renders the Markdown files of a docs folder of a Git repository as a static documentation site, 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 site has search in the browser, 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.3 or later.

Compared to other tools

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

* Versions are copies of the docs for each release, with a menu that switches between them.

Documentation

The documentation is a docpages site itself, in docs/:

example/cli and example/library are complete docs folders, each in a style of its own.

Development

make gen writes the Go code of the templ templates, static/style.min.css, static/docs.min.js and the Morpheus bundle. They are committed, and CI fails when they are out of date. make fmt formats the code with gofumpt, which CI checks too.

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

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.

func Contents

func Contents(p Page) templ.Component

Contents lists sections beside the text on wide screens; it renders nothing when there are none.

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

Head renders a page's <head>: title, description, 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.

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 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, narrow-screen contents, 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 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.js lists search.json results, or suggestions for an empty field.

func Snapshot

func Snapshot(o Options, tag string) (string, error)

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

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.js opens the page in the chosen version.

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
}

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.
	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
	// 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 in the versions directory.

func Read

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

Read reads the documentation of o.Dir in o.Root and converts it.

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

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