Article Template: How to write articles and translations in Markdown for Hugo?

A screenshot of the markdown file for this page.
View original image View dithered image

This page is intented for internal use only.

Files
Article Syntax
Image shortcodes
Comments
Translations

Files

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

Structure

Each post/article 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

Folder Name

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
1 comments file (see below)
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.

By default, your folder name is the article slug. The slug should match the title, but with the following rules. Use "-"instead of " " spaces and don’t include special character (no ,=;/%?! &.@ etc.)

/posts/my-article-name/index.en.md

will become:

https://solar.lowtechmagazine.com/YYYY/MM/my-article-name/

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.

Output

The folder should look like this at start:

my-article-name/
├── comments.en.md
├── images/ 
│   └── images goes here. 
└── index.lang.md

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
audioversion: "url"
_build:
  list: never
---

!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

Always include at least: title: "", date: "", summary: "Article Summary", lang: "en"

Other metadata fields are available:

slug: "" : By default, the slug is the filename but you can overwrite this by adding a slug.

slug: "this-is-a-slug"

_build: list: never : 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.

_build:
  list: never

translators: [""] : see Translations section below

translators: [""]

audioversion : Append here the link (url) to the audio version, if needed.

audioversion: "https://youtube.com/link-to-audio-version"

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 ¹
Footnotes appear the bottom of the document. The syntax is [^1]: text

[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:

The url will not break if the article title or date change, since we are calling the file itself.
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" >}})
[here]({{< ref "/posts/power-water-networks" >}})

No "/" in the end of the file path

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:

This is an image of the shortcode that generated it. You can include footnotes [^1], Hyperlinks, and regular markdown syntax. — This is an image of the shortcode that generated it. You can include footnotes [^1], Hyperlinks, and *regular* **markdown** syntax.
View original image View dithered image

Captions are handy to include sources and additional info but are also useful for screen-readers users (people who cannot see images). Describing the image is thoughtful of them.

To render uncompressed images (not dithered and not compressed in .webp), use the normal markdown syntax. This comes in handy for comic pages, for example. Please pre-compress the images to prevent overcrowding the server with big files.

![here goes your alt text ](image-filename.png)

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 translator name", "other 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" >}})

Translating Site Metadata

Another thing that needs to be translated is the many metadata words used in the website. Such as:

“Translated by”
“Written by”
“View Original Image / View Dithered Image”
“Subscribe to our Newsletter”
etc.

This metadata is stored in configuration files called lang.toml (pl.toml, fr.toml, etc.). Find this folder in solar > i18n > lang.toml

The syntax is (here for nl.toml):

[pagesize]
    other = 'Fill in here the word for page size'
[written_by]
	other = 'Door'
[translated_by]
	other = 'Vertaald door'

The [key] should not be changed and be the same in every language.

The most complete files are the french (fr.toml) and dutch (nl.toml) one, refer to those to know what expressions need translation. Untranslated expressions will default back to english.

Please reach out marie @ verdeil . net if you have any remaining questions.

Footnotes appear here the bottom of the document. ↩︎

Reactions

To make a comment, please send an e-mail to solar (at) lowtechmagazine (dot) com. Your e-mail address is not used for other purposes, and will be deleted after the comment is published. If you don’t want your real name to be published, sign the e-mail with the name you want to appear.

Name

This is the comment text.

LOW←TECH MAGAZINE

Article Template: How to write articles and translations in Markdown for Hugo?

Table of Contents

Files

Structure

Folder Name

Index

Comments file

Output

Syntax

Front matter data

Syntax Rules

Main rules

(Big headers are h2)

Sub-header are h3

Internal Links

Images shortcodes

Comments

Translations

Front matter

Internal Links

Translating Site Metadata

Reactions

Name