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/v2@v2.3.1
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
- 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
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
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
convert
Transform various data strings to other data strings
|
Transform various data strings to other data strings |
|
frontmatter
Package frontmatter adds support for parsing front matter in Markdown documents.
|
Package frontmatter adds support for parsing front matter in Markdown documents. |
|
render
Render html according to html templates
|
Render html according to html templates |
|
source
Handle markdown source and helper methods
|
Handle markdown source and helper methods |
|
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. |