From 0f005aa1013e14e8e054535fc4e81b4f1b319785 Mon Sep 17 00:00:00 2001 From: Adam Mathes Date: Sun, 18 Feb 2018 14:56:39 -0800 Subject: futzing with the readmes --- readme.html | 255 +++++++++++++++++++++++++++++++----------------------------- 1 file changed, 130 insertions(+), 125 deletions(-) (limited to 'readme.html') diff --git a/readme.html b/readme.html index 11a3c7d..b9c6574 100644 --- a/readme.html +++ b/readme.html @@ -1,46 +1,5 @@ - - -
+
                      ██                 
                      ██          ██     
                      ██          ██     
@@ -60,29 +19,74 @@
 
 
-

snkt

+ +

+snkt

-

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

+

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

-

Status

+

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.

-

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

+

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

+

+Status

-

Installation

+

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.

+

Install Go for your platform.

Download and build snkt with something like

@@ -92,12 +96,12 @@

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

-

Quick Start

- -

Creating a Site

- -

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

+

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

$ snkt -i myblog
 
@@ -118,12 +122,12 @@
  • config.yml configuration file
  • - -

    First Post

    +

    +First Post

    A one line plaint text file is a valid post.

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

    Build the site

    @@ -143,25 +147,25 @@
  • rss.xml
  • - -

    Viewing the Results

    +

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

    +

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

    -

    Command Line Options

    +

    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")
    +    	configuration file (default "config.yml")
       -h, --help
         	print usage information
       -i, --init directory
    @@ -179,10 +183,10 @@
     
    $ snkt -c site.yaml -b
     $ snkt --config=myconfig.yml -v -w
     
    +

    +Configuration

    -

    Configuration

    - -

    Per site configuration is via a YAML file.

    +

    Per site configuration is via a YAML file.

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

    @@ -218,7 +222,7 @@ $ snkt --config=myconfig.yml -v -w site_title -string for the site’s title +string for the site's title @@ -230,7 +234,7 @@ $ snkt --config=myconfig.yml -v -w filters -list of search/replace regex’s to run on posts +list of search/replace regex's to run on posts @@ -265,8 +269,8 @@ $ snkt --config=myconfig.yml -v -w - -

    Posts

    +

    +Posts

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

    @@ -289,13 +293,13 @@ 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. +`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.

    +

    Templates use the standard library Go text/template.

    Entities in the templates --

    @@ -339,8 +343,8 @@ You don't have to worry about that right now. Honest. Date string RssDate string
    - -

    home

    +

    +home

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

    @@ -348,8 +352,8 @@ You don't have to worry about that right now. Honest.
  • {{.Site}} Site
  • {{.Posts}} Posts all posts on site in reverse chronological order
  • - -

    post

    +

    +post

    Each individual post uses this template

    @@ -357,8 +361,8 @@ You don't have to worry about that right now. Honest.
  • {{.Site}} Site
  • {{.Post}} Post the individual post
  • - -

    archive

    +

    +archive

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

    @@ -366,8 +370,8 @@ You don't have to worry about that right now. Honest.
  • {{.Site}} Site
  • {{.Posts}} Posts all posts, reverse chronological order
  • - -

    rss

    +

    +rss

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

    @@ -375,10 +379,10 @@ You don't have to worry about that right now. Honest.
  • {{.Site}} Site
  • {{.Posts}} Posts all posts, reverse chronological order
  • - -

    Advanced Configuration Options

    - -

    Permalink and filename formatter

    +

    +Advanced Configuration Options

    +

    +Permalink and filename formatter

    Permalinks (URLs for individual posts) can be customized.

    @@ -424,42 +428,42 @@ You don't have to worry about that right now. Honest. -

    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

    +

    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>
    +
    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

    + 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

    +

    +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

    +

    +Tags

    There is preliminary support for tag style metadata per post.

    -

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

    +

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

        tags: TagOne, tag two, a third tag, fourth
     
    @@ -476,36 +480,37 @@ You don't have to worry about that right now. Honest.
     

    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

    +

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

    +

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

      -
    • post’s ContentType will be set to “image”
    • +
    • post's ContentType will be set to "image"
    • text fields will be empty strings
    • metadata will be populated as it can via exif (maybe)

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

    - -

    Example configurations, sites, themes

    +

    +Example configurations, sites, themes

    not done

    - -

    Rebuild and deployment recipes

    +

    +Rebuild and deployment recipes

    also not done

    - -

    TODO

    +

    +TODO

    • sample sites/templates
    • proper man pages for docs
    +

    +Feedback

    -

    Feedback

    - -

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

    +

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

    +
    \ No newline at end of file -- cgit v1.2.3