|
|
README.md - cl-yag - Common Lisp Yet Another website Generator |
|
|
 |
git clone git://bitreich.org/cl-yag/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/cl-yag/ (git://bitreich.org) |
|
|
 |
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://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'. |
|