staticman

package module
v0.0.0-...-5e476a9 Latest Latest
Warning

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

 Go to latest Published: Feb 5, 2026 License: MIT Imports: 42 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.
  • Frontmatter header parsing compatible with SourceHut.
  • Logo support in the frontmatter header.
  • Dark and light theme support.
  • Support code syntax highlighting.
  • Create web optimized versions for images and use progressive loading.
  • Basic information about the git repository of the wiki.
  • Create table of contents for the wiki based on file structure and HTML headings.
  • Search for the documentation (requires JavaScript, but is invisible if that's not enabled).

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.

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

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	AppVersion = "(devel)"
	AppName    = "SourceHut Wiki"
	AppRepoURL = "https://git.sr.ht/~mariusor/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: "*.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,
				},
			},
		},
	}
)

Functions

func RuleConvertLinksToHTML 

func RuleConvertLinksToHTML(originalExt string) markdown.PostprocessRule

func RuleFileTransclude 

func RuleFileTransclude(f fs.FS, basePath string) markdown.InlineRule

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

func RuleStripLinkPrefix 

func RuleStripLinkPrefix(prefix string) markdown.PostprocessRule

Types

type Capsule 

type Capsule struct {
	// Toc contains the structure of the current site:
	// link -> { title, link, Headings {title, link} }
	Toc    Toc
	Repo   *git.Repository
	Root   *os.Root
	Target *os.Root

	Images   []Img
	Licenses []string
	Tree     FlatTree
	Indexes  []indexDocument
	Ignore   []gitignore.Pattern
	// contains filtered or unexported fields
}

func InitCapsule 

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

func (*Capsule) Build 

func (c *Capsule) Build(prod bool) error

func (*Capsule) Close 

func (c *Capsule) Close() error

func (*Capsule) IgnorePath 

func (c *Capsule) IgnorePath(path string, isDir bool) bool
func (c *Capsule) RuleAddHeadingLinks(s *markdown.StateBlock, _ int, _ int, _ bool) bool

func (*Capsule) RuleExtractTitle 

func (c *Capsule) RuleExtractTitle(s *markdown.StateBlock, _, _ int, _ bool) bool

func (*Capsule) RuleFancyImages 

func (c *Capsule) RuleFancyImages(s *markdown.StateInline)

func (*Capsule) RuleSyntaxHighlightPre 

func (c *Capsule) RuleSyntaxHighlightPre(s *markdown.StateBlock, _ int, _ int, _ bool) bool

type Config 

type Config struct {
	Source string
	Target string
	Prod   bool
}

type FlatTree 

type FlatTree []*Node

func (FlatTree) Find 

func (t FlatTree) Find(path string) *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
}

func (*Img) GenerateWebFormats 

func (i *Img) GenerateWebFormats(root, target *os.Root, createSmaller bool) error
type Link struct {
	Rel   string
	Href  string
	Media string
}

type Metadata 

type Metadata struct {
	Title string   `yaml:"title"`
	Toc   bool     `yaml:"toc"`
	Tags  []string `yaml:"tags"`
}

type Node 

type Node struct {
	IsLicense bool
	Path      string
	Link      string
	Styles    []string
	Metadata  *Metadata
	Original  io.Reader
	Target    io.Reader
}

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) SetCurrent 

func (t *Toc) SetCurrent(link string)

type TocHeading 

type TocHeading struct {
	Title string
	Open  bool
	Link  string
	Level int

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

func (*TocHeading) Add 

func (t *TocHeading) Add(toc TocHeading)

func (*TocHeading) Type 

func (t *TocHeading) Type() template.HTMLAttr

Source Files

View all Source files

Directories

Path Synopsis
cmd
staticman command
internal
hut

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.