drsnyder edited this page Dec 29, 2010 · 10 revisions

Installation

Furthermore was developed using Python 2.5. I haven’t tested it with any other versions. To get started, first, make sure you have Pygments installed and markdown with codehighlight (should be bundled with markdown now). This is required if you want to do syntax highlighting. I haven’t tried running it without this support available. Next, make sure you have PyYAML, PyRSS2Gen, and mako.


 sudo easy_install pygments
 sudo easy_install markdown
 sudo easy_install PyRSS2Gen
 sudo easy_install PyYAML
 sudo easy_install mako

Features

Furthermore is pretty simple right now. It is a bare bones static site generator with the following:

  • mako templates for python-based template generation
  • pygments syntax highlighting
  • markdown for text-to-html generation
  • a local http server for site previewing

Usage

You will probably want to edit the header, footer, index, and post templates under the templates directory and index.html in the top level directory to suit your needs. You probably also want to change any reference to damonsnyder.com to your domain in the templates and in lib/Document.py. One of the things I would like to change is adding a config file where you can set some of the site wide constants. This might be first on the TODO list.

You can generate your site by running:


./bin/furthermore -b . -P -o www -f index.html -S .

This will use the current directory ‘.’ to find the css files, templates, and posts. The -P switch tells furthermore to process your posts and generate html output. The -o switch will cause the processed files to be rendered in the ‘www’ directory. The -f switch will cause furthermore to process the index.html file in the current directory. This switch can be used multiple times. The -S switch will fire up a server on port 8080 so that you can preview your site. If you want to change the port it runs on, you can specify it with the -p switch. To see all of the command line options, run futhermore with the -h switch.

If you want to process other static files such as an about page or an article, you can process it with the -f switch and it will be rendered to the top level of the output directory you specify with the -o option. See the Posts section below for the file format. Files processed with the -f option are treated the same as posts except that the date port of the post file format will not be processed. In other words, everything before .html/.markdown will be treated as the post slug (e.g. index[.html|.markdown]).

Posts

Posts go in the “posts” directory and take the form YYYYMMDD-post-slug.markdown. Posts consist of a YAML preamble defining the document layout and the title. Here is what a typical post file looks like with the preamble at the top:


---
layout: post
title: My post title
...
The post body would go here using markdown.

If a document being processed ends in .markdown, it will be run through markdown for formatting. If it ends in html, it will only be processed using mako. If it suits you, you could write your posts using mako only.

Syntax Highlighting

If you want to write code in your documents and have the syntax highlighted, just prefix the language with ::: and indent the whole block by 4 spaces. I believe you can use a tab as well, but I haven’t tried it. It should look like the following:


    :::python
    def do_something():
        pass

This section will be rendered in a code block with syntax highlighting. Just make sure you include the pygments.css in your html. You can also render your own css file using pygmentize. I used the command below to generate the css file included.


pygmentize -f html -S default | awk '{ print ".codehilite " $0}' > css/pygments.css 
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.