commit 25c83f1ce1ad0e39f746364c88ce45fda78e4630 Solene Rapenne <solene@perso.pw> 2017-11-28 08:15:42 +0100 Fix spaces at end of line
README.md | 125 +++++++++++++++++++++++++++++++------------------------------- 1 file changed, 62 insertions(+), 63 deletions(-)
diff --git a/README.md b/README.md index 95f2cbe..4167f33 100644 --- a/README.md +++ b/README.md @@ -3,17 +3,16 @@ ## Introduction -cl-yag is a very lightweight, 'static site'-generator that produces **gopher** sites as well as **html** websites. -The name 'cl-yag' stands for 'Common Lisp - Yet Another website Generator'. +cl-yag is a very lightweight, 'static site'-generator that produces **gopher** sites as well as **html** websites. +The name 'cl-yag' stands for 'Common Lisp - Yet Another website Generator'. It runs without Quicklisp. ## Showcase I am using cl-yag to create and maintain my websites in the -world-wide-web (visit: *[Solene's -percent](https://dataswamp.org/~solene/)*) as well as [in -gopher-space](gopher://dataswamp.org/1/~solene/). +world-wide-web (visit: *[Solene'spercent](https://dataswamp.org/~solene/)*) +as well as [in gopher-space](gopher://dataswamp.org/1/~solene/). ## Requirements @@ -32,10 +31,10 @@ To use cl-yag you'll need: ## Usage -Go into your project's directory and type ``make``. You'll find your new website/gopher page in 'output/'. +Go into your project's directory and type ``make``. You'll find your new website/gopher page in 'output/'. If you want to get rid of everything in your 'output/' subdirectories, -type ``make clean``. -For further commands: read the Makefile. +type ``make clean``. +For further commands: read the Makefile. Read in the follwing section where to find it. @@ -44,28 +43,28 @@ Read in the follwing section where to find it. After cloning the repository, your project's directory should contain at least the following files and folders: - . - |-- LICENSE - |-- Makefile - |-- README.md - |-- data/ - | |-- 1.md - | |-- README.md - | `-- articles.lisp - |-- generator.lisp - |-- output/ - | |-- gopher/ - | `-- html/ - |-- static/ - | |-- css/style.css - | `-- img/ - `-- templates/ - |-- article.tpl - |-- gopher_head.tpl - |-- layout.tpl - |-- one-tag.tpl - |-- rss-item.tpl - `-- rss.tpl +. + |-- LICENSE + |-- Makefile + |-- README.md + |-- data/ + | |-- 1.md + | |-- README.md + | `-- articles.lisp + |-- generator.lisp + |-- output/ + | |-- gopher/ + | `-- html/ + |-- static/ + | |-- css/style.css + | `-- img/ + `-- templates/ + |-- article.tpl + |-- gopher_head.tpl + |-- layout.tpl + |-- one-tag.tpl + |-- rss-item.tpl + `-- rss.tpl - **Makefile** - This file exists to simplifiy the recurring execution of frequently used commands. @@ -73,14 +72,14 @@ least the following files and folders: - This is cl-yag's core library. - **static/** - This directory holds content, that needs to be published without being changed (e.g. stylesheets, js-scripts). - - If you come from 'non-static CMS'-Country: 'static/' holds, what you would put in your 'assets/' directory. + - If you come from 'non-static CMS'-Country: 'static/' holds, what you would put in your 'assets/' directory. - **templates/** - The templates in this directory provide the structural skeleton(s) of the webpages and feeds you want to create. - **output/** - cl-yag puts in this directory everything ready to get deployed. - - Because cl-yag generates not only HTML, but gopher-compliant pages as well, output/ **holds two subdirectories**. - - **gopher/** : contains the website for gopher, - - **html/** : contains the website in HTML. + - Because cl-yag generates not only HTML, but gopher-compliant pages as well, output/ **holds two subdirectories**. + - **gopher/** : contains the website for gopher, + - **html/** : contains the website in HTML. And there is the **data/** directory, which is important enough to get a subsubsection of its own. @@ -117,15 +116,15 @@ The **config** variable is used to assign the following values: - **:webmaster** - The name of the default(!) author. - - :webmaster gets used, if **:author** is omitted. (see below: 'The **articles** variable'.) + - :webmaster gets used, if **:author** is omitted. (see below: 'The **articles** variable'.) - **:title** - The title of the webpage - **:description** - This text is used in the *description* field of the Atom RSS - **:url** - This needs to be the full(!) URL of your website, including(!) a final slash. - - MIND: If the url contains a tilde (~), it needs to get duplicated - - Example: https://mydomain/~~user/ is a valid url. + - MIND: If the url contains a tilde (~), it needs to get duplicated + - Example: https://mydomain/~~user/ is a valid url. - **:rss-item-number** - This holds the number of latest(!) RSS items you want to get published when you generate the files. - **html** @@ -142,35 +141,35 @@ The **config** variable is used to assign the following values: ### The **articles** Variable -The **articles** variable holds per page/post-metadata. +The **articles** variable holds per page/post-metadata. Of the following fields, only the *:author* and *:short* description could be omitted. - **:short** - - The _:short_ field's value is used for displaying a really short description of the posts content on your homepage. - - If _:short_ doesn't get a value, the full article gets displayed. - - Hint: Use ``:short "view the article for the full text"``, if you don't want to display the full text of an article on your index site. + - The _:short_ field's value is used for displaying a really short description of the posts content on your homepage. + - If _:short_ doesn't get a value, the full article gets displayed. + - Hint: Use ``:short "view the article for the full text"``, if you don't want to display the full text of an article on your index site. - **:id_** - - The _:id_ field holds the filename of your post/page. - - Example: ``:id "2"`` will load file ``data/2.md``. Use text instead of numbers, if you want to. - - (See section: 'The **data/** Directory'.) + - The _:id_ field holds the filename of your post/page. + - Example: ``:id "2"`` will load file ``data/2.md``. Use text instead of numbers, if you want to. + - (See section: 'The **data/** Directory'.) - **:author** - The _:author_ field is used to display the article' author. - If you omit it, the generator will take the name from the **:webmaster** field of the *config* variable. - **:tag** - _:tag_ field is used to create a "view" containing all articles of the same tag. - - MIND: Whitespaces are not allowed in(!) tags. + - MIND: Whitespaces are not allowed in(!) tags. ## Howto Create A New Post - + Edit data/articles.lisp and add a new list to the *articles* variable: - (list :title "How do I use cl-yag" - :id "2" - :date "29 April 2016" - :author "Solène" - :short "I will explain how to use the generator" - :tag "example help code") + (list :title "How do I use cl-yag" + :id "2" + :date "29 April 2016" + :author "Solène" + :short "I will explain how to use the generator" + :tag "example help code") Then write a corresponding ``2.md`` file, using markdown. @@ -189,12 +188,12 @@ other directory, somewhere else on your machine). ## Howto Add A New Page -You may want to have some dedicated pages besides the index or a post. +You may want to have some dedicated pages besides the index or a post. To create one, edit the **generate-site** function in cl-yag's generator.lisp and add a function call, like this: (generate "somepage.html" (load-file "data/mypage.html")) - + This will produce the file **somepage.html** in the output folder. @@ -202,11 +201,11 @@ This will produce the file **somepage.html** in the output folder. ### Howto Use Another Common Lisp Interpreter -cl-yags default Lisp interpreter is **sbcl**. +cl-yags default Lisp interpreter is **sbcl**. If you want to use a different lisp interpreter you need to set the variable 'LISP' to the name of your binary, when calling ``make``. - `make LISP=ecl` + make LISP=ecl ### Using git Hooks For Publishing @@ -221,13 +220,13 @@ updated automatically. Here is an example code, if you want to include another page in the template: 1. Create **template/panel.tpl** with the html you want to include. -2. Add a string in the target file, where the replacement should occur. +2. Add a string in the target file, where the replacement should occur. 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 **template/layout.tpl**. -3. Modify the function *generate-layout* in cl-yag's **generator.lisp** accordingly. +3. Modify the function *generate-layout* in cl-yag's **generator.lisp** accordingly. This is done by adding the following template function call: - "**(template "%%Panel%%" (load-file "template/panel.tpl"))**" + (template "%%Panel%%" (load-file "template/panel.tpl")) (Note: You can insert your text directly into the layout template file as well.) @@ -243,7 +242,7 @@ tilde as a prefix to indicate format specifiers in format strings. In order to use a literal `~` - e.g. for creating a :title or :url reference - you have to **escape** the tilde **by duplicating** it: -``~~``. +``~~``. (See _:url_ in section 'Configuration'). @@ -262,17 +261,17 @@ focuses only on generating html- and gopher-compliant structural markup - not themed layouts. If you want some deeply refined, cross-browser compatible, responsive, -webscale style-sheet, you need to create it yourself. +webscale style-sheet, you need to create it yourself. However, cl-yag will work nicely with it and if you want to make your stylesheets a part of cl-yag you're very welcome to contact me. # Hacking cl-yag -I tried to make cl-yag easy to extend. +I tried to make cl-yag easy to extend. If you want to contribute, feel free to contact me and/or to send in a patch. - If you are looking for a way to contribute: - You could find a way to "sanitize" cl-yag's behaviour regarding the tilde (see: above); - Also see: 'Note' in 'Posting Without Tagging'; - - Also see: 'A Note On Themes. + - Also see: 'A Note On Themes.