staticman

package module
v0.0.0-...-9fbefe9 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 58 Imported by: 0

README

Static Site generator for SourceHut wikis

This is a basic tool for generating an HTML bundle compatible with static site hosting based on the repositories used by man.sr.ht compatible wikis.

Current features:
  • Convert the original markdown to HTML using the CommonMark specification.
  • Additional custom elements:
    • Checkboxes (using the [ ] and [x] syntax)
    • Footnotes (using the [^ref] and [^ref]: description syntax)
  • Convert inline images to web optimized versions and use progressive loading.
  • Frontmatter header parsing compatible with SourceHut.
  • Additional custom frontmatter headers support for:
    • logo representing a URL to an image.
    • tags a string list of keywords that will be found by the search function.
    • styles a string list of additional CSS files that will be included.
    • scripts a string list of additional JS files that will be included.
    • next a path to a markdown document that should be considered the next page.
    • prev a path to a markdown document that should be considered the previous page.
  • Native dark and light themes.
  • Code syntax highlighting without needing JavaScript.
  • Good support for TUI browsers.
  • Basic information about the git repository of the wiki.
  • Use .gitignore to skip processing files or directories.
  • Repository license information.
  • Create table of contents for the wiki based on file structure and HTML headings.
  • Create breadcrumbs for the file structure of any particular page.
  • Create a site-config file compatible with SourceHut pages.
  • Search for the documentation (requires JavaScript, but is invisible if that's not enabled).
  • Theming and custom JavaScript based on the styles and scripts frontmatter elements.

Screenshot of this README being rendered by staticman

Planed features
  • Improve the search function to be more robust and have better UI.
  • Build a proper dependency resolution for the NPM downloader.

If you're able to help with any of these, please feel free to reach out to my public inbox. For some other minor issues and wanted featurs see the todo file.

Usage

Building

The main use for the tool is to build the markdown wiki document into a directory target with the static HTML and associated resources.

$ staticman build --path ./example-wiki --target ./example-wiki-output
$ tar -C ./example-wiki-output -cvz . > example-wiki.tar.gz
$ hut pages publish --site-config ./example-wiki/site-config.json \
 --domain username.srht.site example-wiki.tar.gz

More details about using hut are on its sourcehut pages documentation.

An example of a static site built using the tool can be found for the GoActivityPub projects wiki.

Serving locally

The tool also supports serving the generated bundle locally for debugging purposes.

The bundle is regenerated every time the files in the wiki are modified, so it can be used in real time.

The browser gets notified after every build, so refreshing can be done more easily.

$ staticman serve --path ./example-wiki
2025-11-29 10:20:39 INF Build done. duration=1.232428439s
2025-11-29 10:20:39 INF Started server. Ctrl+C to interrupt. address=http://127.0.0.1:47429
2025-11-29 10:23:09 INF file was modified, rebuilding. path=/path/to/example-wiki/index.md
2025-11-29 10:23:11 INF Build done. duration=1.28132844s
Uploading directly to SourceHut pages

The tool supports direct upload to SourceHut pages if an existing hut configuration is available.

$ staticman upload --path ./example-wiki --domain example-wiki.srht.site
2025-11-29 12:29:46 INF Build done. duration=1.259232512s
2025-11-29 12:29:47 INF Unpublished site site=https://example-wiki.srht.site instance=sr.ht
2025-11-29 12:29:50 INF Published site site=https://example-wiki.srht.site instance=sr.ht

Currently, this doesn't work directly from a pipeline in SourceHut builds. If anyone has an idea or a patch for that, get in touch.

Themes

We have some barebones support for themes by allowing every documentation page to declare a list of CSS and JS files to be included in the resulting HTML file.

Custom Stylesheets

Adding CSS files is simple: they need to be present in the documentation tree, and then referenced with the correct path in the styles frontmatter array.

Currently, they cascade from an root page to all pages in the same subtree, including the ones in subdirectories started from the same parent directory.

This means that you can use different styles for different parts of your documentation.

Custom JavaScript

We allow for custom JavaScript to be included using the same method as above, using the scripts frontmatter array, and additionly we support declaring dependencies for them using the idiomatic package.json file placed in the documentation root directory.

The builder will download the dependencies from NPM and bundle them in the script files you declared, without needing third party dependencies like yarn or npm.

However, this custom npm fetcher does not support yet building a full dependency tree as it should, so its use is limited to libraries that don't have external dependencies themselves.

We'll try to improve on this, but there's no timeline for it at the moment. If you have ideas about the feature, get in touch.

Documentation

Index

Constants

View Source
const LevelTrace = slog.Level(-12)

Variables

View Source
var (
	AppVersion = "(devel)"
	AppName    = "SourceHut Wiki"
	AppRepoURL = "https://git.sr.ht/~mariusor/staticman"

	AppBinary = "staticman"
)
View Source
var (
	DefaultSiteConfig = pages.SiteConfig{
		NotFound: &defaultNotFound,
		FileConfigs: []pages.FileConfig{
			{
				Glob: "*.png",
				Options: pages.FileOptions{
					CacheControl: &defaultStaticMaxAgeValue,
				},
			},
			{
				Glob: "*.jpg",
				Options: pages.FileOptions{
					CacheControl: &defaultStaticMaxAgeValue,
				},
			},
			{
				Glob: "*.avif",
				Options: pages.FileOptions{
					CacheControl: &defaultStaticMaxAgeValue,
				},
			},
			{
				Glob: "*.js",
				Options: pages.FileOptions{
					CacheControl: &defaultStaticMaxAgeValue,
				},
			},
			{
				Glob: "*.json",
				Options: pages.FileOptions{
					CacheControl: &defaultStaticMaxAgeValue,
				},
			},
			{
				Glob: "*.svg",
				Options: pages.FileOptions{
					CacheControl: &defaultStaticMaxAgeValue,
				},
			},
			{
				Glob: "*.css",
				Options: pages.FileOptions{
					CacheControl: &defaultStaticMaxAgeValue,
				},
			},
			{
				Glob: "*.html",
				Options: pages.FileOptions{
					CacheControl: &defaultHTMLMaxAgeValue,
				},
			},
			{
				Glob: "*.ico",
				Options: pages.FileOptions{
					CacheControl: &defaultHTMLMaxAgeValue,
				},
			},
			{
				Glob: ".status",
				Options: pages.FileOptions{
					CacheControl: &noCache,
				},
			},
		},
	}
)

Functions

func IgnorePath

func IgnorePath(ignore []gitignore.Pattern, path string, isDir bool) bool

func RuleFileTransclude

func RuleFileTransclude(f fs.FS) markdown.InlineRule

RuleFileTransclude parses the lines for transclude atoms These have the format !(./path/to/filename.md)

func RuleFootnotes

func RuleFootnotes(s *markdown.StateCore)

RuleFootnotes recognizes Markdown type footnotes with the following logic: [^1] -> <a href="#fn-foot-1" id="fn-inline-1"><sup>1</sup></a> [^1]: description -> <dt id="fn-foot-1">1</dt><dd>description<a href="#fn-inline-1">(back)</a></dd>

func RuleInlineCheckbox

func RuleInlineCheckbox(s *markdown.StateInline, silent bool) bool

RuleInlineCheckbox converts Markdown type checkboxes into HTML ones [ ] -> <input type="checkbox" /> [-] -> <input type="checkbox" checked disabled class="indeterminate"/> [.] -> <input type="checkbox" disabled /> [x] -> <input type="checkbox" checked />

func XDGCachePath

func XDGCachePath(appName string) string

func XDGDataPaths

func XDGDataPaths(appName string) string

Types

type Capsule

type Capsule struct {
	Cache     *os.Root
	Root      *os.Root
	Tree      FlatTree
	BuildTime time.Time
}

func InitCapsule

func InitCapsule(conf Config) (*Capsule, error)

func (*Capsule) Build

func (c *Capsule) Build(ctx context.Context, target Targeter, conf Config) error

func (*Capsule) Close

func (c *Capsule) Close() error

func (*Capsule) State

func (c *Capsule) State(l *slog.Logger, target Targeter, conf Config) ssm.Fn

func (*Capsule) WatcherEventFn

func (c *Capsule) WatcherEventFn(ctx context.Context, buildFn func(...string) error) watch.EventFn

type Config

type Config struct {
	Source          string
	Target          string
	Optimize        bool
	BundleRefreshJS bool
	ChangedPaths    []string
}

type FlatTree

type FlatTree []*Node

func (*FlatTree) Find

func (t *FlatTree) Find(path string) *Node
func (t *FlatTree) FindByLink(path string) *Node

func (*FlatTree) Set

func (t *FlatTree) Set(path string, nn *Node)

type Img

type Img struct {
	OriginalPath string
	Original     *Node
	OriginalSize image.Point
	Small        *Node
	SmallSize    image.Point
	Medium       *Node
	MediumSize   image.Point
	Large        *Node
	LargeSize    image.Point
}
type Link struct {
	Href  string
	Title string
}

type Metadata

type Metadata struct {
	Title   string   `yaml:"title"`
	Tags    []string `yaml:"tags"`
	Next    string   `yaml:"next"`
	Prev    string   `yaml:"prev"`
	Styles  []string `yaml:"styles"`
	Scripts []string `yaml:"scripts"`
}

type Node

type Node struct {
	Path       string
	TargetPath string
	Content    *bytes.Buffer
	Sentences  []string

	Toc   TocHeading
	InUse bool

	Next Link
	Prev Link

	Metadata   *Metadata
	LastCommit *object.Commit
}
func (n Node) Link() string

type Targeter

type Targeter interface {
	Name() string
}

func Target

func Target(conf Config) (Targeter, error)

type Toc

type Toc []*TocHeading

func (*Toc) Add

func (t *Toc) Add(el TocHeading)

func (*Toc) Contains

func (t *Toc) Contains(el TocHeading) bool
func (t *Toc) ForLink(link string) *TocHeading

func (*Toc) Titles

func (t *Toc) Titles() []string

type TocHeading

type TocHeading struct {
	Link
	Next  string
	Prev  string
	Level int

	Crumbs   Toc
	Tags     []string
	Headings Toc
	// contains filtered or unexported fields
}

func (*TocHeading) Add

func (t *TocHeading) Add(toc TocHeading)

Directories

Path Synopsis
cmd
staticman command
internal
hut
npm

Jump to

Keyboard shortcuts

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