Introduction
Introduction Statistics Contact Development Disclaimer Help
README.md - cl-yag - Common Lisp Yet Another website Generator
git clone git://bitreich.org/cl-yag/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws…
Log
Files
Refs
Tags
README
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:/…
26 - [Embeddable Common Lisp (ECL)](https://common-lisp.net/project/ecl…
27 2. A Markdown-to-HTML Converter
28 - cl-yag's current default is [multimarkdown](http://fletcherpenney.…
29
30
31 ## Usage
32
33 Go into your project's directory and type ``make``. You'll find your new…
34 If you want to get rid of everything in your **output/** subdirectories,…
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 frequentl…
71 - **generator.lisp**
72 - This is cl-yag's core library.
73 - **static/**
74 - This directory holds content, that needs to be published without b…
75 - If you come from 'non-static CMS'-Country: **static/** holds, …
76 - **templates/**
77 - The templates in this directory provide the structural skeleton(s)…
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 p…
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…
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 meta…
93 - It also holds **${id}.md** files, which are holding your posts' (or pa…
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 belo…
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 f…
126 - MIND: If the url contains a tilde (~), it needs to get duplica…
127 - Example: ``https://mydomain/~~user/``
128 - **:rss-item-number**
129 - This holds the number of latest(!) RSS items you want to get publi…
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 lin…
144 - **gopher-port**
145 - tcp port of the gopher server. 70 is the default port. It needs to…
146 - **gopher-format**
147 - format of the gopher server. default is the geomyidae format, goph…
148 - **gopher-index**
149 - name of the gopher menu file. defaut is index.gph for geomyidae, g…
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 omitte…
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 ``:webma…
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 in…
165 - (See section: 'The **data/** Directory'.)
166 - **:tag**
167 - ``:tag`` field is used to create a "view" containing all articles …
168 - MIND: Whitespaces are used to separate tags and are not allow…
169 - **:tiny**
170 - The ``:tiny`` field's value is used for displaying a really sh…
171 - If ``:tiny`` doesn't get a value, the full article gets displa…
172 - Hint: Use ``:tiny "Read the full article for more information.…
173 - **:title**
174 - The ``:title`` field's value sets your post's title, its first…
175
176
177 ## Howto Create A New Post
178
179 Edit **data/articles.lisp** and add a new list to the *articles* variabl…
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 temp…
235
236 1. Create **templates/panel.tpl** containing the html you want to includ…
237 2. Add a replacement-string in the target file, where the replacement sh…
238 In this case, we choose **%%Panel%%** for a string, and, because we w…
239
240 3. Modify the function *generate-layout* in cl-yag's **generator.lisp** …
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/…
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…
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 p…
285
286 - If you are looking for a way to contribute:
287 - You could find a way to "sanitize" cl-yag's behaviour regarding th…
288 - Also see: 'Note' in 'Posting Without Tagging';
289 - Also see: 'A Note On Themes'.
You are viewing proxied material from bitreich.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.