dnsmanager-website

This repository contains a prototype for a 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 using the 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

Setup

If you want to contribute to this website, you first need to setup the Zola static site generator. You can either download a pre-compiled package, or compile the program from source using a Rust compiler.

Package setup

For GNU/Linux users, there's a snap package available (no Flatpack yet):

$ snap install --edge zola

On Mac, you can install zola using Homebrew:

$ brew install zola

Alternatively, you can install a precompiled binary from the Github releases:

$ wget https://github.com/getzola/zola/releases/download/v0.10.1/zola-v0.10.1-x86_64-unknown-linux-gnu.tar.gz
$ tar xf zola*.gz && rm zola*.gz
$ sudo cp zola /bin/ && rm ./zola

Compile from source

If you don't have rustc (the official Rust compiler) and cargo (the related package manager) setup, you can either install them through your distribution, or get the latest version directly from the Rust project using rustup. If you're using Nix or GNU Guix for package management, you can also use those to setup cargo and rustc.

If you're running Debian buster or later, you can simply do:

$ sudo apt install cargo rustc

If your distribution does not have a package for Rust, you can download rustup and use it to setup a stable compiler.

Once Rust is setup, we can download Zola's source and compile it. Make sure you have git installed (sudo apt install git) before you proceed:

$ git clone https://github.com/getzola/zola
$ git checkout v0.10.1
$ cargo install --path=.

The last command (cargo install) not only compiles the project, but copies the generated binary to ~/.cargo/bin, which should already be in your $PATH after setting up Rust. You can check that zola is correctly setup by running it with the --version argument:

$ zola --version
zola 0.10.1

If you have an error message such as bash: zola: command not found, it is neither a problem with the Zola project or this website. It means the cargo bin directory is not in your $PATH for executable programs. A few things you can try:

• logging out then logging back in, if you've just setup rust, could apply changes to your $PATH
• appending export PATH="$HOME/.cargo/bin:$PATH" to your ~/.profile

If you still fail at running zola, you should read your distro's documentation or ask a friend.

Compiling the site

Now that zola is up and running, we can use it to build our website. When building a site, zola needs to know about its final address in order to generate links.

$ git clone https://tildegit.org/southerntofu/dnsmanager-website
$ cd dnsmanager-website
$ zola build

zola will then place all the generated files in the public/ folder. Note that zola needs to know about its base URL in order to generate links. By default, the base_url is defined in config.toml for the website's current address. You can pass another base URL as an argument to zola using the -u flag, and a different output folder using the -o flag:

$ zola build -u "http://localhost:1337" -o public_local/
$ zola build -u "http://acab13122131baca.onion" -o public_onion/
Building site...
-> Creating 7 pages (3 orphan), 5 sections, and processing 0 images
Done in 407ms.

Live reload

When updating the website content and stylesheets, you can run zola serve to setup a local web server with a preview of your changes:

Building site...
-> Creating 7 pages (3 orphan), 5 sections, and processing 0 images
Done in 730ms.

Web server is available at http://127.0.0.1:1111

Listening for changes in /home/user/Desktop/Sites/dnsmanager/{content, config.toml, static, templates, themes, sass}
Press Ctrl+C to stop

You can then access the website at the address zola will output, usually 127.0.0.1:1111.

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

Create a new article

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.

Each post has some TOML metadata attached. This is called a frontmatter, and the available variables are described in the Zola documentation:

+++
title = "My article"
date = 2020-03-29
+++

My article!

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

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 is further discussed in the Zola documentation.

This means you can directly link the file from the Markdown page using a relative link:

+++
title = "Hypothetical demo"
+++

[Link to latest incredible theory](important_stuff.pdf)

![Photo of Frantz Fanon](frantz_fanon.jpg)

Link another page from an article

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:

+++
title = "New post"
+++

As explained in the [introduction](@/introduction/index.md), we should abolish the government.

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

$ mkdir content/blog/2021
$ cp content/blog/2020/_index.*.md content/blog/2021

Translations

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.

In config.toml:

• declare the language in the languages variable: {code = "fr", rss = true}
• translate the basic template strings in the translations section:

[translations.fr]
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.

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.

Use translations in the templates

Localized string

If you want to use a translation define in the translations section of the config, you can use the trans function, like so:

{{ trans(key="readmore", lang=lang) }}

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

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:

{% import "widgets.html" as widgets %}
{{ widgets::i18n_path(path="@/blog/_index.md") }}

It will automatically use the language code figured out in index.html.

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:

{% import "widgets.html" as widgets %}
{{ widgets::i18n_content(path="@/blog/_index.md") }}

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 function, passing it the relevant lang context:

{% import "widgets.html" as widgets %}
<a href="{{ widgets:i18n_uri(path = "rss.xml") }}">RSS</a>

TODO

If something is missing for you, please open an issue.

• blog
  • basic blog
  • pagination
  • summaries
• i18n
  • pages
  • blogposts
  • other strings in the templates
  • localized RSS links
  • links to navigate between languages
• other
  • ASCII banner does not overflow
  • write setup/configuration guide
  •  reference water.css semantic styling
  • RSS links