/ 
App-PFT-v0.04.1
River stage zero No dependents
/ pft

pft - Hacker friendly static blog generator

SYNOPSYS

pft <command> [options]

AVAILABLE COMMANDS

Here follows a list of available commands:

  • init: Initialize a pft site in the current directory;

  • blog: Create a new blog entry;

  • page: Create a new page;

  • make: Build the website;

  • pub: Publish on the Web;

  • clean: Clear built tree;

  • tag: Edit tag page;

  • help: Show usage manual.

For options of a specific command cmd use pft cmd --help

FILESYSTEM LAYOUT

A new site can be initialized by running the pft init command inside a directory. In this document such directory will be conveniently called ROOT.

The initialization command produces the following filesystem structure:

ROOT
├── content
│   ├── attachments     - Location for attachments
│   ├── blog            - Root location for blog entries source files
│   ├── pages           - Location for pages source files
│   ├── pics            - Location for pictures lookup
│   └── tags            - Location for tag pages source files
├── inject              - Content to bulk inject the online site root
├── pft.yaml            - Configuration file
└── templates           - Location for templates

The purposes of the directories is explained in the BUILDING A SITE section of this document.

Configuration in pft.yaml

The configuration file is created automatically by the pft init command (run pft init --help for further information). The file is formatted as a YAML document

Title Mangling

The pft blog and pft page commands can be used to generate new blog entries and pages respectively. Besides options, both require a title to be specified in order to enable editing. The title is obtained by joining the non-option parameters into a space separated string.

For example, the command

pft page [...options...] The "User's" Original Title

Will result into the following title:

$title = "The User's Original Title";

The original title is retained in the header of the generated content file, while the file where the content will be stored is named by mangling the title:

$title =~ s/\W/-/g;    # all the non-word characters replaced by '-'
$title =~ s/--+/-/g;   # multiple '-' are packed together
$title =~ s/-*$//;     # trailing '-' are dropped
$basename = lc $title; # everything is lower-cased

The following titles will therefore be reduced to the same mangled file name:

  • Here is me eating pork chop

  • Here is ME eating -- pork/chop

  • Here-is-me-eating-pork-chop

And for all of them the resulting filename will be:

  • here-is-me-eating-pork-chop

CONTENT, EDITING AND FORMAT

The skeleton of a content file is usually created by pft when a blog entry, a page or a tag is edited for the first time. Content files are always positioned under the ROOT/content directory.

Content files are made of plain text. A first section is a YAML header representing the configuration for the content. The header is followed by a line with three dashes (---) which marks the beginning of the actual content document. The document will be parsed as MultiMarkdown when compiled.

Editing files

The pft blog, pft page and pft tag commands will act as helpers for editing content.

They will access a new file in the correct filesystem position, which depends on the kind of content. If the target file does not exists, all three commands will start by generating a skeleton. In all cases an editor will be opened on the file. The $EDITOR environment variable is required and will be honored.

After the editor is closed a warning will be issued if the header is invalid. If the file is empty (as in zero bytes) it will be removed from the filesystem.

A header is invalid if it's not a valid YAML document or if it does not contain at least the Title field.

For specific information about pages, blog entries and tags editing, see

pft page -h
pft blog -h
pft tag -h

Tagging

As in other blogging platforms, content can be assigned with multiple tags. When compiling the site into HTML, pft create, for each existing tag, a tag page. The page will contain an optional description of the tag, and link to all tagged contents.

A description for the tag named foo can be prepared by invoking the pft tag command as follows:

pft tag foo

This will create the ROOT/content/tags/foo content file and open it file with $EDITOR.

Special references handling

Markdown supports a syntax for defining links and pictures which gets translated into HTML <a> and <img> tags respectively. Also, since Markdown is a super-set of HTML, direct HTML can be supplied in the text. Both forms will result in HTML links after the Markdown to HTML transformation, so here we refer in general to the final HTML.

pft parses these URLs in order to provide additional linkage semantics. The recognized format is:

:kind:param/param/...

There is a number of supported kind keywords, enumerated in this document. Additional parameters can be specified and separated by a / symbol.

Pictures:

Picture reference accept special links in the form

<img src=":pic:filename"/>

This form will be resolved by pft, and a link will be generated to the file named named filename inside the ROOT/content/pics directory. The name provided is used directly as lookup, so the complete basename should be provided. Compilation results in errors unless the required file exists

Example:

<img alt="..." src=":pic:test.png"/>

URLs:

Regular URLs in <a/> tags accept the following special prefixes:

:page:pagename

Binds the link to the coordinates of the page named pagename. The provided name can be:

  • The actual file name of the content in ROOT/content/pages;

  • Any title which results in the correct file name after mangling (see the Title Mangling section of this document). Mind about spaces, which must be replaced by / symbols.

    For example, the following forms are equivalently pointing to the same page, previously created with the pft page 'Foo, Bar '+' Baz' command:

    <a href=":page:foo-bar-baz">

<a href=":page:foo/bar/baz">

<a href=":page:Foo,/Bar/+/baz">
:blog:back/N

Only valid within a blog entry. The generated link refers to N blog entries before the current one. The N parameter is optional, and defaults to zero.

Examples:

<a href=":blog:back/5">     (5 entries ago)

<a href=":blog:back/0">     (previous entry)

<a href=":blog:back">       (equivalently, previous entry)
:web:service/param/param/...

Generate an URL which points to a web service (e.g. search engines, or specialized website) and passes data on the query.

The Web Search section of this document contains a number of supported values for service, while the following list of params depends on the specific service.

Special URLs in the form :web:service/param/... can be used to link to online services, like search engines, portals and others. This section is a reference of supported services.

Duck Duck Go

:web:ddg/bang/param/param/...

Search query on the Duck Duck Go search engine. The first parameter is used for Duck Duck Go's Bang syntax, and can be empty in order not to use any Bang.

Example: search linux howto on Duck Duck Go:

:web:ddg//linux/howto

Example: search linux howto with the !yt bang (redirects search on YouTube):

:web:ddg/yt/linux/howto

Example: search linux howto with the !so bang (redirects search on StackOverflow):

:web:ddg/so/linux/howto
Manpages

:web:man/name

:web:man/name/section

Point to an online manpage. Manual section can be optionally supplied.

Examples:

:web:man/bash

:web:man/signal/7

BUILDING A SITE

A site is built into HTML by using the pft make command. This will compile all the content files found in ROOT/content>, and build them inside the ROOT/build directory. Additional pages are also created, like tag pages and month pages, which will index regular contents.

Templates

pft uses the Template::Alloy engine to inject the content inside HTML files.

The compilation process requires three template files to be inside the ROOT/templates directory:

  • entry.html is used as template for blog entries;

  • page.html is used as template for content pages;

  • gen.html is used as template for all generated pages;

Upon initialization with pft init, the ROOT/templates directory is populated with template called default.html, which is good enough for all three kind of pages. It is symlinked to entry.html, page.html and gen.html.

Customizations of the theme and inclusion of third party scripts can be achievd by modifying the default.html file, or by replacing the desired template.

The original configuration can be restored by removing the files to be reset and running pft init again.

Injection

In some configurations, a website needs some additional data to be put online. A good example could be the .htaccess file for the Apache webserver.

Any file or directory which is need, online together with the site, can be copied or symlinked in the ROOT/inject directory. The pft make command will take care of symlinking it into the ROOT/build directory upon compilation.