pher

command module

v3.0.1 Latest Latest Go to latest Published: Dec 29, 2025 License: GPL-3.0 Imports: 9 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/mstcl/pher

Links

Open Source Insights

README ¶

pher

A wiki-style static site generator

Written in go, inspired by ter.

Features

pher aims to match ter's goals and features, but there are a few differences:

Comes with markdown extensions like footnotes and smartypants.
Wikilinks are supported thanks to abhinav's extension.
No CSS framework.
Comes as a small standalone binary (~9M). No need for a runtime.
Some visual tweaks (personal preference).
The atom feed contains only dated entries.
Flatter file structure (no "rooting" every page). Let webservers handle the routing and beautifying.

Installation

$ go install github.com/mstcl/pher/v3@v3.0.0

Usage

Usage of pher:
  -c string
        Path to config file (default "config.yaml")
  -d    Dry run---don't render (default false)
  -i string
        Input directory (default ".")
  -o string
        Output directory (default "_site")

Configuration

# atom feed options
title: "" # wiki title
description: "" # wiki description
url: "" # external link to the wiki (https://...)
authorName: "" # author's name
authorEmail: "" # author's email

# rendering options
rootCrumb: "~" # render root link in navbar with this string.
codeHighlight: true # render code with syntax highlighting.
codeTheme: "trac" # chroma style (https://xyproto.github.io/splash/docs/all.html)
keepExtension: true # render hrefs with .html extension
head: "" # String to inject inside HTML <head>
path: "/" # the subpath of your wiki (e.g. if hosted at example.org/wiki then it's /wiki)

# footer links, leave empty e.g. `footer: []` to disable
footer:
  - text: "license"
    href: "https://link.to.license"
  - text: "feed"
    href: "/feed.xml"

Frontmatter

pher reads in frontmatter in YAML format. Available fields and default values are:

---
title: "" # Entry's title
description: "" # Entry's description
tags: [] # Entry's list of tags
date: "" # Entry's date YYYY-MM-DD format
pinned: false # Pin entry at the top of the listing
unlisted: false # Remove entry from the listing
draft: false # Don't render this entry
toc: false # Render a table of contents for this entry
showHeader: true # Show the header (title, description, tags, date)
layout: "list" # Available values: "grid", "list", "log". Only effective for index.md files.
---

To do

Implement navigation breadcrumbs
Listing (lists/grid)
Listing (log)
Default listing if there is none
Copy linked assets over
Fix TOC
Implement logic
- hiding TOC
- pinning entries
- unlisting entries
Tags page
Related links (by tags)
Atom feed
Configuration to inject into HTML
Frontmatter field for dateUpdated
SEO fields

Ideas

Git diff mode that renders only changes/untracked files
Compress images to webp or mozilla jpeg

Notes

Editing templates

pher embeds the templates in web/templates with go:embed. This means pher can run as a standalone binary. Unfortunately, to modify the templates, we have to recompile.

Removing html extension

To strip extension using webservers, we might have to make the following adjustments:

location / {
  if ( $request_uri ~ "/index.html" ) {
    rewrite ^(.*)/ $1/ permanent;
  }
  try_files $uri $uri/ =404;
}

Additionally, setting keepExtension: false will strip ".html" from href links. This might be necessary if you use weird browsers that break redirects.

Credits

ter - main inspiration
go-vite - aesthetic
goldmark - markdown parser
renee french - gopher

Documentation ¶

Overview ¶

pher is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

pher is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with pher. If not, see <http://www.gnu.org/licenses/>.

Source Files ¶

View all Source files

main.go

Directories ¶

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

Path	Synopsis
internal
assetpath Package assetpath defines the assetpath type	Package assetpath defines the assetpath type
cli Package cli is pher's entrypoint	Package cli is pher's entrypoint
config Package config defines configuration (read from file) and defaults	Package config defines configuration (read from file) and defaults
convert Package convert defines helpers to transform various data strings to other data strings	Package convert defines helpers to transform various data strings to other data strings
customanchor Package customanchor defines a custom header anchor for goldmark/anchor	Package customanchor defines a custom header anchor for goldmark/anchor
feed Package feed handles RSS feed generation	Package feed handles RSS feed generation
frontmatter Package frontmatter adds support for parsing front matter in Markdown documents.	Package frontmatter adds support for parsing front matter in Markdown documents.
metadata Package metadata defines available fields for the frontmatter	Package metadata defines available fields for the frontmatter
node Package node defines the Node struct	Package node defines the Node struct
nodegroup Package nodegroup defines the Nodegroup struct	Package nodegroup defines the Nodegroup struct
nodepath Package nodepath defines the NodeProup struct	Package nodepath defines the NodeProup struct
nodepathlink Package nodepathlink defines the nodepathlink struct	Package nodepathlink defines the nodepathlink struct
render Package render renders html according to html templates	Package render renders html according to html templates
source Package source handles markdown source and helper methods	Package source handles markdown source and helper methods
state Package state defines the asbstracted state struct	Package state defines the asbstracted state struct
tag Package tag defines the Tag struct	Package tag defines the Tag struct
toc Package toc provides support for building a Table of Contents from a goldmark Markdown document.	Package toc provides support for building a Table of Contents from a goldmark Markdown document.
wikilink Package wikilink provides support for parsing [[...]]-style and ![[...]]-style wiki links to the goldmark Markdown parser.	Package wikilink provides support for parsing [[...]]-style and ![[...]]-style wiki links to the goldmark Markdown parser.