~README.md, data/README.md Extensive Rework of README. ~data/articles.lisp Corr… | |
git clone git://bitreich.org/cl-yag/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws… | |
Log | |
Files | |
Refs | |
Tags | |
README | |
LICENSE | |
--- | |
commit f586103e1a32e6e2b5b3891275218c0e7400bc0a | |
parent 6d422b40904e9e0037a38117b45f9323de45ff70 | |
Author: lambda <[email protected]> | |
Date: Thu, 23 Nov 2017 17:14:54 +0100 | |
~README.md, data/README.md Extensive Rework of README. ~data/articles.lisp Corr… | |
Status of this commit: Suggestion. | |
Diffstat: | |
M README.md | 304 ++++++++++++++++++++++++-----… | |
M data/README.md | 304 ++++++++++++++++++++++++-----… | |
M data/articles.lisp | 8 ++++++-- | |
3 files changed, 480 insertions(+), 136 deletions(-) | |
--- | |
diff --git a/README.md b/README.md | |
@@ -1,108 +1,278 @@ | |
-# Introduction | |
+# README | |
-cl-yag stands for Common Lisp Yet Another Generator and obviously it's written… | |
-**It needs a Common Lisp interpreter and a markdown-to-html export tool (like … | |
-It is regularly tested with sbcl, clisp and ecl which are free, open-source an… | |
+## Introduction | |
-**This comes with a minimalistic template**, don't expect something good looki… | |
+cl-yag is a very lightweight, 'static site'-generator that produces **gopher**… | |
+The name 'cl-yag' stands for 'Common Lisp - Yet Another website Generator'. | |
+It runs without Quicklisp. | |
-As a "demo", there is [my website](https://dataswamp.org/~solene/) using cl-ya… | |
-## The hierarchy | |
+## Showcase | |
-Here are the files and folder of cl-yag : | |
- | |
-+ **Makefile** : exists to simplify your life (updating, cleaning) | |
-+ **generator.lisp** : contains all the code of the generator | |
-+ **templates/** : contains .tpl files which are used as template for the html… | |
-+ **static/** : contains the static files like images, css, js etc... that wil… | |
-+ **data/** : | |
- + **articles.lisp** : contains metadata about the website and the list of th… | |
- + **${id}.md** : contains the article using markdown syntax that will be use… | |
-+ **output/** : | |
- + **gopher/** : contains the exported website for gopher | |
- + **html/** : contains the exported website in html | |
- | |
-# Usage | |
+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/). | |
-## Configuration | |
-In data/articles.lisp there is a ***config*** variable with the following fiel… | |
+## 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 wi… | |
+ - 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 websi… | |
+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 | |
-+ **:webmaster** : The name of the default author, this is the name used when … | |
-+ **:title** : The title of the webpage | |
-+ **:description** : This text is used in the *description* field of the Atom … | |
-+ **:url** : This is the full url of the blog with the final slash. If the url… | |
-+ **:rss-item-number** : This is the number of RSS items you want to published… | |
-+ **html** : t to export html website / nil to disable | |
-+ **gopher** : t to export gopher website / nil to disable | |
-+ **gopher-path** : this is the full path of the directory to access your goph… | |
-+ **gopher-server**: hostname of the gopher server because gopher doesn't have… | |
-+ **gopher-port** : tcp port of the gopher server, 70 is the default port, it'… | |
+- **Makefile** | |
+ - This file exists to simplifiy the recurring execution of frequently used… | |
+- **generator.lisp** | |
+ - This is cl-yag's core library. | |
+- **static/** | |
+ - This directory holds content, that needs to be published without being c… | |
+ - If you come from 'non-static CMS'-Country: 'static/' holds, what you… | |
+- **templates/** | |
+ - The templates in this directory provide the structural skeleton(s) of th… | |
+- **output/** | |
+ - cl-yag puts in this directory everything ready to get deployed. | |
+ - Because cl-yag generates not only HTML, but gopher-compliant pages a… | |
+ - **gopher/** : contains the website for gopher, | |
+ - **html/** : contains the website in HTML. | |
-## How to add an article | |
+And there is the **data/** directory, which is important enough to get a subsu… | |
+ | |
+### The 'data/' Directory | |
+ | |
+This directory is crucial for the usage of cl-yag. | |
+ | |
+**data/** contains | |
+ | |
+- the **articles.lisp configuration file**, which defines important metadata f… | |
+- It also holds **${id}.md**-files, which are holding your posts' and pages' c… | |
+ | |
+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 we… | |
+2. A variable called **articles**. It defines local values, that - in turn - d… | |
+ | |
+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 **… | |
+- **: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 s… | |
+ - 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 w… | |
+- **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 lin… | |
+- **gopher-port** | |
+ - tcp port of the gopher server. 70 is the default port. It need to be inc… | |
+ | |
+ | |
+### The **articles** Variable | |
+ | |
+The **articles** variable holds per page/post-metadata. | |
+Of the following fields, only the *:author* and *:short* description could be … | |
+ | |
+- **:short** | |
+ - The _:short_ field's value is used for displaying a really short des… | |
+ - If _:short_ doesn't get a value, the full article gets displayed. | |
+ - Hint: Use ``:short "view the article for the full text"``, if you do… | |
+- **:id_** | |
+ - The _:id_ field holds the filename of your post/page. | |
+ - Example: ``:id "2"`` will load file ``data/2.md``. Use text instead … | |
+ - (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*… | |
+- **:tag** | |
+ - _:tag_ field is used to create a "view" containing all articles of the s… | |
+ - MIND: Whitespaces are not allowed in(!) tags. | |
+ | |
+ | |
+## Howto Create A New Post | |
-Edit data/articles.lisp and add a new line inside the *articles* variable like… | |
+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" | |
+ :id "2" | |
+ :date "29 April 2016" | |
+ :author "Solène" | |
:short "I will explain how to use the generator" | |
:tag "example help code") | |
-The _:short_ field is used on the homepage. It it is defined, this is the text… | |
+Then write a corresponding ``2.md`` file, using markdown. | |
-The _:id_ field will be part of the filename of the file and it's also the nam… | |
+## Howto Publish A Post | |
-The _:author_ field is used to display who wrote the article. You can omitt it… | |
+I prepared a Makefile to facilitate the process of generating and | |
+publishing your static sites. | |
-The _:tag_ field is used to create a page with all the articles with the same … | |
+All you need to do in order to publish is to go into your cl-yag | |
+directory and type "make". | |
-## How to publish | |
+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). | |
-There is a makefile, all you need to do is to type "make" in the folder, this … | |
-**/!\ Linux users /!\ ** you should use **bmake** (bsd make) because the Make… | |
+## Howto Add A New Page | |
-If you want to use a different lisp interpreter (default is **sbcl**), you can… | |
+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: | |
-Example with clisp : | |
+ (generate "somepage.html" (load-file "data/mypage.html")) | |
+ | |
+This will produce the file **somepage.html** in the output folder. | |
-`make LISP=clisp` | |
-This way, you can easily use a git hook to type make after each change in the … | |
+## Further Customization | |
-# Some hacks you can do | |
+### Howto Use Another Common Lisp Interpreter | |
-I tried to make it "hacking friendly", you can extend if easily. If you have a… | |
+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``. | |
-## Include some file in the template | |
+ `make LISP=ecl` | |
-Here is an example code if you want to include a page in the template | |
-+ Add a string for the replacement to occure, like %%Panel%% in **template/lay… | |
-+ In **generator.lisp** modify the function *generate-layout* to add "**(templ… | |
-+ Create **template/panel.tpl** with the html | |
+### Using git Hooks For Publishing | |
-(note : you can also directly add your text inside the layout template file in… | |
+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. | |
-## Add a new specific page | |
-You may want to have some dedicated page for some reason, reusing the website … | |
+## Page-Includes | |
-In **generate-site** function we can load a file, apply the template and save … | |
+Here is an example code, if you want to include another page in the template: | |
- (generate "somepage.html" (load-file "data/mypage.html")) | |
- | |
-This will produce the file **somepage.html** in the output folder. | |
+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 th… | |
+ | |
+3. Modify the function *generate-layout* in cl-yag's **generator.lisp** accord… | |
+ 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. | |
-# Known limitations | |
+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. | |
-## Use of ~ character | |
-The application will crash if you use a single "**~**" caracter inside one dat… | |
+# Hacking cl-yag | |
-## Article without tag | |
+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. | |
-You can have a page without a tag associated but in the default template you w… | |
+- If you are looking for a way to contribute: | |
+ - You could find a way to "sanitize" cl-yag's behaviour regarding the tild… | |
+ - Also see: 'Note' in 'Posting Without Tagging'; | |
+ - Also see: 'A Note On Themes. | |
diff --git a/data/README.md b/data/README.md | |
@@ -1,108 +1,278 @@ | |
-# Introduction | |
+# README | |
-cl-yag stands for Common Lisp Yet Another Generator and obviously it's written… | |
-**It needs a Common Lisp interpreter and a markdown-to-html export tool (like … | |
-It is regularly tested with sbcl, clisp and ecl which are free, open-source an… | |
+## Introduction | |
-**This comes with a minimalistic template**, don't expect something good looki… | |
+cl-yag is a very lightweight, 'static site'-generator that produces **gopher**… | |
+The name 'cl-yag' stands for 'Common Lisp - Yet Another website Generator'. | |
+It runs without Quicklisp. | |
-As a "demo", there is [my website](https://dataswamp.org/~solene/) using cl-ya… | |
-## The hierarchy | |
+## Showcase | |
-Here are the files and folder of cl-yag : | |
- | |
-+ **Makefile** : exists to simplify your life (updating, cleaning) | |
-+ **generator.lisp** : contains all the code of the generator | |
-+ **templates/** : contains .tpl files which are used as template for the html… | |
-+ **static/** : contains the static files like images, css, js etc... that wil… | |
-+ **data/** : | |
- + **articles.lisp** : contains metadata about the website and the list of th… | |
- + **${id}.md** : contains the article using markdown syntax that will be use… | |
-+ **output/** : | |
- + **gopher/** : contains the exported website for gopher | |
- + **html/** : contains the exported website in html | |
- | |
-# Usage | |
+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/). | |
-## Configuration | |
-In data/articles.lisp there is a ***config*** variable with the following fiel… | |
+## 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 wi… | |
+ - 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 websi… | |
+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 | |
-+ **:webmaster** : The name of the default author, this is the name used when … | |
-+ **:title** : The title of the webpage | |
-+ **:description** : This text is used in the *description* field of the Atom … | |
-+ **:url** : This is the full url of the blog with the final slash. If the url… | |
-+ **:rss-item-number** : This is the number of RSS items you want to published… | |
-+ **html** : t to export html website / nil to disable | |
-+ **gopher** : t to export gopher website / nil to disable | |
-+ **gopher-path** : this is the full path of the directory to access your goph… | |
-+ **gopher-server**: hostname of the gopher server because gopher doesn't have… | |
-+ **gopher-port** : tcp port of the gopher server, 70 is the default port, it'… | |
+- **Makefile** | |
+ - This file exists to simplifiy the recurring execution of frequently used… | |
+- **generator.lisp** | |
+ - This is cl-yag's core library. | |
+- **static/** | |
+ - This directory holds content, that needs to be published without being c… | |
+ - If you come from 'non-static CMS'-Country: 'static/' holds, what you… | |
+- **templates/** | |
+ - The templates in this directory provide the structural skeleton(s) of th… | |
+- **output/** | |
+ - cl-yag puts in this directory everything ready to get deployed. | |
+ - Because cl-yag generates not only HTML, but gopher-compliant pages a… | |
+ - **gopher/** : contains the website for gopher, | |
+ - **html/** : contains the website in HTML. | |
-## How to add an article | |
+And there is the **data/** directory, which is important enough to get a subsu… | |
+ | |
+### The 'data/' Directory | |
+ | |
+This directory is crucial for the usage of cl-yag. | |
+ | |
+**data/** contains | |
+ | |
+- the **articles.lisp configuration file**, which defines important metadata f… | |
+- It also holds **${id}.md**-files, which are holding your posts' and pages' c… | |
+ | |
+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 we… | |
+2. A variable called **articles**. It defines local values, that - in turn - d… | |
+ | |
+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 **… | |
+- **: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 s… | |
+ - 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 w… | |
+- **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 lin… | |
+- **gopher-port** | |
+ - tcp port of the gopher server. 70 is the default port. It need to be inc… | |
+ | |
+ | |
+### The **articles** Variable | |
+ | |
+The **articles** variable holds per page/post-metadata. | |
+Of the following fields, only the *:author* and *:short* description could be … | |
+ | |
+- **:short** | |
+ - The _:short_ field's value is used for displaying a really short des… | |
+ - If _:short_ doesn't get a value, the full article gets displayed. | |
+ - Hint: Use ``:short "view the article for the full text"``, if you do… | |
+- **:id_** | |
+ - The _:id_ field holds the filename of your post/page. | |
+ - Example: ``:id "2"`` will load file ``data/2.md``. Use text instead … | |
+ - (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*… | |
+- **:tag** | |
+ - _:tag_ field is used to create a "view" containing all articles of the s… | |
+ - MIND: Whitespaces are not allowed in(!) tags. | |
+ | |
+ | |
+## Howto Create A New Post | |
-Edit data/articles.lisp and add a new line inside the *articles* variable like… | |
+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" | |
+ :id "2" | |
+ :date "29 April 2016" | |
+ :author "Solène" | |
:short "I will explain how to use the generator" | |
:tag "example help code") | |
-The _:short_ field is used on the homepage. It it is defined, this is the text… | |
+Then write a corresponding ``2.md`` file, using markdown. | |
-The _:id_ field will be part of the filename of the file and it's also the nam… | |
+## Howto Publish A Post | |
-The _:author_ field is used to display who wrote the article. You can omitt it… | |
+I prepared a Makefile to facilitate the process of generating and | |
+publishing your static sites. | |
-The _:tag_ field is used to create a page with all the articles with the same … | |
+All you need to do in order to publish is to go into your cl-yag | |
+directory and type "make". | |
-## How to publish | |
+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). | |
-There is a makefile, all you need to do is to type "make" in the folder, this … | |
-**/!\ Linux users /!\ ** you should use **bmake** (bsd make) because the Make… | |
+## Howto Add A New Page | |
-If you want to use a different lisp interpreter (default is **sbcl**), you can… | |
+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: | |
-Example with clisp : | |
+ (generate "somepage.html" (load-file "data/mypage.html")) | |
+ | |
+This will produce the file **somepage.html** in the output folder. | |
-`make LISP=clisp` | |
-This way, you can easily use a git hook to type make after each change in the … | |
+## Further Customization | |
-# Some hacks you can do | |
+### Howto Use Another Common Lisp Interpreter | |
-I tried to make it "hacking friendly", you can extend if easily. If you have a… | |
+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``. | |
-## Include some file in the template | |
+ `make LISP=ecl` | |
-Here is an example code if you want to include a page in the template | |
-+ Add a string for the replacement to occure, like %%Panel%% in **template/lay… | |
-+ In **generator.lisp** modify the function *generate-layout* to add "**(templ… | |
-+ Create **template/panel.tpl** with the html | |
+### Using git Hooks For Publishing | |
-(note : you can also directly add your text inside the layout template file in… | |
+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. | |
-## Add a new specific page | |
-You may want to have some dedicated page for some reason, reusing the website … | |
+## Page-Includes | |
-In **generate-site** function we can load a file, apply the template and save … | |
+Here is an example code, if you want to include another page in the template: | |
- (generate "somepage.html" (load-file "data/mypage.html")) | |
- | |
-This will produce the file **somepage.html** in the output folder. | |
+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 th… | |
+ | |
+3. Modify the function *generate-layout* in cl-yag's **generator.lisp** accord… | |
+ 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. | |
-# Known limitations | |
+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. | |
-## Use of ~ character | |
-The application will crash if you use a single "**~**" caracter inside one dat… | |
+# Hacking cl-yag | |
-## Article without tag | |
+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. | |
-You can have a page without a tag associated but in the default template you w… | |
+- If you are looking for a way to contribute: | |
+ - You could find a way to "sanitize" cl-yag's behaviour regarding the tild… | |
+ - Also see: 'Note' in 'Posting Without Tagging'; | |
+ - Also see: 'A Note On Themes. | |
diff --git a/data/articles.lisp b/data/articles.lisp | |
@@ -33,7 +33,11 @@ | |
(defvar *articles* | |
(list | |
- (list :id "README" :date "20 May 2016" :tag "cl-yag" :title "README" :autho… | |
- (list :id "1" :date "29 April 2016":tag "pony code" :title "My first messag… | |
+ ;; README | |
+ (list :id "README" :date "23 November 2016" :tag "cl-yag README" | |
+ :title "README" :author "lambda" :short "cl-yag's README got rewo… | |
+ ;; 1 | |
+ (list :id "1" :date "29 April 2016":tag "pony code" | |
+ :title "My first message" :short "This is my first message" :author "… | |
)) | |