git/cl-yag/commit/9f06b3331dbd17c1be1c8cfcb255d62202cf8b2a.html (16402 bytes)
1 <!DOCTYPE html> 2 <html lang="en"><head><meta charset="UTF-8" /> 3 <meta name="viewport" content="width=device-width, initial-scale=1" /> 4 <title>cl-yag 9f06b333 - Recently Written</title> 5 <link rel="stylesheet" href="../../stagit.css" /> 6 </head><body> 7 <div id="top"><a href="../../../index.html">Recently Written</a> · <a href="../../index.html">git</a></div> 8 <h1>cl-yag</h1><span class="desc">Mirror and rewrite of Solène Rapenne's cl-yag SSG of renown</span><p class="url">git clone https://github.com/equwal/cl-yag</p><p><a href="../../cl-yag/index.html">Log</a> | <a href="../../cl-yag/files.html">Files</a> | <a href="../../cl-yag/refs.html">Refs</a></p><hr/> 9 <div id="content"> 10 <pre>commit 9f06b3331dbd17c1be1c8cfcb255d62202cf8b2a 11 lambda <lambda@fnord.one> 12 2017-11-22 16:26:49 +0100 13 14 ~data/articles.lisp 15 Improve readability. 16 17 +data/README.md 18 Cover the old lisp-application tradition and make cl-yag 19 self-documenting in another way: By displaying it's own README as a post. :-) 20 21 -data/2.md 22 Remove data/2.md 23 Use README as another example-entry: 24 25 Status of this commit: Suggestion 26 27 </pre><pre> data/2.md | 1 - 28 data/README.md | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 29 data/articles.lisp | 49 ++++++++++++++---------- 30 3 files changed, 137 insertions(+), 21 deletions(-) 31 </pre><pre>diff --git a/data/2.md b/data/2.md 32 deleted file mode 100644 33 index 917bbde..0000000 34 --- a/data/2.md 35 +++ /dev/null 36 <span class="h">@@ -1 +0,0 @@</span> 37 <span class="d">-**hello in bold**</span> 38 diff --git a/data/README.md b/data/README.md 39 new file mode 100644 40 index 0000000..287a641 41 --- /dev/null 42 +++ b/data/README.md 43 <span class="h">@@ -0,0 +1,108 @@</span> 44 <span class="a">+# Introduction</span> 45 <span class="a">+</span> 46 <span class="a">+cl-yag stands for Common Lisp Yet Another Generator and obviously it's written in Common Lisp. Currently, cl-yag can generate **gopher** and **html** website.</span> 47 <span class="a">+</span> 48 <span class="a">+**It needs a Common Lisp interpreter and a markdown-to-html export tool (like multimarkdown).**</span> 49 <span class="a">+It is regularly tested with sbcl, clisp and ecl which are free, open-source and multi-platform. You don't need quicklisp library manager.</span> 50 <span class="a">+</span> 51 <span class="a">+**This comes with a minimalistic template**, don't expect something good looking without work. You will have to write the CSS entirely and modify the html to fit your need.</span> 52 <span class="a">+</span> 53 <span class="a">+As a "demo", there is [my website](https://dataswamp.org/~solene/) using cl-yag for html version, and [my gopher](gopher://perso.pw/) for gopher version.</span> 54 <span class="a">+</span> 55 <span class="a">+## The hierarchy</span> 56 <span class="a">+</span> 57 <span class="a">+Here are the files and folder of cl-yag :</span> 58 <span class="a">+ </span> 59 <span class="a">++ **Makefile** : exists to simplify your life (updating, cleaning) </span> 60 <span class="a">++ **generator.lisp** : contains all the code of the generator</span> 61 <span class="a">++ **templates/** : contains .tpl files which are used as template for the html or xml structure </span> 62 <span class="a">++ **static/** : contains the static files like images, css, js etc... that will be published</span> 63 <span class="a">++ **data/** : </span> 64 <span class="a">+ + **articles.lisp** : contains metadata about the website and the list of the articles with their id/title/date/tag/*author*/*short description* (fields in *italic* are not mandatory)</span> 65 <span class="a">+ + **${id}.md** : contains the article using markdown syntax that will be used when exported</span> 66 <span class="a">++ **output/** :</span> 67 <span class="a">+ + **gopher/** : contains the exported website for gopher</span> 68 <span class="a">+ + **html/** : contains the exported website in html</span> 69 <span class="a">+</span> 70 <span class="a">+# Usage</span> 71 <span class="a">+</span> 72 <span class="a">+## Configuration</span> 73 <span class="a">+</span> 74 <span class="a">+In data/articles.lisp there is a ***config*** variable with the following fields :</span> 75 <span class="a">+</span> 76 <span class="a">++ **:webmaster** : The name of the default author, this is the name used when **:author** is omitted</span> 77 <span class="a">++ **:title** : The title of the webpage</span> 78 <span class="a">++ **:description** : This text is used in the *description* field of the Atom RSS</span> 79 <span class="a">++ **:url** : This is the full url of the blog with the final slash. If the url contains a ~ it should be doubled (e.g. : https://mydomain/~~user/ is a valid url)</span> 80 <span class="a">++ **:rss-item-number** : This is the number of RSS items you want to published when you generate the files, it will publish the last N articles</span> 81 <span class="a">++ **html** : t to export html website / nil to disable</span> 82 <span class="a">++ **gopher** : t to export gopher website / nil to disable</span> 83 <span class="a">++ **gopher-path** : this is the full path of the directory to access your gopher hole</span> 84 <span class="a">++ **gopher-server**: hostname of the gopher server because gopher doesn't have relative links like html, so you need to know where you put your files</span> 85 <span class="a">++ **gopher-port** : tcp port of the gopher server, 70 is the default port, it's included in every link as explained in gopher-server</span> 86 <span class="a">+</span> 87 <span class="a">+## How to add an article</span> 88 <span class="a">+ </span> 89 <span class="a">+Edit data/articles.lisp and add a new line inside the *articles* variable like this (you can do it in one line, as you prefer)</span> 90 <span class="a">+</span> 91 <span class="a">+ (list :title "How do I use cl-yag" </span> 92 <span class="a">+ :id "2" :date "29 April 2016" </span> 93 <span class="a">+ :author "Solène" </span> 94 <span class="a">+ :short "I will explain how to use the generator" </span> 95 <span class="a">+ :tag "example help code")</span> 96 <span class="a">+</span> 97 <span class="a">+The _:short_ field is used on the homepage. It it is defined, this is the text that will be shown on the homepage with all the others articles. If it's not defined, the whole article content will be used on the homepage. Sometimes when you have long articles, you may not want to display it entirely on the index so you can use _:short "view the article for the full text_.</span> 98 <span class="a">+</span> 99 <span class="a">+The _:id_ field will be part of the filename of the file and it's also the name of the content on the disk. `:id "2"` will load file `data/2.txt`, you can use text instead of numbers if you want.</span> 100 <span class="a">+</span> 101 <span class="a">+The _:author_ field is used to display who wrote the article. You can omitt it, the generator will take the name from the *config* variable</span> 102 <span class="a">+</span> 103 <span class="a">+The _:tag_ field is used to create a page with all the articles with the same tag. Tags can't contain spaces.</span> 104 <span class="a">+</span> 105 <span class="a">+## How to publish</span> 106 <span class="a">+</span> 107 <span class="a">+There is a makefile, all you need to do is to type "make" in the folder, this will create the files in the **output/** location (which can be a symbolic link to somewhere else). The Gopher website will be generated inside **output/gopher** and the html will be generated in **output/html**.</span> 108 <span class="a">+</span> 109 <span class="a">+**/!\ Linux users /!\ ** you should use **bmake** (bsd make) because the Makefile isn't compatible with gmake (gnu make) which is the default in Linux.</span> 110 <span class="a">+</span> 111 <span class="a">+If you want to use a different lisp interpreter (default is **sbcl**), you can set the variable LISP to the name of your binary. </span> 112 <span class="a">+</span> 113 <span class="a">+Example with clisp : </span> 114 <span class="a">+</span> 115 <span class="a">+`make LISP=clisp`</span> 116 <span class="a">+</span> 117 <span class="a">+This way, you can easily use a git hook to type make after each change in the repo so your website is automatically updated.</span> 118 <span class="a">+</span> 119 <span class="a">+# Some hacks you can do</span> 120 <span class="a">+</span> 121 <span class="a">+I tried to make it "hacking friendly", you can extend if easily. If you have any idea, feel free to contact me or to send patches.</span> 122 <span class="a">+</span> 123 <span class="a">+## Include some file in the template</span> 124 <span class="a">+</span> 125 <span class="a">+Here is an example code if you want to include a page in the template</span> 126 <span class="a">+</span> 127 <span class="a">++ Add a string for the replacement to occure, like %%Panel%% in **template/layout.tpl** (because we want the panel on every page)</span> 128 <span class="a">++ In **generator.lisp** modify the function *generate-layout* to add "**(template "%%Panel%%" (load-file "template/panel.tpl"))**" after one template function call</span> 129 <span class="a">++ Create **template/panel.tpl** with the html</span> 130 <span class="a">+</span> 131 <span class="a">+(note : you can also directly add your text inside the layout template file instead of including another file)</span> 132 <span class="a">+</span> 133 <span class="a">+## Add a new specific page</span> 134 <span class="a">+</span> 135 <span class="a">+You may want to have some dedicated page for some reason, reusing the website layout, which is not the index nor an article.</span> 136 <span class="a">+</span> 137 <span class="a">+In **generate-site** function we can load a file, apply the template and save it in the output. It may look like this</span> 138 <span class="a">+</span> 139 <span class="a">+ (generate "somepage.html" (load-file "data/mypage.html"))</span> 140 <span class="a">+ </span> 141 <span class="a">+This will produce the file **somepage.html** in the output folder.</span> 142 <span class="a">+</span> 143 <span class="a">+# Known limitations</span> 144 <span class="a">+</span> 145 <span class="a">+## Use of ~ character</span> 146 <span class="a">+</span> 147 <span class="a">+The application will crash if you use a single "**~**" caracter inside one data structure in **articles.lisp** files. This is due to the format function trying to interpret the ~ symbol while we just one a ~ symbol. This symbol in the others files are automatically replaced by ~~ which produce a single ~. So, if you want to have a "~" as a title/url/author/description/short/date you have to double it. It may be interestind to sanitize it in the tool maybe.</span> 148 <span class="a">+</span> 149 <span class="a">+## Article without tag</span> 150 <span class="a">+</span> 151 <span class="a">+You can have a page without a tag associated but in the default template you will have a line under the title which will displays "Tags : " and no tags after.</span> 152 diff --git a/data/articles.lisp b/data/articles.lisp 153 index 31a3311..1b9c2cb 100644 154 --- a/data/articles.lisp 155 +++ b/data/articles.lisp 156 <span class="h">@@ -1,30 +1,39 @@</span> 157 <span class="d">-;; WARNING caracter "~" must be escaped when used in this file</span> 158 <span class="d">-;; you have to type ~~ for one ~ to escape it</span> 159 <span class="a">+;; MIND: The tilde character "~" must be escaped like this '~~' to use it as a literal.</span> 160 161 162 <span class="d">-;; define informations about your blog</span> 163 <span class="d">-;; used for the RSS generation and some variables replacements in the layout</span> 164 <span class="a">+;; Define Your Webpage</span> 165 <span class="a">+</span> 166 (defvar *config* 167 (list 168 <span class="d">- :webmaster "Your author name here"</span> 169 <span class="d">- :title "Your blog title here"</span> 170 <span class="d">- :description "Yet another website on the net"</span> 171 <span class="d">- :url "https://my.website/~~user/" ;; the trailing slash is mandatory, rss links will fails without it</span> 172 <span class="d">- :rss-item-number 10 ;; we want 10 items in our RSS feed</span> 173 <span class="d">- :html t ;; t to export html website / nil to disable</span> 174 <span class="d">- :gopher t ;; t to export gopher website / nil to disable</span> 175 <span class="d">- :gopher-path "/user" ;; the absolute path of your gopher directory</span> 176 <span class="d">- :gopher-server "my.website" ;; hostname of the gopher server</span> 177 <span class="d">- :gopher-port "70" ;; tcp port of the gopher server, 70 usually</span> 178 <span class="a">+ :webmaster "Your autor name here"</span> 179 <span class="a">+ :title "Put youre website's title here."</span> 180 <span class="a">+ :description "Yet another website on the net"</span> 181 <span class="a">+ :url "https://my.website/~~user/" ;; the trailing slash is mandatory! RSS links will fail without it. Notice the '~~' to produce a literal '~'</span> 182 <span class="a">+ :rss-item-number 10 ;; limit total amount of items in RSS feed to 10</span> 183 <span class="a">+ :html t ;; 't' to enable export to a html website / 'nil' to disable</span> 184 <span class="a">+ :gopher t ;; 't' to enable export to a gopher website / 'nil' to disable</span> 185 <span class="a">+ :gopher-path "/user" ;; absolute path of your gopher directory</span> 186 <span class="a">+ :gopher-server "my.website" ;; hostname of the gopher server</span> 187 <span class="a">+ :gopher-port "70" ;; tcp port of the gopher server, 70 usually</span> 188 )) 189 190 <span class="d">-;; describes articles (ordered on the website as they are displayed here, the first in list is the top of the website)</span> 191 <span class="d">-;; exemple => (list :id "4" :date "2015-05-04" :title "The article title" :author "Me" :tiny "Short description for home page")</span> 192 <span class="d">-;; :author can be omitted and will be replaced by webmaster value</span> 193 <span class="d">-;; :tiny can be omitted and will be replaced by the full article text</span> 194 <span class="a">+</span> 195 <span class="a">+</span> 196 <span class="a">+</span> 197 <span class="a">+</span> 198 <span class="a">+;; Define your articles and their display-order on the website in *articles* below.</span> 199 <span class="a">+;; Display Order is 'lifo', i.e. the top entry in this list gets displayed as the topmost entry.</span> 200 <span class="a">+;; </span> 201 <span class="a">+;; An Example Of A Minimal Definition:</span> 202 <span class="a">+;; (list :id "4" :date "2015-05-04" :title "The article title" :author "Me" :tiny "Short description for home page")</span> 203 <span class="a">+;;</span> 204 <span class="a">+;; A Note On Keywords:</span> 205 <span class="a">+;; :author can be omitted. If so, it's value gets replaced by the value of :webmaster.</span> 206 <span class="a">+;; :tiny can be omitted. If so, the article's full text gets displayed on the all-articles view. (most people don't want this.)</span> 207 <span class="a">+</span> 208 (defvar *articles* 209 (list 210 <span class="d">- (list :id "2" :date "30 April 2016" :tag "lisp" :title "Another message" :short "New version available") </span> 211 <span class="d">- (list :id "1" :date "29 April 2016":tag "pony code" :title "My first message" :short "This is my first message" :author "Solène")</span> 212 <span class="a">+ (list :id "README" :date "20 May 2016" :tag "cl-yag" :title "README" :author "Solène" :short "cl-yag is documenting itself." :tiny "cl-yag's README")</span> 213 <span class="a">+ (list :id "1" :date "29 April 2016":tag "pony code" :title "My first message" :short "This is my first message" :author "Solène" :tiny "Read more")</span> 214 )) 215 </pre> 216 </div></body></html>