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 (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://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/** sub directories, type ``make clean``. 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 used commands. 69 - **generator.lisp** 70 - This is cl-yag's core library. 71 - **static/** 72 - This directory holds content, that needs to be published without being changed (e.g. style sheets, js-scripts). 73 - If you come from 'non-static CMS'-Country: **static/** holds, what you would put in your **assets/** directory. 74 - **templates/** 75 - The templates in this directory provide the structural skeleton(s) of the web pages and feeds you want to create. 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 pages as well, **output/** **holds two sub directories**. 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 subsubsection of its own. 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-data for posts and pages. 91 - It also holds **${id}.md** files, which are holding your posts' (or pages') content. You can use markdown to write them. 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 below: 'The **articles** variable'.) 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 final slash. 124 - MIND: If the url contains a tilde (~), it needs to get duplicated. 125 - Example: ``https://mydomain/~~user/`` 126 - **:rss-item-number** 127 - This holds the number of latest(!) RSS items you want to get published. 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 link. 136 - **gopher-port** 137 - tcp port of the gopher server. 70 is the default port. It needs to be included in each link. 138 - **gopher-format** 139 - format of the gopher server. default is the geomyidae format, gophernicus format is commented. 140 - **gopher-index** 141 - name of the gopher menu file. default is index.gph for geomyidae, gophermap file is commented. 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 omitted. 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 ``:webmaster`` field of the *config* variable. 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 instead of numbers, if you want to. 157 - (See section: 'The **data/** Directory'.) 158 - **:tag** 159 - ``:tag`` field is used to create a "view" containing all articles of the same tag. 160 - MIND: White spaces are used to separate tags and are not allowed in(!) tags. 161 - **:tiny** 162 - The ``:tiny`` field's value is used for displaying a really short description of the posts content on your homepage. 163 - If ``:tiny`` doesn't get a value, the full article gets displayed. 164 - 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. 165 - **:title** 166 - The ``:title`` field's value sets your post's title, its first headline, as well as its entry on the index.html. 167 168 169 ## How-to Create A New Post 170 171 Edit **data/articles.lisp** and add a new list to the *articles* variable: 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 template: 227 228 1. Create **templates/panel.tpl** containing the html you want to include. 229 2. Add a replacement-string in the target file, where the replacement should occur. 230 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**. 231 232 3. Modify the function *generate-layout* in cl-yag's **generator.lisp** accordingly. 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/layout.tpl**. 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 you.) 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 patch. 277 278 - If you are looking for a way to contribute: 279 - You could find a way to "sanitize" cl-yag's behaviour regarding the tilde (see: above); 280 - Also see: 'Note' in 'Posting Without Tagging'; 281 - Also see: 'A Note On Themes'.