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 (9936B)
---
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/** sub directories…
35 For further commands: read the Makefile.
36 Read in the following 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 | |-- gopher/
55 | `-- html/
56 |-- static/
57 | |-- css/style.css
58 | `-- img/
59 `-- templates/
60 |-- article.tpl
61 |-- gopher_head.tpl
62 |-- layout.tpl
63 |-- one-tag.tpl
64 |-- rss-item.tpl
65 `-- rss.tpl
66
67 - **Makefile**
68 - This file exists to simplify the recurring execution of frequently…
69 - **generator.lisp**
70 - This is cl-yag's core library.
71 - **static/**
72 - This directory holds content, that needs to be published without b…
73 - If you come from 'non-static CMS'-Country: **static/** holds, …
74 - **templates/**
75 - The templates in this directory provide the structural skeleton(s)…
76 - **output/**
77 - cl-yag puts in this directory everything ready to get deployed.
78 - Because cl-yag generates not only HTML, but gopher-compliant p…
79 - **gopher/** contains the website for gopher,
80 - **html/** contains the website in HTML.
81
82 And there is the **data/** directory, which is important enough to get a…
83
84 ### The data/ Directory
85
86 This directory is crucial for the usage of cl-yag.
87
88 **data/** contains
89
90 - the **articles.lisp** configuration file, which defines important meta…
91 - It also holds **${id}.md** files, which are holding your posts' (or pa…
92
93 For more information: Read section 'Configuration'.
94
95
96 ## Configuration
97
98 cl-yag's main configuration file is **data/articles.lisp**.
99 In order to have a running implementation of cl-yag, you have
100 to set most of the values in this file.
101
102 **data/articles.lisp** has two parts:
103
104 1. A variable called *config*. Its values define your web page.
105 2. "posts" declaration with their meta-data
106
107 Values are assigned by placing a string (e.g. ``"foo"``) or a boolean
108 (i.e. ``t`` or ``nil``) behind a keyword (e.g. ``:title``).
109
110
111 ### The *config* Variable
112
113 The *config* variable is used to assign the following values:
114
115 - **:webmaster**
116 - The name of the default(!) author.
117 - ``:webmaster`` gets used, if ``:author`` is omitted. (See belo…
118 - **:title**
119 - The title of the web-page
120 - **:description**
121 - This text is used in the *description* field of the atom/rss feed.
122 - **:url**
123 - This needs to be the full(!) URL of your website, including(!) a f…
124 - MIND: If the url contains a tilde (~), it needs to get duplica…
125 - Example: ``https://mydomain/~~user/``
126 - **:rss-item-number**
127 - This holds the number of latest(!) RSS items you want to get publi…
128 - **html**
129 - ``t`` to export html website. Set ``nil`` to disable.
130 - **gopher**
131 - ``t`` to export gopher website. Set ``nil`` to disable.
132 - **gopher-path**
133 - This is the full path of the directory to access your gopher hole.
134 - **gopher-server**
135 - Hostname of the gopher server. It needs to be included in each lin…
136 - **gopher-port**
137 - tcp port of the gopher server. 70 is the default port. It needs to…
138 - **gopher-format**
139 - format of the gopher server. default is the geomyidae format, goph…
140 - **gopher-index**
141 - name of the gopher menu file. default is index.gph for geomyidae, …
142
143
144 ### Posts declarations
145
146 Each post is declared with its meta-data using the function "post".
147 So you need to add a new line for each of your posts.
148
149 Of the following keywords, only ``:author`` and ``:short`` can be omitte…
150
151 - **:author**
152 - The ``:author`` field is used to display the article's author.
153 - If you omit it, the generator will take the name from the ``:webma…
154 - **:id**
155 - The ``:id`` field holds the file name of your post/page.
156 - Example: ``:id "2"`` will load file **data/2.md**. Use text in…
157 - (See section: 'The **data/** Directory'.)
158 - **:tag**
159 - ``:tag`` field is used to create a "view" containing all articles …
160 - MIND: White spaces are used to separate tags and are not allo…
161 - **:tiny**
162 - The ``:tiny`` field's value is used for displaying a really sh…
163 - If ``:tiny`` doesn't get a value, the full article gets displa…
164 - Hint: Use ``:tiny "Read the full article for more information.…
165 - **:title**
166 - The ``:title`` field's value sets your post's title, its first…
167
168
169 ## How-to Create A New Post
170
171 Edit **data/articles.lisp** and add a new list to the *articles* variabl…
172
173 (list :title "How do I use cl-yag"
174 :id "2"
175 :date "29 April 2016"
176 :author "Solène"
177 :tiny "Read more about how I use cl-yag."
178 :tag "example help code")
179
180 Then write a corresponding **data/2.md** file, using markdown.
181
182
183 ## How-to Publish A Post
184
185 I prepared a Makefile to facilitate the process of generating and
186 publishing your static sites.
187 All you need to do in order to publish is to go into your cl-yag
188 directory and type ``make``.
189
190 The make command creates html and gopher files in the defined location.
191 The default is the **output/** directory, but you can use a symbolic link
192 pointing to some other directory as well.
193
194
195 ## How-to Add A New Page
196
197 You may want to have some dedicated pages besides the index or a post.
198 To create one, edit the *generate-site* function in cl-yag's
199 **generator.lisp** and add a function call, like this:
200
201 (generate "somepage.html" (load-file "data/mypage.html"))
202
203 This will produce **output/html/somepage.html**.
204
205
206 ## Further Customization
207
208 ### How-to Use Another Common Lisp Interpreter
209
210 cl-yags default Lisp interpreter is **sbcl**. If you want to use a
211 different interpreter you need to set the variable *LISP* to the name
212 of your binary, when calling ``make``:
213
214 make LISP=ecl
215
216
217 ### Using git Hooks For Publishing
218
219 You may customize your publishing-process further, e.g. by using a git
220 hook to call the make program after each change in the repo so your
221 website gets updated automatically.
222
223
224 ## Page-Includes
225
226 Here is an example code, if you want to include another page in the temp…
227
228 1. Create **templates/panel.tpl** containing the html you want to includ…
229 2. Add a replacement-string in the target file, where the replacement sh…
230 In this case, we choose **%%Panel%%** for a string, and, because we w…
231
232 3. Modify the function *generate-layout* in cl-yag's **generator.lisp** …
233 This is done by adding the following template function call:
234
235 (template "%%Panel%%" (load-file "templates/panel.tpl"))
236
237 Another valid approach is to writer your html directly into **templates/…
238
239 ## Known Limitations
240
241 ### Use ~~ To Create ~
242
243 cl-yag crashes if you use a single "~" character inside
244 **templates/articles.lisp**, because Common Lisp employs the tilde as a
245 prefix to indicate format specifiers in format strings.
246
247 In order to use a literal `~` -- e.g. for creating a ``:title`` or
248 ``:url`` reference -- you have to *escape* the tilde *by
249 duplicating* it: ``~~``. (See ``:url`` in section 'Configuration').
250
251
252 ### Posting Without Tagging
253
254 cl-yag allows posts without tags, but, using the default
255 **templates/layout.tpl**, you'll get a line below your title that
256 displays: "Tags: ".
257
258 (Note: If you are looking for a way to contribute this may be a task for…
259
260
261 ### A Note On Themes
262
263 Although cl-yag may ship with a minimalist template, cl-yag focuses
264 on generating html- and gopher-compliant structural markup - not
265 themed layouts.
266
267 If you want some deeply refined, cross-browser compatible, responsive,
268 webscale style sheets, you need to create them yourself. However,
269 cl-yag will work nicely with them and if you want to make your
270 style sheets a part of cl-yag you're very welcome to contact me.
271
272
273 # Hacking cl-yag
274
275 I tried to make cl-yag easy to extend.
276 If you want to contribute, feel free to contact me and/or to send in a p…
277
278 - If you are looking for a way to contribute:
279 - You could find a way to "sanitize" cl-yag's behaviour regarding th…
280 - Also see: 'Note' in 'Posting Without Tagging';
281 - 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.