nonlinear
/
www-gopher
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
www-gopher/README.md

9.6 KiB
Raw Blame History

README

Introduction

cl-yag is a very lightweight, 'static site'-generator that produces gopher sites as well as html websites. The name 'cl-yag' stands for 'Common Lisp - Yet Another website Generator'. It runs without Quicklisp.

Showcase

I am using cl-yag to create and maintain my websites in the world-wide-web (visit: Solene'spercent) as well as in gopher-space.

Requirements

To use cl-yag you'll need:

  1. A Common Lisp Interpreter
    • cl-yag's current default is Steel Bank Common Lisp (SBCL).
    • Embeddable Common Lisp (ECL) will do fine as well.
  2. A Markdown-to-HTML Converter
    • cl-yag's current default is multimarkdown.
  3. BSD Make
    • Linux-Users, cl-yag uses a BSD Makefile syntax, that isn't compatible with GNU make's.
    • You need to install a port of the NetBSD make tool, called bmake.

Usage

Go into your project's directory and type make. You'll find your new website/gopher page in 'output/'. If you want to get rid of everything in your 'output/' subdirectories, type make clean. For further commands: read the Makefile. Read in the follwing section where to find it.

Overview: cl-yag's File Hierarchy

After cloning the repository, your project's directory should contain at least the following files and folders:

. |-- LICENSE |-- Makefile |-- README.md |-- data/ | |-- 1.md | |-- README.md | -- articles.lisp |-- generator.lisp |-- output/ | |-- gopher/ | -- html/ |-- static/ | |-- css/style.css | -- img/ -- templates/ |-- article.tpl |-- gopher_head.tpl |-- layout.tpl |-- one-tag.tpl |-- rss-item.tpl `-- rss.tpl

  • Makefile
    • This file exists to simplifiy the recurring execution of frequently used commands.
  • generator.lisp
    • This is cl-yag's core library.
  • static/
    • This directory holds content, that needs to be published without being changed (e.g. stylesheets, js-scripts).
    • If you come from 'non-static CMS'-Country: 'static/' holds, what you would put in your 'assets/' directory.
  • templates/
    • The templates in this directory provide the structural skeleton(s) of the webpages and feeds you want to create.
  • output/
    • cl-yag puts in this directory everything ready to get deployed.
    • Because cl-yag generates not only HTML, but gopher-compliant pages as well, output/ holds two subdirectories.
      • gopher/ : contains the website for gopher,
      • html/ : contains the website in HTML.

And there is the data/ directory, which is important enough to get a subsubsection of its own.

The 'data/' Directory

This directory is crucial for the usage of cl-yag.

data/ contains

  • the articles.lisp configuration file, which defines important metadata for posts and pages.
  • It also holds ${id}.md-files, which are holding your posts' and pages' content. You can use markdown to write them.

For more information: Read section 'Configuration'.

Configuration

cl-yag's main configuration file is data/articles.lisp.
In order to have a reliably running implementation of cl-yag, you have to set most of the values in this file.

data/articles.lisp has two parts:

  1. A variable called config. It defines global values, that define your webpage.
  2. A variable called articles. It defines local values, that - in turn - define individual pages/posts.

Values are assigned by placing a string (e.g. "foo") or a boolean (i.e. 't' or 'nil') behind a keyword (e.g. ':title').

The config Variable

The config variable is used to assign the following values:

  • :webmaster
    • The name of the default(!) author.
    • :webmaster gets used, if :author is omitted. (see below: 'The articles variable'.)
  • :title
    • The title of the webpage
  • :description
    • This text is used in the description field of the Atom RSS
  • :url
    • This needs to be the full(!) URL of your website, including(!) a final slash.
    • MIND: If the url contains a tilde (~), it needs to get duplicated
    • Example: https://mydomain/~~user/ is a valid url.
  • :rss-item-number
    • This holds the number of latest(!) RSS items you want to get published when you generate the files.
  • html
    • t to export html website. Set nil to disable.
  • gopher
    • t to export gopher website. Set nil to disable.
  • gopher-path
    • This is the full path of the directory to access your gopher hole.
  • gopher-server
    • Hostname of the gopher server. Because gopher doesn't allow relative links (like html), you need to know where you put your files.
  • gopher-port
    • tcp port of the gopher server. 70 is the default port. It need to be included in every link (see: gopher-server).

The articles Variable

The articles variable holds per page/post-metadata. Of the following fields, only the :author and :short description could be omitted.

  • :short
    • The :short field's value is used for displaying a really short description of the posts content on your homepage.
    • If :short doesn't get a value, the full article gets displayed.
    • Hint: Use :short "view the article for the full text", if you don't want to display the full text of an article on your index site.
  • :id_
    • The :id field holds the filename of your post/page.
    • Example: :id "2" will load file data/2.md. Use text instead of numbers, if you want to.
    • (See section: 'The data/ Directory'.)
  • :author
    • The :author field is used to display the article' author.
    • If you omit it, the generator will take the name from the :webmaster field of the config variable.
  • :tag
    • :tag field is used to create a "view" containing all articles of the same tag.
    • MIND: Whitespaces are not allowed in(!) tags.

Howto Create A New Post

Edit data/articles.lisp and add a new list to the articles variable:

(list :title "How do I use cl-yag"
      :id "2"
      :date "29 April 2016"
      :author "Solène"
      :short "I will explain how to use the generator"
      :tag "example help code")

Then write a corresponding 2.md file, using markdown.

Howto Publish A Post

I prepared a Makefile to facilitate the process of generating and publishing your static sites.

All you need to do in order to publish is to go into your cl-yag directory and type "make".

The 'make' command does create html and gopher files in the defined output/ location (which can be a symbolic link pointing to some other directory, somewhere else on your machine).

Howto Add A New Page

You may want to have some dedicated pages besides the index or a post. To create one, edit the generate-site function in cl-yag's generator.lisp and add a function call, like this:

(generate "somepage.html" (load-file "data/mypage.html"))

This will produce the file somepage.html in the output folder.

Further Customization

Howto Use Another Common Lisp Interpreter

cl-yags default Lisp interpreter is sbcl. If you want to use a different lisp interpreter you need to set the variable 'LISP' to the name of your binary, when calling make.

make LISP=ecl

Using git Hooks For Publishing

You may customize your publishing-process further, e.g. by using a git hook to call 'make' after each change in the repo so your website gets updated automatically.

Page-Includes

Here is an example code, if you want to include another page in the template:

  1. Create template/panel.tpl with the html you want to include.

  2. Add a string in the target file, where the replacement should occur. In this case, we choose %%Panel%% for a string, and, because we want the panel to be displayed on each page, we add this string to template/layout.tpl.

  3. Modify the function generate-layout in cl-yag's generator.lisp accordingly. This is done by adding the following template function call:

    (template "%%Panel%%" (load-file "template/panel.tpl"))

(Note: You can insert your text directly into the layout template file as well.)

Known Limitations

Use ~~ To Create ~

cl-yag crashes if you use a single "~" caracter inside one data structure in articles.lisp files, because Common Lisp employs the tilde as a prefix to indicate format specifiers in format strings.

In order to use a literal ~ - e.g. for creating a :title or :url reference - you have to escape the tilde by duplicating it: ~~. (See :url in section 'Configuration').

Posting Without Tagging

cl-yag allows posts to be 'untagged'- but with the default template you'll get a line below your title that displays: "Tags: ".

(Note: If you are looking for a way to contribute this may be a task for you.)

A Note On Themes

Although cl-yag may ship with a minimalistic template, cl-yag focuses only on generating html- and gopher-compliant structural markup - not themed layouts.

If you want some deeply refined, cross-browser compatible, responsive, webscale style-sheet, you need to create it yourself. However, cl-yag will work nicely with it and if you want to make your stylesheets a part of cl-yag you're very welcome to contact me.

Hacking cl-yag

I tried to make cl-yag easy to extend. If you want to contribute, feel free to contact me and/or to send in a patch.

  • If you are looking for a way to contribute:
    • You could find a way to "sanitize" cl-yag's behaviour regarding the tilde (see: above);
    • Also see: 'Note' in 'Posting Without Tagging';
    • Also see: 'A Note On Themes.