~solene/cl-yag

7258c13e — Solene Rapenne 1 year, 1 month ago
Bump license
a3604d3b — Solene Rapenne 2 years ago
Use .gmi extension for gemini texts
23d6c036 — Solene Rapenne 3 years ago
Fixing typo, one reported by Oliver Marugg

clone

read-only
https://git.sr.ht/~solene/cl-yag
read/write
git@git.sr.ht:~solene/cl-yag

You can also use your local clone with git send-email.

#README

#Introduction

cl-yag is a 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 needing Quicklisp (Common LISP library manager).

#Showcase

I am using cl-yag to create and maintain my websites in the world-wide-web (visit: [Solene's percent] (https://dataswamp.org/~solene/)) as well as [in gopher-space] (gopher://dataswamp.org/1/~solene/).

#Requirements

To use cl-yag you'll need:

  1. A Common Lisp Interpreter
  2. A Markdown-to-HTML Converter

#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/ sub directories, type make clean.
For further commands: read the Makefile. Read in the following 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 simplify 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. style sheets, 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 web pages 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 sub directories.
      • 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 meta-data for posts and pages.
  • It also holds ${id}.md files, which are holding your posts' (or 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 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. Its values define your web page.
  2. "posts" declaration with their meta-data

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 web-page
  • :description
    • This text is used in the description field of the atom/rss feed.
  • :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/
  • :rss-item-number
    • This holds the number of latest(!) RSS items you want to get published.
  • 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. It needs to be included in each link.
  • gopher-port
    • tcp port of the gopher server. 70 is the default port. It needs to be included in each link.
  • gopher-format
    • format of the gopher server. default is the geomyidae format, gophernicus format is commented.
  • gopher-index
    • name of the gopher menu file. default is index.gph for geomyidae, gophermap file is commented.

#Posts declarations

Each post is declared with its meta-data using the function "post". So you need to add a new line for each of your posts.

Of the following keywords, only :author and :short can be omitted.

  • :author
    • The :author field is used to display the article's author.
    • If you omit it, the generator will take the name from the :webmaster field of the config variable.
  • :id
    • The :id field holds the file name 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'.)
  • :tag
    • :tag field is used to create a "view" containing all articles of the same tag.
    • MIND: White spaces are used to separate tags and are not allowed in(!) tags.
  • :tiny
    • The :tiny field's value is used for displaying a really short description of the posts content on your homepage.
    • If :tiny doesn't get a value, the full article gets displayed.
    • Hint: Use :tiny "Read the full article for more information.", if you don't want to display the full text of an article on your index site.
  • :title
    • The :title field's value sets your post's title, its first headline, as well as its entry on the index.html.

#How-to 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"
	  :tiny "Read more about how I use cl-yag." 
	  :tag "example help code")

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

#How-to 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 creates html and gopher files in the defined location. The default is the output/ directory, but you can use a symbolic link pointing to some other directory as well.

#How-to 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 output/html/somepage.html.

#Further Customization

#How-to Use Another Common Lisp Interpreter

cl-yags default Lisp interpreter is sbcl. If you want to use a different 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 the make program 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 templates/panel.tpl containing the html you want to include.

  2. Add a replacement-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 templates/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 "templates/panel.tpl"))
    

Another valid approach is to writer your html directly into templates/layout.tpl.

#Known Limitations

#Use ~~ To Create ~

cl-yag crashes if you use a single "~" character inside templates/articles.lisp, 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 without tags, but, using the default templates/layout.tpl, 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 minimalist template, cl-yag focuses on generating html- and gopher-compliant structural markup - not themed layouts.

If you want some deeply refined, cross-browser compatible, responsive, webscale style sheets, you need to create them yourself. However, cl-yag will work nicely with them and if you want to make your style sheets 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'.