dil

LitePub

2018-01-12

Tags: hello there

why I created it.

Overview

LitePub is a static blog generator that tries to be as easy to use as possible.

It requires no software dependencies, needs no configuration files, uses no databases. All it needs is one binary, posts written in Markdown and a set of templates to render the posts to static HTML files.

Posts don't have to include any special metadata (aka front matter) like title or date in them - the title, date and optional tags are parsed from the natural flow of the posts.

Quick Start

To create a sample blog follow these steps:

  1. Download a release and unpack it to a directory.

  2. cd to the directory.

  3. Create a sample blog:

    $ ./litepub create

  4. Build the blog:

    $ ./litepub build

Generating: index.html Generating: tags/reference.html Generating: tags/tutorial.html Generating: tags/advanced.html Generating: tags/docs.html Generating: tags/basics.html Generating: overview.html Generating: quick-start.html Generating: installation.html Generating: creating-a-blog.html Generating: creating-posts.html Generating: generating-html-files-for-a-blog-aka-building-a-blog.html Generating: serving-a-blog.html Generating: templates.html Generating: getting-help.html ```

  1. Run the built-in server:

    $ ./litepub serve
 Running on http://localhost:2703
 Ctrl+C to quit

  2. Open http://localhost:2703 in your browser.

Documentation

Installation

Download a release and unpack it to a directory. That's all.

You can optionally add the directory to the PATH so you can run litepub from any directory. All examples assume you have litepub in your PATH.

Creating a Blog

The following will create a sample blog in the current directory:

$ litepub create

If you don't need the sample templates and posts use the --skeleton option:

$ litepub create --skeleton

Because the template files are required they will be still created but with no content.

Directory Structure

Each blog is stored in a directory with the following structure:

The create Command Reference

Usage:
   litepub create [<dir>] [-s, --skeleton] [-q, --quiet]
 
 Arguments:
   <dir>  The directory to create the blog in or look for; it will be created if
          it doesn't exist (only when creating a blog) [default: .]
 
 Options:
   -s, --skeleton     Don't create sample posts and templates
   -q, --quiet        Show only errors

Creating Posts

To create a post just add a Markdown file in the posts directory. The file name and extension aren't important, only the content of the file.

All posts need to be stored directly in the posts directory. In other words, subdirectories in the posts directory are ignored when looking for posts.

Each post looks like this (it's the start of an actual post from my blog):

  • Line 1 is the post's title. If it starts with one or more #s they are stripped. So in this case the title becomes How I Switched from Java to JavaScript.
  • Line 3 is the post's date. It has to be in the *MMM d, YYYY* format.
  • Line 5 are comma separated post tags.
  • Anything below line 6 is the content of the post.

The post's title and date are required. Tags are optional.

Draft Posts

Any post can be marked as draft by simply moving it to the draft subdirectory of the posts directory. To unmark it just move it back to the posts directory.

Deleting a post is analogous to drafting: just remove it from the posts directory.

Generating HTML Files for a Blog, aka Building a Blog

To generate the HTML files for a blog cd to the blog's directory and use the build command:

$ litepub build
 Generating: index.html
 Generating: tags/reference.html
 Generating: tags/tutorial.html
 Generating: tags/advanced.html
 Generating: tags/docs.html
 Generating: tags/basics.html
 Generating: overview.html
 Generating: quick-start.html
 Generating: installation.html
 Generating: creating-a-blog.html
 Generating: creating-posts.html
 Generating: generating-html-files-for-a-blog-aka-building-a-blog.html
 Generating: serving-a-blog.html
 Generating: templates.html
 Generating: getting-help.html

The draft posts are ignored when building a blog.

LitePub takes the *.tmpl files from the templates directory, applies them to posts stored in the posts directory and generates the HTML files to the www directory. It also copies all accompanying files (and directories) from the templates directory to the www directory.

The generated HTML file names are created by slugifying the post title (or the tag name when generating tag pages) and adding the html extension. For example, a post with the How I Switched from Java to JavaScript title is generated to the how-i-switched-from-java-to-javascript.html file.

The build Command Reference

Usage:
   litepub build  [<dir>] [-q, --quiet]
 
 Arguments:
   <dir>  The directory to create the blog in or look for; it will be created if
          it doesn't exist (only when creating a blog) [default: .]
 
 Options:
   -q, --quiet        Show only errors

Serving a Blog

LitePub has a built-in server so you can see how a generated blog looks like in a browser. cd to the blog's directory and start the server:

$ litepub serve
 Running on http://localhost:2703
 Ctrl+C to quit

Now open http://localhost:2703 in your browser to see the generated blog.

Note that the server ignores the draft posts.

Serving a Blog on a Different Port

When starting the server you can specify a port on which to listen with the --port option:

$ litepub serve --port 3000
 Running on http://localhost:3000
 Ctrl+C to quit

Serving a Blog and Watching for Changes

When creating templates or even writing posts it's quite useful to be able to immediately see the changes after refreshing the page. To tell LitePub that it should watch for changes to posts and templates use the --watch option:

$ litepub serve --watch
 Running on http://localhost:2703
 Rebuilding when posts or templates change
 Ctrl+C to quit

Note that subdirectories in the posts and templates directories aren't watched.

Rebuilding a Blog Before Serving

Sometimes it can be useful to rebuild a blog before serving it, for example when you don't remember if you made any changes to posts or templates. To rebuild a blog before serving use the --rebuild option:

$ litepub serve --rebuild
 Generating: index.html
 Generating: tags/reference.html
 Generating: tags/tutorial.html
 Generating: tags/advanced.html
 Generating: tags/docs.html
 Generating: tags/basics.html
 Generating: overview.html
 Generating: quick-start.html
 Generating: installation.html
 Generating: creating-a-blog.html
 Generating: creating-posts.html
 Generating: generating-html-files-for-a-blog-aka-building-a-blog.html
 Generating: serving-a-blog.html
 Generating: templates.html
 Generating: getting-help.html
 Running on http://localhost:2703
 Ctrl+C to quit

The serve Command Reference

Usage:
   litepub serve  [<dir>] [-R, --rebuild] [-p, --port <port>] [-w, --watch] [-q, --quiet]
 
 Arguments:
   <dir>  The directory to create the blog in or look for; it will be created if
          it doesn't exist (only when creating a blog) [default: .]
 
 Options:
   -R, --rebuild      Rebuild the blog before serving
   -p, --port <port>  The port to listen on [default: 2703]
   -w, --watch        Rebuild the blog when posts or templates change
   -q, --quiet        Show only errors

Templates

The create command adds sample templates to the templates directory. Of course, you can change them or create your own from scratch.

LitePub uses the Go html/template package to define the templates.

Design changes require no knowledge of Go templates. However changes that affect what data is displayed will require it less or more (depending on the change).

Structure

There are four required files in the templates directory:

  • layout.tmpl defines the common layout for the home page (index.tmpl), post pages (post.tmpl) and tag pages (tag.tmpl)
  • index.tmpl is used when generating the home page (index.html)
  • post.tmpl is used when generating post pages
  • and tag.tmpl is used when generating tag pages

Besides the four files there can be any number of html, css, js, png, etc. files that are used by the .tmpl files.

If you're not familiar with Go templates, some things in the next sections can be unclear.

Data

Templates have access to data they are meant to display. There are two types of data: Posts and Tags.

Posts

A Post has the following properties:

  • Title - the post title
  • Content - the content of the post as Markdown text
  • Written - the post's date
  • Tags - an array of tags the post is tagged with (can be empty)
  • Draft - true if the post is a draft

To get a post's page URL in a template use the slug function (described below) like this: <a href="/{{.Title | slug}}.html">A Post</a>.

Tags

A Tag has the following properties:

  • Name - the tag name
  • Posts - an array of Posts that are tagged with the tag sorted by Written in descending order

To get a tag's page URL in a template use the slug function (described below) like this: <a href="/tags/{{.Name | slug}}.html">A Tag</a>.

The index.tmpl template has access to an array of Posts sorted by Written in descending order. The post.tmpl template has access to the Post it displays. The tag.tmpl template has access to the Tag it displays.

Functions

The index.tmpl, post.tmpl and tag.tmpl templates have access to the following functions:

html

Converts a Markdown string to a raw HTML, for example {{.Content | html}}.

summary

Extracts the first paragraph of a Markdown string that isn't a header (doesn't start with a #), for example {{.Content | summary | html}}.

even

Returns true if an integer is even, for example {{if even $i}}<divclass="row">{{end}}.

inc

Increments an integer by one, for example {{if or (eq (inc $i) $l) (not (even $i))}}</div>{{end}}.

slug

Slugifies a string, for example <a href="/{{.Title | slug}}.html">A Post</a>.

The available functions represent my needs when converting my handmade blog to a generated one.

Getting Help

To see all available commands and their options use the --help option:

$ litepub --help
 LitePub 0.5.1 [github.com/mirovarga/litepub]
 Copyright (c) 2016 Miro Varga [mirovarga.com, hello@mirovarga.com, @mirovarga]
 
 Usage:
   litepub create [<dir>] [-s, --skeleton] [-q, --quiet]
   litepub build  [<dir>] [-q, --quiet]
   litepub serve  [<dir>] [-R, --rebuild] [-p, --port <port>] [-w, --watch] [-q, --quiet]
 
 Arguments:
   <dir>  The directory to create the blog in or look for; it will be created if
          it doesn't exist (only when creating a blog) [default: .]
 
 Options:
   -s, --skeleton     Don't create sample posts and templates
   -R, --rebuild      Rebuild the blog before serving
   -p, --port <port>  The port to listen on [default: 2703]
   -w, --watch        Rebuild the blog when posts or templates change
   -q, --quiet        Show only errors
   -h, --help         Show this screen
   -v, --version      Show version

About me

Hi, i'm and this is my place.

This is my picture:


I'm a web developer. I like Ruby the most but i'm fine with other technology also. After all, it's just technology.

I work at topmonks.com. I also have my own tiny company Imagine Anything.

One of my side projects is DameData.cz. It's a web app which helps you to easily connect your business with accounting(czech market only right now). Check it out:

DameData.cz logo

Have a good one