README.md - 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
---
README.md (10205B)
---
1 # README
2
3
4 ## Introduction
5
6 cl-yag is a lightweight, static site generator that produces
7 **gopher** sites as well as **html** websites. The name 'cl-yag'
8 stands for 'Common Lisp - Yet Another website Generator'. It runs
9 without needing Quicklisp (Common LISP library manager).
10
11
12 ## Showcase
13
14 I am using cl-yag to create and maintain my websites in the
15 world-wide-web (visit: *[Solene's percent]
16 (https://dataswamp.org/~solene/)*) as well as [in gopher-space]
17 (gopher://dataswamp.org/1/~solene/).
18
19
20 ## Requirements
21
22 To use cl-yag you'll need:
23
24 1. A Common Lisp Interpreter
25 - cl-yag's current default is [Steel Bank Common Lisp (SBCL)](http://www.sbcl.org/).
26 - [Embeddable Common Lisp (ECL)](https://common-lisp.net/project/ecl/) will do fine as well.
27 2. A Markdown-to-HTML Converter
28 - cl-yag's current default is [multimarkdown](http://fletcherpenney.net/multimarkdown/).
29
30
31 ## Usage
32
33 Go into your project's directory and type ``make``. You'll find your new website/gopher page in **output/**.
34 If you want to get rid of everything in your **output/** subdirectories, type ``make clean``.
35 For further commands: read the Makefile.
36 Read in the follwing section where to find it.
37
38
39 ## Overview: cl-yag's File Hierarchy
40
41 After cloning the repository, your project's directory should contain at
42 least the following files and folders:
43
44 .
45 |-- LICENSE
46 |-- Makefile
47 |-- README.md
48 |-- data/
49 | |-- 1.md
50 | |-- README.md
51 | `-- articles.lisp
52 |-- generator.lisp
53 |-- output/
54 | |-- gemini/
55 | |-- gopher/
56 | `-- html/
57 |-- static/
58 | |-- css/style.css
59 | `-- img/
60 `-- templates/
61 |-- article.tpl
62 |-- gemini_head.tpl
63 |-- gopher_head.tpl
64 |-- layout.tpl
65 |-- one-tag.tpl
66 |-- rss-item.tpl
67 `-- rss.tpl
68
69 - **Makefile**
70 - This file exists to simplifiy the recurring execution of frequently used commands.
71 - **generator.lisp**
72 - This is cl-yag's core library.
73 - **static/**
74 - This directory holds content, that needs to be published without being changed (e.g. stylesheets, js-scripts).
75 - If you come from 'non-static CMS'-Country: **static/** holds, what you would put in your **assets/** directory.
76 - **templates/**
77 - The templates in this directory provide the structural skeleton(s) of the webpages and feeds you want to create.
78 - **output/**
79 - cl-yag puts in this directory everything ready to get deployed.
80 - Because cl-yag generates not only HTML, but gopher-compliant pages as well, **output/** **holds two subdirectories**.
81 - **gopher/** contains the website for gopher,
82 - **html/** contains the website in HTML.
83
84 And there is the **data/** directory, which is important enough to get a subsubsection of its own.
85
86 ### The data/ Directory
87
88 This directory is crucial for the usage of cl-yag.
89
90 **data/** contains
91
92 - the **articles.lisp** configuration file, which defines important metadata for posts and pages.
93 - It also holds **${id}.md** files, which are holding your posts' (or pages') content. You can use markdown to write them.
94
95 For more information: Read section 'Configuration'.
96
97
98 ## Configuration
99
100 cl-yag's main configuration file is **data/articles.lisp**.
101 In order to have a running implementation of cl-yag, you have
102 to set most of the values in this file.
103
104 **data/articles.lisp** has two parts:
105
106 1. A variable called *config*. Its values define your webpage.
107 2. "posts" declaration with their metadata
108
109 Values are assigned by placing a string (e.g. ``"foo"``) or a boolean
110 (i.e. ``t`` or ``nil``) behind a keyword (e.g. ``:title``).
111
112
113 ### The *config* Variable
114
115 The *config* variable is used to assign the following values:
116
117 - **:webmaster**
118 - The name of the default(!) author.
119 - ``:webmaster`` gets used, if ``:author`` is omitted. (See below: 'The **articles** variable'.)
120 - **:title**
121 - The title of the webpage
122 - **:description**
123 - This text is used in the *description* field of the atom/rss feed.
124 - **:url**
125 - This needs to be the full(!) URL of your website, including(!) a final slash.
126 - MIND: If the url contains a tilde (~), it needs to get duplicated.
127 - Example: ``https://mydomain/~~user/``
128 - **:rss-item-number**
129 - This holds the number of latest(!) RSS items you want to get published.
130 - **html**
131 - ``t`` to export html website. Set ``nil`` to disable.
132 - **gopher**
133 - ``t`` to export gopher website. Set ``nil`` to disable.
134 - **gemini**
135 - ``t`` to export gemini capsule. Set ``nil`` to disable.
136 - **gemini-path**
137 - This is the absolute public gemini url.
138 - **gemini-index**
139 - This is the name of the index file. Default is ``index.md``
140 - **gopher-path**
141 - This is the full path of the directory to access your gopher hole.
142 - **gopher-server**
143 - Hostname of the gopher server. It needs to be included in each link.
144 - **gopher-port**
145 - tcp port of the gopher server. 70 is the default port. It needs to be included in each link.
146 - **gopher-format**
147 - format of the gopher server. default is the geomyidae format, gophernicus format is commented.
148 - **gopher-index**
149 - name of the gopher menu file. defaut is index.gph for geomyidae, gophermap file is commented.
150
151
152 ### Posts declarations
153
154 Each post is declared with its metadata using the function "post".
155 So you need to add a new line for each of your posts.
156
157 Of the following keywords, only ``:author`` and ``:short`` can be omitted.
158
159 - **:author**
160 - The ``:author`` field is used to display the article's author.
161 - If you omit it, the generator will take the name from the ``:webmaster`` field of the *config* variable.
162 - **:id**
163 - The ``:id`` field holds the filename of your post/page.
164 - Example: ``:id "2"`` will load file **data/2.md**. Use text instead of numbers, if you want to.
165 - (See section: 'The **data/** Directory'.)
166 - **:tag**
167 - ``:tag`` field is used to create a "view" containing all articles of the same tag.
168 - MIND: Whitespaces are used to separate tags and are not allowed in(!) tags.
169 - **:tiny**
170 - The ``:tiny`` field's value is used for displaying a really short description of the posts content on your homepage.
171 - If ``:tiny`` doesn't get a value, the full article gets displayed.
172 - 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.
173 - **:title**
174 - The ``:title`` field's value sets your post's title, its first headline, as well as its entry on the index.html.
175
176
177 ## Howto Create A New Post
178
179 Edit **data/articles.lisp** and add a new list to the *articles* variable:
180
181 (list :title "How do I use cl-yag"
182 :id "2"
183 :date "29 April 2016"
184 :author "Solène"
185 :tiny "Read more about how I use cl-yag."
186 :tag "example help code")
187
188 Then write a corresponding **data/2.md** file, using markdown.
189
190
191 ## Howto Publish A Post
192
193 I prepared a Makefile to facilitate the process of generating and
194 publishing your static sites.
195 All you need to do in order to publish is to go into your cl-yag
196 directory and type ``make``.
197
198 The make command creates html, gemini and gopher files in the defined
199 location. The default is the **output/** directory, but you can use a
200 symbolic link pointing to some other directory as well.
201
202
203 ## Howto Add A New Page
204
205 You may want to have some dedicated pages besides the index or a post.
206 To create one, edit the *generate-site* function in cl-yag's
207 **generator.lisp** and add a function call, like this:
208
209 (generate "somepage.html" (load-file "data/mypage.html"))
210
211 This will produce **output/html/somepage.html**.
212
213
214 ## Further Customization
215
216 ### Howto Use Another Common Lisp Interpreter
217
218 cl-yags default Lisp interpreter is **sbcl**. If you want to use a
219 different interpreter you need to set the variable *LISP* to the name
220 of your binary, when calling ``make``:
221
222 make LISP=ecl
223
224
225 ### Using git Hooks For Publishing
226
227 You may customize your publishing-process further, e.g. by using a git
228 hook to call the make program after each change in the repo so your
229 website gets updated automatically.
230
231
232 ## Page-Includes
233
234 Here is an example code, if you want to include another page in the template:
235
236 1. Create **templates/panel.tpl** containing the html you want to include.
237 2. Add a replacement-string in the target file, where the replacement should occur.
238 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**.
239
240 3. Modify the function *generate-layout* in cl-yag's **generator.lisp** accordingly.
241 This is done by adding the following template function call:
242
243 (template "%%Panel%%" (load-file "templates/panel.tpl"))
244
245 Another valid approach is to writer your html directly into **templates/layout.tpl**.
246
247 ## Known Limitations
248
249 ### Use ~~ To Create ~
250
251 cl-yag crashes if you use a single "~" character inside
252 **templates/articles.lisp**, because Common Lisp employs the tilde as a
253 prefix to indicate format specifiers in format strings.
254
255 In order to use a literal `~` -- e.g. for creating a ``:title`` or
256 ``:url`` reference -- you have to *escape* the tilde *by
257 duplicating* it: ``~~``. (See ``:url`` in section 'Configuration').
258
259
260 ### Posting Without Tagging
261
262 cl-yag allows posts without tags, but, using the default
263 **templates/layout.tpl**, you'll get a line below your title that
264 displays: "Tags: ".
265
266 (Note: If you are looking for a way to contribute this may be a task for you.)
267
268
269 ### A Note On Themes
270
271 Although cl-yag may ship with a minimalistic template, cl-yag focuses
272 on generating html-, gemini and gopher-compliant structural markup -
273 not themed layouts.
274
275 If you want some deeply refined, cross-browser compatible, responsive,
276 webscale style sheets, you need to create them yourself. However,
277 cl-yag will work nicely with them and if you want to make your
278 style sheets a part of cl-yag you're very welcome to contact me.
279
280
281 # Hacking cl-yag
282
283 I tried to make cl-yag easy to extend.
284 If you want to contribute, feel free to contact me and/or to send in a patch.
285
286 - If you are looking for a way to contribute:
287 - You could find a way to "sanitize" cl-yag's behaviour regarding the tilde (see: above);
288 - Also see: 'Note' in 'Posting Without Tagging';
289 - Also see: 'A Note On Themes'.