lol

a static website generator in chicken scheme.

page contents

• features
• caveats
• disclaimer
• requirements
• compilation
• installation
• usage
• configuration

features

• sleep deprived, rushed, no-time-to-write dad documentation
• not scalable
• badly programmed
• the programmer had a lot of fun writing it
• markdown for source files (john gruber's markdown, so indentation is used for codeblocks, instead of three backticks.)
• directory structure of the source directory is copied to the build directory
• supports copying static assets to the build directory
• optionally generate an rss feed
• optionally generate a list of posts
• optionally clean build directory before building
• built-in local web server for previewing your work
• templates for html pages, a page containing a list of posts, and the rss feed
• config file where you can customize built-in variables or create new ones

caveats

• lots

disclaimer

i wish i could make this documentation a little more detailed, but right now i don't have the time or energy to, and want to spend that time and energy programming, because it makes me happy. maybe i'll try to add to this when i'm in the mood, but i can't guarantee anything.

requirements

• a unix-like operating system
• chicken scheme 5
• utf8 egg
• lowdown egg
• spiffy egg

if you use an x86_64 linux system, there is a binary that you can use in the builds directory.

compilation

by default, the Makefile compiles a static binary in the builds directory of this Git repository.

to compile lol from source, following the steps below:

1. run make dependencies as root.
2. run make.

installation

~/.local/bin is the default installation directory. you'll need this directory in your $PATH, so you can run the lol command from any directory.

to install lol, run make install.

usage

run lol <command>, where <command> is one of the commands below:

• help: display the help message.
• init: create the files and directories that are required for generating a website.
• build: generate a website.
• preview: preview your website on a local http server.

configuration

this section describes which templates that built-in variables populate by default, conditional settings, and the purposes of the default directories, files, and templates.

default variables

you can change the value of the variables described in this section by editing the config.scm file.

• author: populates a placeholder in the templates/page.html template.
• description: populates a placeholder in the templates/page.html template.
• keywords: populates a placeholder in the templates/page.html template.
• domain: populates placeholders in the templates/page.html and templates/channel.xml templates.
• rss-file: populates placeholders in the templates/page.html and templates/channel.xml templates.

run-time variables

you can't change the value of the variables described in this section, but you can move these variables around the template files, or remove these variables from templates.

• page-title: populates placeholders in the templates/page.html and templates/item.xml templates. the first line of each file in the posts-directory populates each instance of page-title in the templates that it occurs.
• page-url: populates a placeholder in the templates/item.xml template. local pathnames to source files are converted to page-urls.
• page-date: populates a placeholder in the templates/item.xml template. the third line of each file in the posts-directory populates each instance of page-date in the templates that it occurs.
• css: refer to the information about the css-file in the files section.
• page-contents: populates the templates/page.html template with html that's generated from markup files in the source directory.
• links: populates the templates/posts.txt template with a list of links.
• rss-items: populates the templates/channel.xml template with a list of rss <item>s. these <items> are customizable using the templates/item.xml template.

conditionals

you can change the value of the variables described in this section by editing the config.scm file.

• clean-build-directory?: if "yes", then the build-directory is deleted and recreated before building.
• generate-posts-page?: if "yes", then a list of posts is generated at <build-directory>/<posts-directory>/index.html by recursively searching the posts-directory for markup files..
  • the first line of each file should have a markup h1 title.
  • the third line of each file should have a date in the format of yyyy-mm-dd hh:mm.
• generate-rss-feed?: if "yes" , then an rss feed is generated at <build-directory>/<rss-file> by recursively searching the posts-directory for markup files.
  • the first line of each file should have a markup h1 title.
  • the third line of each file should have a date in the format of yyyy-mm-dd hh:mm.

directories

you can change the value of the variables described in this section by editing the config.scm file.

• build-directory: the directory where your website is generated.
• source-directory: the directory that contains your markup files and directories. the structure of this directory is copied to the build directory. for example, if you have a markup file at source/friends/list-of-friends.md, then a build/friends/list-of-friends.html file is created.
• assets-directory: the directory containing items that you want copied over to the build-directory.
• templates-directory: the directory that contains the templates for html and rss generation.
• posts-directory: the directory that's recursively searched for markup files if generate-posts-page? is "yes". the first line of each markup file should contain a markup h1 title, which is used as the link title for each post on the posts page. the path of the file is parsed and converted into a link for each post on the posts page.

files

you can change the value of the variables described in this section by editing the config.scm file.

• css-file: the contents of this file replaces the {{css-file}} placeholder in the html-page-template.
• rss-file: the filename of the rss feed file.

templates

you can move the {{placeholders}} around the template files described in this section.

• html-page-template: a file with placeholder values that are replaced with values in the config.scm file. all markup pages use this template.
• posts-page-template: a file with placeholder values that are replaced with values in the config.scm file. if a {{links}} placeholder exists in the posts-page-template, then a list of links replaces the {{links}} placeholder. the list of links is generated from markup files in the posts-directory directory. the posts page is generated at <build-directory>/<posts-directory>/index.html.
• rss-channel-template: a file with placeholder values that are replaced with values in the config.scm file.
• rss-item-template: a file with placeholder values that are replaced with values in the config.scm file, and values that are generated from the first and third lines of each file in the posts-directory. refer to generate-rss-feed? for more information about the first and third lines of each file in the posts-directory.