Add a contribution guide

README.md

@@ -2,12 +2,28 @@
 
 This repository contains a prototype for a [dnsmanager](https://github.com/KaneRoot/dnsmanager) homepage. Below, you will find instructions on how to use it and how to contribute to it.
 
-On a high-level, this website is made for [Zola](https://getzola.org) using the water.css stylesheet to decorate the semantic HTML on all pages. Currently this website does:
+On a high-level, this website is made for [Zola](https://getzola.org) using the [water.css](https://kognise.github.io/water.css/) stylesheet to decorate the semantic HTML on all pages. Currently this website does:
 
 - static pages
 - blog articles
 - internationalization (i18n) with support for localized dates
 
+The current structure is:
+
+- content/ - individual pages to be rendered (Markdown + colocated files)
+  - `blog/` - a section rendering its subchildren
+  - `blog/YYYY/` - transparent subsections per year for better browsability
+  - `blog/YYYY/foobar/` - individual blogposts (index.md), their translations (index.fr.md), and colocated assets (eg. images)
+- sass/ - where the SASS stylesheets reside
+  - `style.scss` - for customizations over raw water.css
+  - `_mobile.scss` - for mobile-specific customizations
+- static/water.css - 3rd party stylesheet for basic styles
+- templates/ - where HTML templates are
+  - index.html - the main template, that renders the index page and serves as a basis for other templates
+  - page.html - the template used for single pieces of content (static pages, blogposts)
+  - section.html - the template used for lists of content (blog, tags)
+  - widgets.html - a few macros to make everything easier
+
 # Setup
 
 If you want to contribute to this website, you first need to setup the [Zola](https://getzola.org) static site generator. You can either download a pre-compiled package, or compile the program from source using a [Rust](https://rust-lang.org) compiler.
@@ -107,28 +123,48 @@ You can then access the website at the address zola will output, usually [127.0.
 
 Note that this live reload feature does not entirely play well with the macro system at the moment, so if you see some changes in your work are not reflected on the preview, don't hesitate to kill zola using `Ctrl-c` and then start it again.
 
-# Blog
+# Contributing
 
-## Create a new article
+In this section, we explain how to get started contributing to this website. We will introduce how to edit content for the website ([edition](#edition)), how to translate the website ([translation](#translation)), and how to hack on the templates ([webdesign](#webdesign)).
 
-Create a new folder in the content/blog/YEAR/ folder. index.md is the English version, with the extension prefixed by the language code for translations.
+It is assumed you are familiar with the git ecosystem and you can submit a patch either through a pull request on the project's forge or via email to one of the maintainers. If you are not at ease with git, please ask a friend to teach you so we can cooperate and build awesome things together!
 
-Each post has some TOML metadata attached. This is called a frontmatter, and the available variables are described in the [Zola documentation](https://www.getzola.org/documentation/content/page/#front-matter):
+## Edition
+
+### Create a new page
+
+Create a new folder in the content/ folder. In this folder, place an index.md file for the English page, and one file per translation like index.fr.md (see [translating pages](#translating-pages)).
+
+Each post has some TOML metadata attached. This is called a frontmatter, and the available variables are described in the [Zola documentation](https://www.getzola.org/documentation/content/page/#front-matter). The frontmatter is mandatory although it can be empty, and should contain at least the title of the page:
 
 ```
 +++
-title = "My article"
+title = "About the project"
++++
+
+We want to decentralize everything.
+```
+
+### Create a new blog post
+
+Creating a blogpost is very similar to creating any page, but it is important that a blogpost has a `date` frontmatter key set following the format `year-month-day` like so:
+
+```
++++
+title = "Long live the Commune!"
 date = 2020-03-29
 +++
 
-My article!
+They may kill us, but they may never kill our ideas.
 ```
 
+Blogposts are organized per year to ensure the `blog/` folder does not become too bloated. So in 2020, your posts should go inside content/blog/2020/your-article/ folder.
+
 The post summary is taken from the first part of the article. If you add a `<-- more -->` tag, everything before that will be treated as the post summary.
 
-## Attach files to an article
+### Attach files to a page
 
-As previously explained, every article has its own folder. Any file you place inside that is not a Markdown file will be copied alongside the generated page. [Asset colocation](https://www.getzola.org/documentation/content/overview/#asset-colocation) is further discussed in the Zola documentation.
+As previously explained, every page has its own folder. Any file you place inside that is not a Markdown file will be copied alongside the generated page. [Asset colocation](https://www.getzola.org/documentation/content/overview/#asset-colocation) is further discussed in the Zola documentation.
 
 This means you can directly link the file from the Markdown page using a relative link:
 
@@ -142,9 +178,9 @@ title = "Hypothetical demo"
 ![Photo of Frantz Fanon](frantz_fanon.jpg)
 ```
 
-## Link another page from an article
+### Link to another page
 
-A link to another page in Markdown can use the @ sign to signify the link target is found in the content folder, as explained in the docs on [internal links](https://www.getzola.org/documentation/content/linking/#internal-links):
+A link to another page can use the @ sign to signify the link target is found in the content folder, as explained in the docs on [internal links](https://www.getzola.org/documentation/content/linking/#internal-links):
 
 ```
 +++
@@ -154,7 +190,9 @@ title = "New post"
 As explained in the [introduction](@/introduction/index.md), we should abolish the government.
 ```
 
-## Transitioning to a new year
+This allows to keep links between pages valid when their URLs change.
+
+### Transitioning to a new year
 
 If a new year is starting, you may want to create a new folder for the year and copy the placeholder section files from the past year into the new folder (one file per available language):
 
@@ -163,9 +201,9 @@ $ mkdir content/blog/2021
 $ cp content/blog/2020/_index.*.md content/blog/2021
 ```
 
-# Translations
+## Translations
 
-## Add a new language
+### Add a new language
 
 Adding a language is not hard, but it takes a few steps. The example here takes `fr` as language code for french translations, just replace it with your own language.
 
@@ -179,15 +217,103 @@ source = "Source de cette page"
 readmore = "Lire la suite"
 ```
 
-Now you can translate the Markdown pages in the content folder. The translated page should have the language code before the .md extension, like `index.fr.md`. The homepage is translated from content/_index.md, and some common parts (such as the navigation bar) are located in the content/_common folder.
+### Translating pages
 
-Warning: don't forget to copy the placeholder section file for year-folders in the blog, otherwise no article will appear on your language's blog. You can safely copy content/2020/_index.md to, say, content/2020/_index.fr.md.
+If you want to translate a page in the content folder, the translated page should have the language code before the .md extension, like `index.fr.md`. The homepage is translated from content/_index.md, and some common parts (such as the navigation bar) are located in the content/_common folder.
 
-## Use translations in the templates
+Note: don't forget to copy the section file for year-folders in the blog, otherwise no article will appear on your language's blog. You can safely copy content/2020/_index.md to, say, content/2020/_index.fr.md.
 
-### Localized string
+## Webdesign
 
-If you want to use a translation define in the translations section of the config, you can use the [trans](https://www.getzola.org/documentation/templates/overview/#trans) function, like so:
+As a webdesigner, you should look at the files in sass/ folder (for the style sources), and templates/ folder (for [tera](https://tera.netlify.com) templates.
+
+If you would like to change the `water.css` stylesheet, refer to the [water.css README](https://github.com/kognise/water.css#runtime-theming). Also, if you need to make deeper changes to water.css, please fork water.css instead of applying local changes here.
+
+### Stylesheets
+
+Apart from the upstream water.css, there are two stylesheets for the website, with `style.scss` being the main one. `_mobile.scss` is imported into style.scss, then both are rendered to style.css.
+
+The stylesheets are written in the SCSS language, which is a superset of CSS that compiles to bare CSS. [Here is](https://gist.github.com/martensonbj/d9c4ac31959e1b5a9611a9986d8f8c67) a quick introduction to SASS/SCSS styling.
+
+If you want to make changes for different viewports (such as mobile phones), please use a dedicated stylesheet. All changes for mobile-related responsiveness should live in `_mobile.scss`.
+
+### Templates
+
+The templates for Zola use the [tera](https://tera.netlify.com) template engine. If you are familiar with jinja templates, they are very similar systems.
+
+You may be looking for how to use [control structures](https://tera.netlify.com/docs/#control-structures) such as conditions, loops, macros and includes.
+
+#### Basics
+
+Using variables:
+
+```
+{# Here's how to write comments #}
+{% set variable = 2 + 2 %}
+My variable is {{ variable }}
+```
+
+Using a function:
+
+```
+<link rel="stylesheet" href="{{ get_url(path="static/water.css") }}">
+```
+
+Using a macro:
+
+```
+{% import "widgets.html" as macros %}
+The current language's index page lies in {{ macros::i18n_page(path="_index.md") }}
+```
+
+#### Structure
+
+index.html is the main template that gets rendered for everypage. It defines the current language and renders the global page skeleton accordingly. In addition, it defines a few blocks that are overriden by children templates:
+
+- title: the raw page title
+- main: the main content
+
+Both page.html and section.html extend index.html. They are children of index.html, one for rendering individual pieces of content, the other for rendering lists of content.
+
+#### Custom macros
+
+The widgets.html file contains a few useful macros. The macros related to translation/localization are documented later in the [translations in templates](#translations-in-templates) section.
+
+##### menu macro
+
+The menu macro builds a menu from a Markdown file, where each entry is separated by a thematic break. This pattern for static site generators is explained in [this article](https://staticadventures.netlib.re/blog/multi-column-layout/). The menu macro assumes that the HTML generated by every entry will have it wrapped by paragraph tags (`<p>...</p>`) and will strip that.
+
+Here's an example menu file in `content/menu.md`:
+
+```
++++
++++
+
+First entry
+
+---
+
+Second entry
+
+---
+
+Third entry
+```
+
+You can then summon this menu like this:
+
+```
+{% import 'widgets.html' as widgets %}
+{{ widgets::menu(content="menu.md") }}
+```
+
+If a `lang` variable is defined in the current context, the macro will automatically find the localized page for the menu.
+
+#### Translations in templates
+
+##### Localized string
+
+If you want to use a translation string defined in the translations section of the config, you can use the [trans](https://www.getzola.org/documentation/templates/overview/#trans) function, like so:
 
 ```
 {{ trans(key="readmore", lang=lang) }}
@@ -195,18 +321,18 @@ If you want to use a translation define in the translations section of the confi
 
 The lang variable is conveniently set for you at the top of index.html template so all templates which extend index.html should have it.
 
-### Localized path
+##### Localized path
 
-In case you need to interact with a localized page, you will need to replace the last .md with .LANG.md. There is a small macro called i18n_path for this in widgets.html. You can use it like this:
+In case you need to interact with a localized page, you will need to replace the last .md with .LANG.md. There is a widgets::i18n_path for that. You can use it like this:
 
 ```
 {% import "widgets.html" as widgets %}
 {{ widgets::i18n_path(path="@/blog/_index.md") }}
 ```
 
-It will automatically use the language code figured out in index.html.
+If the `lang` variable is set in the context, the corresponding path will be returned.
 
-### Localized page content
+##### Localized page content
 
 If you wish to directly extract the contents of a localized page, without any regards to its frontmatter, you can use the i18n_content macro:
 
@@ -215,15 +341,19 @@ If you wish to directly extract the contents of a localized page, without any re
 {{ widgets::i18n_content(path="@/blog/_index.md") }}
 ```
 
-### Localized URL
+If the `lang` variable is set in the context, the corresponding page's content will be returned.
 
-If you need to get the localized URI for path on the website, you can use the i18n_url macro which acts as a wrapper around the [get_url](https://www.getzola.org/documentation/templates/overview/#get-url) function, passing it the relevant lang context:
+##### Localized URL
+
+If you need to get the localized URI for path on the website, you can use the i18n_url macro which acts as a wrapper around the [get_url](https://www.getzola.org/documentation/templates/overview/#get-url) function:
 
 ```
 {% import "widgets.html" as widgets %}
 <a href="{{ widgets:i18n_uri(path = "rss.xml") }}">RSS</a>
 ```
 
+If the `lang` variable is set in the context, the corresponding URL will be returned.
+
 # TODO
 
 If something is missing for you, please open an issue.
@@ -238,9 +368,11 @@ If something is missing for you, please open an issue.
   - [x] other strings in the templates
   - [x] localized RSS links
   - [ ] links to navigate between languages
+  - [ ] support generic default_language (not en by default)
 - [ ] other
   - [x] ASCII banner does not overflow
   - [x] write setup/configuration guide
-  - [ ] reference water.css semantic styling
+  - [x] reference water.css semantic styling
   - [x] RSS links
-
+  - [x] hacking guides for: edition, translation, webdesign
+  - [ ] reference quickstart guide for git