~data/articles.lisp Improve readability. - cl-yag - Common Lisp Yet Another website Generator
HTML git clone git://bitreich.org/cl-yag/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/cl-yag/
DIR Log
DIR Files
DIR Refs
DIR Tags
DIR README
DIR LICENSE
---
DIR commit 1c586b79e894959621e9c618a18974c2f34fa5d5
DIR parent e2d4f830fa5c7fa15180caa3f3bd58ed8c4c9dfc
HTML Author: lambda <lambda@fnord.one>
Date: Wed, 22 Nov 2017 16:26:49 +0100
~data/articles.lisp Improve readability.
+data/README.md
Cover the old lisp-application tradition and make cl-yag
self-documenting in another way: By displaying it's own README as a post. :-)
-data/2.md
Remove data/2.md
Use README as another example-entry:
Status of this commit: Suggestion
Diffstat:
D data/2.md | 1 -
A data/README.md | 108 +++++++++++++++++++++++++++++++
M data/articles.lisp | 49 ++++++++++++++++++-------------
3 files changed, 137 insertions(+), 21 deletions(-)
---
DIR diff --git a/data/2.md b/data/2.md
@@ -1 +0,0 @@
-**hello in bold**
DIR diff --git a/data/README.md b/data/README.md
@@ -0,0 +1,108 @@
+# Introduction
+
+cl-yag stands for Common Lisp Yet Another Generator and obviously it's written in Common Lisp. Currently, cl-yag can generate **gopher** and **html** website.
+
+**It needs a Common Lisp interpreter and a markdown-to-html export tool (like multimarkdown).**
+It is regularly tested with sbcl, clisp and ecl which are free, open-source and multi-platform. You don't need quicklisp library manager.
+
+**This comes with a minimalistic template**, don't expect something good looking without work. You will have to write the CSS entirely and modify the html to fit your need.
+
+As a "demo", there is [my website](https://dataswamp.org/~solene/) using cl-yag for html version, and [my gopher](gopher://perso.pw/) for gopher version.
+
+## The hierarchy
+
+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 or xml structure
++ **static/** : contains the static files like images, css, js etc... that will be published
++ **data/** :
+ + **articles.lisp** : contains metadata about the website and the list of the articles with their id/title/date/tag/*author*/*short description* (fields in *italic* are not mandatory)
+ + **${id}.md** : contains the article using markdown syntax that will be used when exported
++ **output/** :
+ + **gopher/** : contains the exported website for gopher
+ + **html/** : contains the exported website in html
+
+# Usage
+
+## Configuration
+
+In data/articles.lisp there is a ***config*** variable with the following fields :
+
++ **:webmaster** : The name of the default author, this is the name used when **:author** is omitted
++ **:title** : The title of the webpage
++ **:description** : This text is used in the *description* field of the Atom RSS
++ **:url** : This is the full url of the blog with the final slash. If the url contains a ~ it should be doubled (e.g. : https://mydomain/~~user/ is a valid url)
++ **:rss-item-number** : This is the number of RSS items you want to published when you generate the files, it will publish the last N articles
++ **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 gopher hole
++ **gopher-server**: hostname of the gopher server because gopher doesn't have relative links like html, so you need to know where you put your files
++ **gopher-port** : tcp port of the gopher server, 70 is the default port, it's included in every link as explained in gopher-server
+
+## How to add an article
+
+Edit data/articles.lisp and add a new line inside the *articles* variable like this (you can do it in one line, as you prefer)
+
+ (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")
+
+The _:short_ field is used on the homepage. It it is defined, this is the text that will be shown on the homepage with all the others articles. If it's not defined, the whole article content will be used on the homepage. Sometimes when you have long articles, you may not want to display it entirely on the index so you can use _:short "view the article for the full text_.
+
+The _:id_ field will be part of the filename of the file and it's also the name of the content on the disk. `:id "2"` will load file `data/2.txt`, you can use text instead of numbers if you want.
+
+The _:author_ field is used to display who wrote the article. You can omitt it, the generator will take the name from the *config* variable
+
+The _:tag_ field is used to create a page with all the articles with the same tag. Tags can't contain spaces.
+
+## How to publish
+
+There is a makefile, all you need to do is to type "make" in the folder, this will create the files in the **output/** location (which can be a symbolic link to somewhere else). The Gopher website will be generated inside **output/gopher** and the html will be generated in **output/html**.
+
+**/!\ Linux users /!\ ** you should use **bmake** (bsd make) because the Makefile isn't compatible with gmake (gnu make) which is the default in Linux.
+
+If you want to use a different lisp interpreter (default is **sbcl**), you can set the variable LISP to the name of your binary.
+
+Example with clisp :
+
+`make LISP=clisp`
+
+This way, you can easily use a git hook to type make after each change in the repo so your website is automatically updated.
+
+# Some hacks you can do
+
+I tried to make it "hacking friendly", you can extend if easily. If you have any idea, feel free to contact me or to send patches.
+
+## Include some file in the template
+
+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/layout.tpl** (because we want the panel on every page)
++ In **generator.lisp** modify the function *generate-layout* to add "**(template "%%Panel%%" (load-file "template/panel.tpl"))**" after one template function call
++ Create **template/panel.tpl** with the html
+
+(note : you can also directly add your text inside the layout template file instead of including another file)
+
+## Add a new specific page
+
+You may want to have some dedicated page for some reason, reusing the website layout, which is not the index nor an article.
+
+In **generate-site** function we can load a file, apply the template and save it in the output. It may look like this
+
+ (generate "somepage.html" (load-file "data/mypage.html"))
+
+This will produce the file **somepage.html** in the output folder.
+
+# Known limitations
+
+## Use of ~ character
+
+The application will crash if you use a single "**~**" caracter inside one data structure in **articles.lisp** files. This is due to the format function trying to interpret the ~ symbol while we just one a ~ symbol. This symbol in the others files are automatically replaced by ~~ which produce a single ~. So, if you want to have a "~" as a title/url/author/description/short/date you have to double it. It may be interestind to sanitize it in the tool maybe.
+
+## Article without tag
+
+You can have a page without a tag associated but in the default template you will have a line under the title which will displays "Tags : " and no tags after.
DIR diff --git a/data/articles.lisp b/data/articles.lisp
@@ -1,30 +1,39 @@
-;; WARNING caracter "~" must be escaped when used in this file
-;; you have to type ~~ for one ~ to escape it
+;; MIND: The tilde character "~" must be escaped like this '~~' to use it as a literal.
-;; define informations about your blog
-;; used for the RSS generation and some variables replacements in the layout
+;; Define Your Webpage
+
(defvar *config*
(list
- :webmaster "Your author name here"
- :title "Your blog title here"
- :description "Yet another website on the net"
- :url "https://my.website/~~user/" ;; the trailing slash is mandatory, rss links will fails without it
- :rss-item-number 10 ;; we want 10 items in our RSS feed
- :html t ;; t to export html website / nil to disable
- :gopher t ;; t to export gopher website / nil to disable
- :gopher-path "/user" ;; the absolute path of your gopher directory
- :gopher-server "my.website" ;; hostname of the gopher server
- :gopher-port "70" ;; tcp port of the gopher server, 70 usually
+ :webmaster "Your autor name here"
+ :title "Put youre website's title here."
+ :description "Yet another website on the net"
+ :url "https://my.website/~~user/" ;; the trailing slash is mandatory! RSS links will fail without it. Notice the '~~' to produce a literal '~'
+ :rss-item-number 10 ;; limit total amount of items in RSS feed to 10
+ :html t ;; 't' to enable export to a html website / 'nil' to disable
+ :gopher t ;; 't' to enable export to a gopher website / 'nil' to disable
+ :gopher-path "/user" ;; absolute path of your gopher directory
+ :gopher-server "my.website" ;; hostname of the gopher server
+ :gopher-port "70" ;; tcp port of the gopher server, 70 usually
))
-;; describes articles (ordered on the website as they are displayed here, the first in list is the top of the website)
-;; exemple => (list :id "4" :date "2015-05-04" :title "The article title" :author "Me" :tiny "Short description for home page")
-;; :author can be omitted and will be replaced by webmaster value
-;; :tiny can be omitted and will be replaced by the full article text
+
+
+
+
+;; Define your articles and their display-order on the website in *articles* below.
+;; Display Order is 'lifo', i.e. the top entry in this list gets displayed as the topmost entry.
+;;
+;; An Example Of A Minimal Definition:
+;; (list :id "4" :date "2015-05-04" :title "The article title" :author "Me" :tiny "Short description for home page")
+;;
+;; A Note On Keywords:
+;; :author can be omitted. If so, it's value gets replaced by the value of :webmaster.
+;; :tiny can be omitted. If so, the article's full text gets displayed on the all-articles view. (most people don't want this.)
+
(defvar *articles*
(list
- (list :id "2" :date "30 April 2016" :tag "lisp" :title "Another message" :short "New version available")
- (list :id "1" :date "29 April 2016":tag "pony code" :title "My first message" :short "This is my first message" :author "Solène")
+ (list :id "README" :date "20 May 2016" :tag "cl-yag" :title "README" :author "Solène" :short "cl-yag is documenting itself." :tiny "cl-yag's README")
+ (list :id "1" :date "29 April 2016":tag "pony code" :title "My first message" :short "This is my first message" :author "Solène" :tiny "Read more")
))