From 4b6b19fdfad5af8d91cee5b34710f64dea6756c8 Mon Sep 17 00:00:00 2001 From: Adam Mathes Date: Sun, 18 Feb 2018 14:20:34 -0800 Subject: update docs. generate html readme. --- README.md | 216 ++++++++++++++----------- readme.html | 511 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 635 insertions(+), 92 deletions(-) create mode 100644 readme.html diff --git a/README.md b/README.md index a791947..39ed1a0 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,80 @@ -# snkt - -`snkt` is a static web site generator focused on simplicity and efficiency. +
+                     ██                 
+                     ██          ██     
+                     ██          ██     
+  ▒█████░  ██░████   ██  ▓██▒  ███████  
+ ████████  ███████▓  ██ ▓██▒   ███████  
+ ██▒  ░▒█  ███  ▒██  ██▒██▒      ██     
+ █████▓░   ██    ██  ████▓       ██     
+ ░██████▒  ██    ██  █████       ██     
+    ░▒▓██  ██    ██  ██░███      ██     
+ █▒░  ▒██  ██    ██  ██  ██▒     ██░    
+ ████████  ██    ██  ██  ▒██     █████  
+ ░▓████▓   ██    ██  ██   ███    ░████  
+                                        
+
+              v.01 manual
+               2/18/2018
+
+
-snkt only does a few things, but strives to do them well, in a coherent manner. +# snkt -snkt generates my [personal web site of ~2000 articles in under a second](https://trenchant.org/daily/2017/1/31/). Additional work may be done to increase efficiency, but it should be fast enough to regularly regenerate your site without concern in near real-time if needed. +`snkt` is a static site generator focused on simplicity and efficiency. -## What +`snkt` does a few things, but strives to do them coherently. -Takes a bunch of plain text files, processes them via templates, and generates HTML. Pretty much like you'd expect of a static site generator. +`snkt` generates my [personal web site of ~2000 articles in under a second](https://trenchant.org/daily/2017/1/31/). It should be fast enough to completely regenerate even very large sites in near real-time if needed. ## Why Every 5-10 years I throw out the software for my site and rewrite it. -This time it's in Go. Maybe you'll find it useful. - -I found it fun to get myself thinking in Go. Also, it's 10x faster than the old version in Python. +This time it's in Go. Maybe you'll find it useful. It's 10x faster than the old version in Python. ## Status It powers [trenchant.org](https://trenchant.org) but is under active development and pieces may change. See TODO for future / in progress work. -## Getting snkt - -[Install Go](https://golang.org/doc/install) - -Set up $GOPATH - - $ mkdir $HOME/go - $ export GOPATH=$HOME/go - -See also: [The GOPATH environment variable](https://golang.org/doc/code.html#GOPATH) +# Installation -Add $GOPATH/bin to your PATH +The only dependency for building is `go`. - $ export PATH=$PATH:$GOPATH/bin +[Install Go](https://golang.org/doc/install) for your platform. -Download and build `snkt` +Download and build `snkt` with something like $ go get adammathes.com/snkt -This should download depdendencies, build `snkt` and place it in $GOPATH/bin +This will download dependencies, build `snkt` and place it in your $GOPATH/bin (by default, ~/go/bin/). -`snkt` should now be a self-contained binary, you can move it if needed. +`snkt` is a self-contained binary, you can move it anywhere. -## Setting up a site +# Quick Start + +## Creating a Site Use the "-init" option to create the skeleton for a new site - - $ snkt -init blogadu + $ snkt -i myblog This will create: - * `txt` directory for plain text input + * `txt` directory for posts * `html` directory for HTML output * `tmpl` directory for templates - * `base` basic HTML structure for all pages - * `post` single post page template - * `home` - home page with recent posts template - * `archive` - list all posts template - * `rss` - template for an RSS 2.0 archive - * `config.yml` -- configuration file - + * `base` HTML structure wrapper + * `archive` lists all posts + * `post` single post page + * `home` home page with recent posts + * `rss` RSS 2.0 + * `config.yml` configuration file ## First Post A one line plaint text file is a valid post. - user@host:~/blogadu$ echo "hello world" >> txt/hi + user@host:~/myblog$ echo "hello world" >> txt/hi Build the site @@ -82,31 +88,44 @@ Output should now be in the `html` directory and look like * `archive.html` * `rss.xml` -Run a preview server to see the results with +## Viewing the Results + +`snkt` includes a simple web server to view the results with $ snkt -p -Loading http://localhost:8000 in a web browser should now show the (near empty) site. +Visiting http://localhost:8000 in a web browser should now show the site and the first post. + +You can now copy this HTML anywhere and you're set. -## Command Line Usage +# Command Line Options ``` Usage of snkt: - -b build site - -c configuration + -b, --build + generates site from input files and templates + -c, --config configuration configuration file (default "config.yml") - -h help - -init directory + -h, --help + print usage information + -i, --init directory initialize new site at directory - -p preview site with local HTTP server - -v print version number - -verbose - log actions during build + -s, --serve + serve site via integrated HTTP server + -v, --verbose + log operations during build to STDOUT + -w, --watch + watch configured input text dir, rebuild on changes ``` -## Configuration File +Examples -The configuration is in [YAML](http://yaml.org) + $ snkt -c site.yaml -b + $ snkt --config=myconfig.yml -v -w + +# Configuration + +Per site configuration is via a [YAML](http://yaml.org) file. For most purposes, it should just be a listing of attribute : value @@ -117,8 +136,8 @@ Configuration options -- | `input_dir` | absolute path of directory for text input files | | | `output_dir` | absolute path of directory for html output files | | | `tmpl_dir` | absolute path of directory for template files | | -| `site_title` | string for the site's title (used in templates) | | -| `site_url` | absolute URL for the site (used in templates) | | +| `site_title` | string for the site's title | | +| `site_url` | absolute URL for the site | | | `filters` | list of search/replace regex's to run on posts | | | `permalink_fmt` | format string for permalinks | /%F/ | | `post_file_fmt` | format string for post filenames | /%F/index.html | @@ -126,7 +145,7 @@ Configuration options -- | `preview_server` | host:port to spawn the preview server | localhost:8000 | | `preview_dir` | root directory of preview server | `output_dir` | -## Posts +# Posts Post inputs are stored as plain text files. (I have only tested UTF-8 and ASCII.) @@ -151,27 +170,29 @@ Post with a preamble -- `totes` will be stored in the post's `meta` map under `valid.` You don't have to worry about that right now. Honest. -## Templates +# Templates Templates use the standard library [Go text/template](https://golang.org/pkg/text/template/). -### Types +Entities in the templates -- -#### Site (see site/site.go) -```go +**Site** +``` Title string URL string - Posts post.Posts + Posts array of posts ``` -#### Post (see post/post.go) +See site/site.go for more. + +**Post** -```go +``` // Metadata Meta map[string]string SourceFile string - Title string `json:"title"` - Permalink string `json:"permalink"` + Title string + Permalink string Time time.Time Year int Month time.Month @@ -195,51 +216,42 @@ Templates use the standard library [Go text/template](https://golang.org/pkg/tex // Precomputed dates as strings Date string RssDate string - - FileInfo os.FileInfo - - Site sitemeta ``` -### home +## home -Displays recent posts. Rendered to `index.html`. +Displays recent posts and rendered to `index.html` in the `output_dir`. - {{.Site}} *Site* -- {{.Posts}} *Posts* all posts on site, reverse chronological order +- {{.Posts}} *Posts* all posts on site in reverse chronological order -### post +## post -Template that gets rendered to create individual post pages +Each individual post uses this template - {{.Site}} *Site* -- {{.Post}} *Post* the individual post the page is for +- {{.Post}} *Post* the individual post -### archive +## archive Lists all posts, showing only titles and links. Rendered to `archive.html` - {{.Site}} *Site* - {{.Posts}} *Posts* all posts, reverse chronological order -### rss +## rss Displays recent posts as RSS 2.0 XML. Rendered to `rss.xml` - {{.Site}} *Site* - {{.Posts}} *Posts* all posts, reverse chronological order -## Advanced Features - -### paged template -If present renders paged archives (15 posts per page) to `page/%d.html` +# Advanced Configuration Options -See archive/paged.go for details. Used to create an "infinite scroll" style archive. Details/options/implementation may change. +## Permalink and filename formatter -### Permalink and filename formatter - -Permalink (URLs for individual posts) can be customized. This part is *meh* and subject to change. +Permalinks (URLs for individual posts) can be customized. | String | Value | Example | |--------|----------|---------| @@ -251,7 +263,8 @@ Permalink (URLs for individual posts) can be customized. This part is *meh* and `Filename` is a cleaned version of the post's original filename with the extension removed. Filenames and titles will be "cleaned" of characters unsuitable for links, with whitespace replaced by `-`. -### Filters + +## Filters Arbitrary regular expressions can be executed on each post to create domain-specific and site-specific modifications. @@ -269,7 +282,19 @@ filters: r: "http://www.amazon.com/exec/obidos/ASIN/$1/decommodify-20/" ``` -### Tags +# Work in Progress Features + +These features are working but less documented and potentially still in progress and subject to change. + +## Paged Archives + +If a template named `paged` is present then paged archives (15 posts per page) are created at `output_dir/page/%d.html` + +Template variables are the same as the `archive` template, but with `.NextPage` and `.PrevPage` as integers of the next and previous page. + +See archive/paged.go for details. + +## Tags There is preliminary support for tag style metadata per post. @@ -284,11 +309,15 @@ Tags will be normalized to lowercase, with spaces replaced with underscores. So `tagone tag_two a_third_tag fourth` -Tags are accessible in each post struct via the `Tags` field. +Tags are accessible in each post via the `Tags` field. -To create archives of tags, create a template named `tags` -- it will behave the same as an `archive` template, but create a file at HTML_DIR/tag/tag_name/index.html for each unique tag. +To create pages by tag, create a template named `tags`. -### Binary Files as Posts +This creates a file at OUTPUT_DIR/tag/tag_name/index.html for each tag. + +It will have access to the same variables as an `archive` template with the additional `.Tag` for the tag name. + +## Binary Files as Posts Preliminary support to treat binary files as standalone posts. @@ -296,20 +325,23 @@ Drop image files with "jpg" or other image extensions into the "txt" dir. * post's ContentType will be set to "image" * text fields will be empty strings -* metadata will be populated as it can via exif (sorta) +* metadata will be populated as it can via exif (maybe) -Video and audio files have preliminary support too -- see post.go +Video and audio files have preliminary support too -- see `post/post.go` -### Example configurations/sites/themes +# Example configurations, sites, themes *not done* -### Auto-rebuild/deployment +# Rebuild and deployment recipes *also not done* -## TODO +# TODO - * complete and document media support (image/mp3/video/binary file posts) * sample sites/templates * proper man pages for docs + +# Feedback + +Pull requests and issues are welcomed at https://github.com/adammathes/snkt diff --git a/readme.html b/readme.html new file mode 100644 index 0000000..11a3c7d --- /dev/null +++ b/readme.html @@ -0,0 +1,511 @@ + + +
+                     ██                 
+                     ██          ██     
+                     ██          ██     
+  ▒█████░  ██░████   ██  ▓██▒  ███████  
+ ████████  ███████▓  ██ ▓██▒   ███████  
+ ██▒  ░▒█  ███  ▒██  ██▒██▒      ██     
+ █████▓░   ██    ██  ████▓       ██     
+ ░██████▒  ██    ██  █████       ██     
+    ░▒▓██  ██    ██  ██░███      ██     
+ █▒░  ▒██  ██    ██  ██  ██▒     ██░    
+ ████████  ██    ██  ██  ▒██     █████  
+ ░▓████▓   ██    ██  ██   ███    ░████  
+                                        
+
+              v.01 manual
+               2/18/2018
+
+
+ +

snkt

+ +

snkt is a static site generator focused on simplicity and efficiency.

+ +

snkt does a few things, but strives to do them coherently.

+ +

snkt generates my personal web site of ~2000 articles in under a second. It should be fast enough to completely regenerate even very large sites in near real-time if needed.

+ +

Why

+ +

Every 5-10 years I throw out the software for my site and rewrite it.

+ +

This time it’s in Go. Maybe you’ll find it useful. It’s 10x faster than the old version in Python.

+ +

Status

+ +

It powers trenchant.org but is under active development and pieces may change. See TODO for future / in progress work.

+ +

Installation

+ +

The only dependency for building is go.

+ +

Install Go for your platform.

+ +

Download and build snkt with something like

+ +
$ go get adammathes.com/snkt
+
+ +

This will download dependencies, build snkt and place it in your $GOPATH/bin (by default, ~/go/bin/).

+ +

snkt is a self-contained binary, you can move it anywhere.

+ +

Quick Start

+ +

Creating a Site

+ +

Use the “-init” option to create the skeleton for a new site -

+ +
$ snkt -i myblog
+
+ +

This will create:

+ + + +

First Post

+ +

A one line plaint text file is a valid post.

+ +
user@host:~/myblog$ echo "hello world" >> txt/hi
+
+ +

Build the site

+ +
$ snkt -b
+
+ +

Output should now be in the html directory and look like

+ + + +

Viewing the Results

+ +

snkt includes a simple web server to view the results with

+ +
$ snkt -p
+
+ +

Visiting http://localhost:8000 in a web browser should now show the site and the first post.

+ +

You can now copy this HTML anywhere and you’re set.

+ +

Command Line Options

+ +
Usage of snkt:
+  -b, --build
+    	generates site from input files and templates
+  -c, --config configuration
+    	configuration file (default "config.yml")
+  -h, --help
+    	print usage information
+  -i, --init directory
+    	initialize new site at directory
+  -s, --serve
+    	serve site via integrated HTTP server
+  -v, --verbose
+    	log operations during build to STDOUT
+  -w, --watch
+    	watch configured input text dir, rebuild on changes
+
+ +

Examples

+ +
$ snkt -c site.yaml -b
+$ snkt --config=myconfig.yml -v -w
+
+ +

Configuration

+ +

Per site configuration is via a YAML file.

+ +

For most purposes, it should just be a listing of attribute : value

+ +

Configuration options --

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namevaluedefault
input_dirabsolute path of directory for text input files
output_dirabsolute path of directory for html output files
tmpl_dirabsolute path of directory for template files
site_titlestring for the site’s title
site_urlabsolute URL for the site
filterslist of search/replace regex’s to run on posts
permalink_fmtformat string for permalinks/%F/
post_file_fmtformat string for post filenames/%F/index.html
show_futureinclude posts with dates in the futurefalse
preview_serverhost:port to spawn the preview serverlocalhost:8000
preview_dirroot directory of preview serveroutput_dir
+ +

Posts

+ +

Post inputs are stored as plain text files. (I have only tested UTF-8 and ASCII.)

+ +

Posts have an optional metadata preamble, and a markdown formatted body. The preamble is just a series of name value pairings separated by a colon (:) character.

+ +

Minimal complete and valid post --

+ +
this is a totally valid post
+
+ +

Post with a preamble --

+ +
title: also a valid post
+date: 2017-02-08
+valid: totes
+
+This post will have an explicitly set title (ooh! fancy!) 
+instead of inferred from the filename. 
+
+It will also have an explicitly set date instead of inferring 
+it from the file creation/modification time.
+
+`totes` will be stored in the post's `meta` map under `valid.` 
+You don't have to worry about that right now. Honest.
+
+ +

Templates

+ +

Templates use the standard library Go text/template.

+ +

Entities in the templates --

+ +

Site

+ +
	Title string
+	URL   string
+	Posts array of posts
+
+ +

See site/site.go for more.

+ +

Post

+ +
	// Metadata
+	Meta       map[string]string
+	SourceFile string
+	Title      string 
+	Permalink  string
+	Time       time.Time
+	Year       int
+	Month      time.Month
+	Day        int
+	InFuture   bool
+
+	// Content text -- raw, unprocessed, unfiltered markdown
+	Text string
+
+	// Content text -- processed into HTML via markdown and other filters
+	Content string
+
+	// Content with sources and references resolved to absolute URLs
+	AbsoluteContent string
+
+	// Post following chronologically (later)
+	Next *Post
+	// Post preceding chronologically (earlier)
+	Prev *Post
+
+	// Precomputed dates as strings
+	Date    string
+	RssDate string
+
+ +

home

+ +

Displays recent posts and rendered to index.html in the output_dir.

+ + + +

post

+ +

Each individual post uses this template

+ + + +

archive

+ +

Lists all posts, showing only titles and links. Rendered to archive.html

+ + + +

rss

+ +

Displays recent posts as RSS 2.0 XML. Rendered to rss.xml

+ + + +

Advanced Configuration Options

+ +

Permalink and filename formatter

+ +

Permalinks (URLs for individual posts) can be customized.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StringValueExample
%YYear2017
%MMonth04
%DDay14
%FFilenamefoo
%TTitlebar
+ +

Filename is a cleaned version of the post’s original filename with the extension removed. Filenames and titles will be “cleaned” of characters unsuitable for links, with whitespace replaced by -.

+ +

Filters

+ +

Arbitrary regular expressions can be executed on each post to create domain-specific and site-specific modifications.

+ +

Here are the real world examples of regular expressions that filter each post on my personal site -

+ +
filters:
+  - s: <photo id="(.+)">
+    r: <div class="photo"><img src="/img/$1" /></div>
+  - s: <segue />
+    r: <p class="segue">&middot; &middot; &middot;</p>
+  - s: <youtube id="(.+)">
+    r: <p class="video"><a href="https://www.youtube.com/watch?v=$1"><img src="/img/$1.jpg" /></a></p>
+  - s: "amazon:(.+)"
+    r: "http://www.amazon.com/exec/obidos/ASIN/$1/decommodify-20/"
+
+ +

Work in Progress Features

+ +

These features are working but less documented and potentially still in progress and subject to change.

+ +

Paged Archives

+ +

If a template named paged is present then paged archives (15 posts per page) are created at output_dir/page/%d.html

+ +

Template variables are the same as the archive template, but with .NextPage and .PrevPage as integers of the next and previous page.

+ +

See archive/paged.go for details.

+ +

Tags

+ +

There is preliminary support for tag style metadata per post.

+ +

Add a “tags” field to your post preamble. Tags should be comma separated.

+ +
    tags: TagOne, tag two, a third tag, fourth
+
+
+ +

Tags will be normalized to lowercase, with spaces replaced with underscores. So the above would have tagged a post with --

+ +

tagone tag_two a_third_tag fourth

+ +

Tags are accessible in each post via the Tags field.

+ +

To create pages by tag, create a template named tags.

+ +

This creates a file at OUTPUT_DIR/tag/tag_name/index.html for each tag.

+ +

It will have access to the same variables as an archive template with the additional .Tag for the tag name.

+ +

Binary Files as Posts

+ +

Preliminary support to treat binary files as standalone posts.

+ +

Drop image files with “jpg” or other image extensions into the “txt” dir.

+ + + +

Video and audio files have preliminary support too -- see post/post.go

+ +

Example configurations, sites, themes

+ +

not done

+ +

Rebuild and deployment recipes

+ +

also not done

+ +

TODO

+ + + +

Feedback

+ +

Pull requests and issues are welcomed at https://github.com/adammathes/snkt

-- cgit v1.2.3