132 lines
4.5 KiB
Markdown
132 lines
4.5 KiB
Markdown
# dnsmanager-website
|
||
|
||
Prototype for a dnsmanager homepage
|
||
|
||
# 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](https://www.getzola.org/documentation/content/page/#front-matter):
|
||
|
||
```
|
||
+++
|
||
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](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:
|
||
|
||
```
|
||
+++
|
||
title = "Hypothetical demo"
|
||
+++
|
||
|
||
[Link to latest incredible theory](important_stuff.pdf)
|
||
|
||
|
||
```
|
||
|
||
## 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](https://www.getzola.org/documentation/content/linking/#internal-links):
|
||
|
||
```
|
||
+++
|
||
title = "New post"
|
||
+++
|
||
|
||
As explained in the [introduction](@/introduction/index.md), we should abolish the government.
|
||
```
|
||
|
||
# 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](https://www.getzola.org/documentation/templates/overview/#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](https://www.getzola.org/documentation/templates/overview/#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.
|
||
|
||
- [x] blog
|
||
- [x] basic blog
|
||
- [x] pagination
|
||
- [x] summaries
|
||
- [ ] i18n
|
||
- [x] pages
|
||
- [x] blogposts
|
||
- [x] other strings in the templates
|
||
- [x] localized RSS links
|
||
- [ ] links to navigate between languages
|
||
- [ ] other
|
||
- [x] ASCII banner does not overflow
|
||
- [ ] write setup/configuration guide
|
||
- [ ] reference water.css semantic styling
|
||
- [x] RSS links
|