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