Table of Contents

• Files
  • Structure
  • Index
  • Comments file
• Article Syntax
  • Front Matter
  • Syntax rules
  • Main rules
  • Internal links
• Image shortcodes
• Comments
• Translations
  • Translations front matter
  • Translations internal links

Files

Each articles lives in the folder posts on Gitlab, with the following structure.

Structure

That means that each post is a folder which contains:

• the article in english (index.md) or (index.en.md)
• the translations (index.lang.md)
• the images in the article (images/)
• dithered versions of the images (images/dithers/)
• comments in various languages (comments.en.md)

Example:

how-to-build-a-low-tech-internet/
├── comments.en.md
├── images
│   ├── air-jaldi-epostman.png
│   ├── dithers
│   │   ├── air-jaldi-epostman_dithered.png
│   │   ├── freifunk-wifi-node_dithered.png
│   │   ├── node-air-jaldi-network_dithered.png
│   │   ├── node-spanish-guifi-network_dithered.png
│   │   ├── node-tegola_dithered.png
│   │   ├── sneakernet-on-rails_dithered.png
│   │   ├── tegola-project-low-tech-internet_dithered.png
│   │   ├── wifi-link_dithered.png
│   │   └── wireless-links-spanish-guifi-network_dithered.png
│   ├── freifunk-wifi-node.jpg
│   ├── node-air-jaldi-network.png
│   ├── node-spanish-guifi-network.png
│   ├── node-tegola.jpg
│   ├── sneakernet-on-rails.jpg
│   ├── tegola-project-low-tech-internet.png
│   ├── wifi-link.jpg
│   └── wireless-links-spanish-guifi-network.jpg
├── index.de.md
├── index.en.md
├── index.es.md
└── index.fr.md

To create on new article, be sure to create a new folder in posts/ with the name of the article, containing at least 1 index file and 1 images folder where your images will live.

To create an new page that isn’t an article, place the folder directly in content/ or in content/about/ for the about section.

Index

The article content should be in a file named index.lang.md. For an english article it would be index.en.md, for french translation index.fr.md, etc.

Regarding the syntax of the index files see the Syntax section below..

Comments file

The comments should now be placed in a different file in the article folder. The different comments are separated by languages and will appear in the corresponding article version. Each comments files should be named “comments.lang.md”. So for english it would be comments.en.md, for dutch comments.nl.md, etc.

The Comments will appear automatically at the end of the article, no need to add anything in the article file.

Regarding the syntax of the comments files see the Comments section below.

Syntax

The syntax of the markdown file has a few changes and additions in Hugo, which we will go over in this section. The specific changes related to Translations can be found in theTranslations section below.

Front matter data

The Front matter data at the top of each article should follow the following syntax:

---
title: "Article Title"
date: "2015-10-26"
summary: "Article Summary"
lang: "en"
authors: ["Kris De Decker" ]
categories: ["Low-tech Solutions"]
tags: ["tag", "tag2" ]
translators: [""]
featured_image: "image.png"
draft: false
---

!Do not forget the --- at the first and last line of the front matter!

• Date should use the following YYYY-MM-DD syntax.

date: "2015-10-26"

• Language should be using on the following: en (english), nl (dutch), fr (french) pl (polish), pt (portuguese), es (spanish), de (german), it (italian ), vn (vietnamese), ar (arabic), ko (korean). To add a different language translations changes in the config file are necessary.

lang: "en"

• The authors, tags and translators fields support several entry, using this syntax:

authors: ["Kris De Decker" ]
authors: ["Kris De Decker", "Roel Roscam Abbing" ]
tags: ["ICT", "transportation" ] 

• The correct spelling for categories is: "Low-tech Solutions" (Blue), "High-tech Problems" (Red), "Obsolete Technology" (Green), "About" or " " (BW)

categories: ["Low-tech Solutions"]

• The featured image will appear as a thumbnail on the category page. Make sure the image is placed inside the images/ folder. Do not include the file path, just the image with the correct extension (.png, .jpg).

featured_image: "image.png"

• draft: false is the default. Setting this to draft: true will not generate the article. It will not be visible on the site anymore, only on gitlab.

draft: false

Other metadata fields are available:

• unlisted: true : Include this field to mark the article as unlisted: it will still be accessible via the url but won’t be listed in the index page.

unlisted: true

• translators: [""] : see Translations section below

translators: [""]

Syntax Rules

The rest of of the document uses regular markdown syntax, with a few exception. Markup conventions as follows:

Main rules

• ## Big headers are h2 and render as:

(Big headers are h2)

• ### Sub-header are h3 and render as:

Sub-header are h3

• > Quotes render as:

Quotes

• * Lists / - Lists render as this list.

• Footnote references use this syntax: [^number] and render as ¹ [^number]: Footnotes appear the bottom of the document.

• [Hyperlinks](url) linking to other websites render as: Hyperlinks

Internal Links

To link to other articles on the solar website, we use a hugo specific shortcode to call the article folder. This has several advantages:

1. The url will not break if the article slug changes, since we are calling the file itself.
2. We don’t need to change the url when translating an article, it’s automatic: see translations section.

• Shortcode is written as follow and looks like this: Text.

[Text]({{< ref "/path-to-folder" /*>}})

The file path should start from within the content folder and link to the article or page folder, not the slug!

• Examples:

[Donate]({{</* ref "/donate" >}})
[low voltage DC power]({{< ref "/posts/slow-electricity-the-return-of-dc-power" >}})

• To link to a section in the article (render as: Link to section.)

[Link to Section](#section)

### Section Header{#section}

Images shortcodes

Images now use specific shortcodes instead of the classic markdown syntax. This allows t include a toggle linking to the original images and to embed the caption within the image and better control its styling.

The shortcode is written:

{{% figure src="image-1.png" %}} 
Here goes the image caption. 
You can include footnotes [^1], 
[Hyperlinks](https://solar.lowtechmagazine.com), 
and *regular* __markdown__ syntax.
{{% /figure %}}

and render as:

Comments

Comments are now added in a dedicated comments.lang.md file, as explained above. The file should start with the following lines:

---
---

Each comment is then added:

{{< comment name="Name" >}}

This is the comment text.

{{</ comment >}}

Check out the result at the bottom

Translations

To translate an article in a different language, another index.lang.md file should be created in the article folder as detailed above.

Front matter

Not all front matter should be translated, or the website might give an error.

• Front-matter that should be translated:

---
title: "Translate the title"
date: "YYYY-MM-DD" #of the translation
summary: "Translate the Article Summary"
lang: "en" #add the language code (fr, nl, etc.)
translators: ["add the translator name here", "add second (if any translator"]
---

• Front matter that shouldn’t change, no matter the language:

---
authors: ["Kris De Decker" ]
categories: ["Low-tech Solutions"]
tags: ["tag", "tag2" ]
featured_image: "image.png"
draft: false
---

Internal Links

When linking to articles on the website, the shortcode will handle directing to the correct translation automatically:

On a french article index.fr.md the link will redirect to the french donate page.

[Donate]({{< ref "/donate" >}})

Another example: this article Bring back the Horses isn’t yet available in dutch. The shortcode below in a index.nl.md file would lead to the english version, until the dutch translation is available:

[Bring back the Horses]({{< ref "/posts/bring-back-the-horses" >}})