Write docs for Duckling #4

Add template for localization

config.toml

@@ -139,9 +139,9 @@ show_repo = true
 # i.e. "@/blog/_index.md".
 # See https://www.getzola.org/documentation/content/linking/#internal-links
 links = [
+	{ url = "@/docs/gettingstarted/index.md", name = "Docs" },
 	{ url = "@/blog/_index.md", name = "Blog" },
 	{ url = "@/subprojects/_index.md", name = "Subprojects" },
-	{ url = "@/docs/overview/index.md", name = "Docs" },
 	{ url = "@/demo/index.md", name = "Demo" },
 ]
 
@@ -149,9 +149,9 @@ links = [
 # Links used in the footer.
 # Same as the nav ones.
 links = [
+	{ url = "@/docs/gettingstarted/index.md", name = "Docs" },
 	{ url = "@/blog/_index.md", name = "Blog" },
 	{ url = "@/subprojects/_index.md", name = "Subprojects" },
-	{ url = "@/docs/overview/index.md", name = "Docs" },
 	{ url = "@/demo/index.md", name = "Demo" },
 	{ url = "https://mastodon.de/@david_swift", name = "Developer" }
 ]

content/_index.md

@@ -17,200 +17,9 @@ Duckling is an minimal and feature-rich [Zola](https://www.getzola.org) theme th
 
 It is based on the [Duckquill](https://duckquill.daudix.one) theme for blogs.
 
-Some of the features Duckling has to offer:
+<div class="buttons" style="margin-top: 30px;">
-
+  <a href="/docs/gettingstarted">Getting Started</a>
-- Cute and informative social media cards for Discourse, Facebook, LinkedIn, Mastodon and more.
+</div>
-- [Mastodon-powered comments](https://carlschwan.eu/2020/12/29/adding-comments-to-your-static-blog-with-mastodon/); comment under a post by using your Mastodon account.
-- Lightweight by default, powerful when needed; no mandatory JavaScript is used by default.
-- Privacy respecting analytics using [GoatCounter](https://www.goatcounter.com), with support for self-hosting.
-- Estimated read time of the post; put away those with short attention spans.
-- A user-defined accent color for a pleasant look.
-- GitHub-style alerts. Yes, they're pretty, but don't overuse them. 
-- Post banners; they're even used in the social media cards!
-- YouTube/Vimeo shortcodes for easy video embedding.
-- Tiny by default; only ~100kB. Take that, 5MB Medium!
-- Customizable copyright text; you Better Quack Soul!
-- Image styling via URL. Yes, you read that right.
-- Useless CRT style that everyone seems to like.
-- Fully localizeable, worry not, [it's pretty easy](#localization).
-- Social links in the footer, with special styling.
-- LaTeX markup support via the [KaTeX](https://katex.org) library.
-- Emoji favicon if you're lazy to draw one.
-- Copy button for code blocks.
-
-## Installation
-
-First, if you already have Git setup, add this theme as a submodule:
-
-```bash
-git submodule init
-git submodule add https://git.aparoksha.dev/david-swift/duckling themes/duckling
-```
-
-Otherwise, simply clone it to your `themes` directory:
-
-```bash
-git clone https://git.aparoksha.dev/david-swift/duckling themes/duckling
-```
-
-{% alert(important=true) %}
-It is highly recommended to switch from the `main` branch to the latest release:
-{% end %}
-
-```bash
-cd themes/duckling
-git checkout tags/v0.1.0
-```
-
-Then, enable it in your `config.toml`:
-
-```toml
-theme = "duckling"
-```
-
-To update the theme, simply switch to a new tag:
-
-```bash
-git submodule update --remote --merge
-cd themes/duckling
-git checkout tags/v0.1.0
-```
-
-{% alert(important=true) %}
-Check the changelog for all versions after the one you are using; there may be breaking changes that require manual involvement.
-{% end %}
-
-## Options
-
-Duckling offers some configuration options to make it fit you better; most options have pretty descriptive comments, so it should be easy to understand what they do.
-
-## Front Matter
-
-Duckling has some [front matter](https://www.getzola.org/documentation/content/page/#front-matter) variables that you can use by setting them in the `[extra]` section:
-
-### Global
-
-Configuration variables from `config.toml` that can be set/overriden per page/section:
-
-- `default_theme`: Which theme should be used by default (light/dark).
-- `accent_color`: Sets theme and [browser theme](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/theme-color) color.
-- `accent_color_dark`: Ditto but for the dark theme. If not set regular variant will be used.
-- `emoji_favicon`: Use emoji as a favicon. Only one emoji is being rendered, everything else is truncated.
-- `styles`: Additional CSS styles; expects them to be in the `./static/` directory. If you are using Sass it will be generated there automatically.
-- `scripts`: Additional JavaScript scripts; expects them to be in the `./static/` directory.
-- `katex`: Whether to enable the KaTeX library for rendering LaTeX.
-- `toc`: Enables table of contents. Only first 2 levels of headings are listed.
-- `toc_inline`: Whether to render inline table of contents at the top of all pages, in addition to floating quick navigation buttons.
-- `toc_ordered`: Whether to use numbered (ordered) list for table of contents.
-
-Other variables:
-
-- `apple_touch_icon`: Filename of the [colocated](https://www.getzola.org/documentation/content/overview/#asset-colocation) Apple Touch Icon.
-- `favicon`: Filename of the [colocated](https://www.getzola.org/documentation/content/overview/#asset-colocation) favicon.
-- `card`: Filename of the [colocated](https://www.getzola.org/documentation/content/overview/#asset-colocation) metadata card.
-- `archive`: Displays an archived message.
-- `trigger`: Displays a trigger warning message.
-- `disclaimer`: Displays a disclaimer message.
-- `left_align_badges`: Left-align badges in subprojects lists.
-- `hide_subproject_tags`: Hide the link to the list of tags in subprojects lists.
-- `hide_number_of_subprojects`: Hide the subprojects counter in a subproject list.
-
-### Blog Post Specific
-
-- `banner`: Filename of the [colocated](https://www.getzola.org/documentation/content/overview/#asset-colocation) banner image. Recommended dimensions are 2:1 aspect ratio and 1920x960 resolution.
-- `banner_pixels` Makes the banner use nearest neighbor algorithm for scaling, useful for keeping pixel-art sharp.
-- `archived`: Make the post visually stand out in the post list. Also accepts message as a value.
-- `featured`: Ditto but doesn't accept message as a value.
-- `hot`: Ditto.
-- `poor`: Ditto.
-
-In `[extra.comments]` section:
-
-- `host`: The Mastodon server on which the post was posted.
-- `user`: The username of the poster.
-- `id`: ID of the post; the one in the URL.
-
-### Subproject Specific
-
-All the options for blog posts are available for subprojects as well.
-
-Additionally, you can use the following front matter variables:
-
-- `preview`: Filename of the image displayed in the subprojects list.
-- `expand`: Make the subproject use the full width in the subprojects list.
-- `url`: Instead of showing the page's content, redirect from the subprojects list to the given URL.
-- `badge`: A label displayed in the item's corner in the subprojects list.
-
-### Documentation Page Specific
-
-All the options for blog posts are avilable for documentation pages as well, with the exception of banners.
-
-Additionally, you can use the following front matter variables:
-
-- `section`: Assign the page to the section with the given index. The sections are defined in the Zola section (the `_index.md`). Use `0` to place it above all the sections.
-
-### Documentation Specific
-
-- `sections`: The sections available in the documentation.
-
-### Localization
-
-Duckling ships with a localization system based on one used in [tabi](https://github.com/welpo/tabi), it's very easy to use and quite flexible at the same time.
-
-To add a translation, simply create a file in your site's `i18n` directory called `LANG_CODE.toml`, e.g `fr.toml`. The language code should be either [ISO 639-1](https://localizely.com/iso-639-1-list/) or [BCP 47](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
-
-Inside that file, copy-paste one of the existing translations from Duckling and adapt it to your needs. You can also check [tabi](https://github.com/welpo/tabi/tree/main/i18n) translation files for reference.
-
-Additionally to translating Duckling, you can also override the English stings by copy-pasting `en.toml` from Duckling to the `i18n` directory of your website and adjusting the values to your liking.
-
-### Custom Styles
-
-To add your own or override existing styles, create a custom style and add it in the `config.toml`:
-
-```toml
-[extra]
-styles = [
-  "YOUR_STYLE.css",
-  "ALSO_YOUR_STYLE.css"
-]
-```
-
-Additional styles are expected it to be in the `static` directory. If you are using Sass they will be compiled there by default.
-
-If for some reason overridden style is not respected, try using `!important` (don't use it unless needed). You can import styles from Duckling using:
-
-```scss
-@use "../themes/duckling/sass/NEEDED_FILE.scss";
-```
-
-You can also load styles per page/section by setting them inside page's front matter:
-
-```toml
-[extra]
-styles = [
-  "YOUR_PAGE_STYLE.css"
-]
-```
-
-### Accent Color
-
-Duckling respects chosen accent color everywhere. To use your own, simply change it in `config.toml`:
-
-```toml
-[extra]
-accent_color = "#3584e4"
-```
-
-Additionally, you can set a separate color for dark mode:
-
-```toml
-[extra]
-accent_color_dark = "#ff7800"
-```
-
-### Favicon
-
-Files named `favicon.png` and `apple-touch-icon.png` are used as favicon and Apple Touch Icon respectively. For animated favicon you can use APNG with the `png` file extension.
 
 ## In the Wild
 

content/docs/_index.md

@@ -5,6 +5,7 @@ page_template = "documentation_page.html"
 
 [extra]
 sections = [
-  "More"
+  "Usage",
+  "Advanced"
 ]
 +++

content/docs/blogs/index.md

@@ -0,0 +1,40 @@
++++
+weight = 1
+title = "Blogs"
+[extra]
+section = 1
++++
+
+A blog is a place to publish articles. Take a look at the [sample blog](/blog).
+
+To create a blog, start with a [Zola section](https://www.getzola.org/documentation/content/section/).
+Set the following front matter variables:
+
+```toml
+template = "article_list.html"
+page_template = "article.html"
+```
+
+Then, add [pages](https://www.getzola.org/documentation/content/page/).
+
+## Options
+
+Use the default [Zola section front matter variables](https://www.getzola.org/documentation/content/section/#front-matter) to configure the blog.
+In addition to the [default front matter variables for pages](https://www.getzola.org/documentation/content/page/#front-matter), Duckling provides some additional variables that can be set under `[extra]`:
+
+- `banner`: Filename of the [colocated](https://www.getzola.org/documentation/content/overview/#asset-colocation) banner image. Recommended dimensions are 2:1 aspect ratio and 1920x960 resolution.
+- `banner_pixels` Makes the banner use nearest neighbor algorithm for scaling, useful for keeping pixel-art sharp.
+- `archived`: Make the post visually stand out in the post list. Also accepts message as a value.
+- `featured`: Ditto but doesn't accept message as a value.
+- `hot`: Ditto.
+- `poor`: Ditto.
+
+The following options are available in the `[extra.comments]` section:
+
+- `host`: The Mastodon server on which the post was posted.
+- `user`: The username of the poster.
+- `id`: ID of the post; the one in the URL.
+
+## Example
+
+The code for the [sample blog](/blog) can be used as a reference or as a starting point. It is available [in the project's source code](https://git.aparoksha.dev/david-swift/duckling/src/branch/main/content/blog).

content/docs/config/index.md

@@ -0,0 +1,38 @@
++++
+weight = 1
+title = "Configuration"
+[extra]
+section = 0
++++
+
+Duckling offers a number of variables that can be set in the a website's `config.toml` file.
+
+The following configuration variables from `config.toml` can be set/overriden per page/section:
+
+- `default_theme`: Which theme should be used by default (light/dark).
+- `accent_color`: Sets theme and [browser theme](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/theme-color) color.
+- `accent_color_dark`: Ditto but for the dark theme. If not set regular variant will be used.
+- `emoji_favicon`: Use emoji as a favicon. Only one emoji is being rendered, everything else is truncated.
+- `styles`: Additional CSS styles; expects them to be in the `./static/` directory. If you are using Sass it will be generated there automatically.
+- `scripts`: Additional JavaScript scripts; expects them to be in the `./static/` directory.
+- `katex`: Whether to enable the KaTeX library for rendering LaTeX.
+- `toc`: Enables table of contents. Only first 2 levels of headings are listed.
+- `toc_inline`: Whether to render inline table of contents at the top of all pages, in addition to floating quick navigation buttons.
+- `toc_ordered`: Whether to use numbered (ordered) list for table of contents.
+
+The following variables can be set in the `config.tom` file:
+
+- `apple_touch_icon`: Filename of the [colocated](https://www.getzola.org/documentation/content/overview/#asset-colocation) Apple Touch Icon.
+- `favicon`: Filename of the [colocated](https://www.getzola.org/documentation/content/overview/#asset-colocation) favicon.
+- `card`: Filename of the [colocated](https://www.getzola.org/documentation/content/overview/#asset-colocation) metadata card.
+- `archive`: Displays an archived message.
+- `trigger`: Displays a trigger warning message.
+- `disclaimer`: Displays a disclaimer message.
+- `left_align_badges`: Left-align badges in subprojects lists.
+- `hide_subproject_tags`: Hide the link to the list of tags in subprojects lists.
+- `hide_number_of_subprojects`: Hide the subprojects counter in a subproject list.
+
+## Favicon
+
+Files named `favicon.png` and `apple-touch-icon.png` are used as favicon and Apple Touch Icon respectively. For animated favicon you can use APNG with the `png` file extension.
+

content/docs/details/index.md

@@ -1,8 +0,0 @@
-+++
-weight = 2
-title = "Details"
-[extra]
-section = 1
-+++
-
-This is overview's content!

content/docs/docs/index.md

@@ -0,0 +1,53 @@
++++
+weight = 3
+title = "Docs"
+[extra]
+section = 1
++++
+
+Document a tool using the built-in documentation feature.
+
+To create a documentation page, start with a [Zola section](https://www.getzola.org/documentation/content/section/).
+Set the following front matter variable:
+
+```toml
+page_template = "documentation_page.html"
+```
+
+Then, add [pages](https://www.getzola.org/documentation/content/page/).
+Use the `sections` front matter variable in the section and the `section` front matter variable in the individual pages to group multiple pages to a docs section.
+
+## Options
+
+### Section
+
+Use the default [Zola section front matter variables](https://www.getzola.org/documentation/content/section/#front-matter) to configure the docs.
+Duckling provides the following additional variable:
+
+- `sections`: The sections available in the documentation.
+
+Use the following syntax:
+
+```toml
+[extra]
+sections = [
+  "Usage", # Section 1
+  "Extra"  # Section 2
+]
+```
+
+### Page
+
+In addition to the [default front matter variables for pages](https://www.getzola.org/documentation/content/page/#front-matter), Duckling provides some additional variables that can be set under `[extra]`:
+
+- `section`: Assign the page to the section with the given index. The sections are defined in the Zola section (the `_index.md`). Use `0` to place it above all the sections, `1` for the first section, etc.
+
+The following options are available in the `[extra.comments]` section:
+
+- `host`: The Mastodon server on which the post was posted.
+- `user`: The username of the poster.
+- `id`: ID of the post; the one in the URL.
+
+## Example
+
+The code for Duckling's docs can be used as a reference or as a starting point. It is available [in the project's source code](https://git.aparoksha.dev/david-swift/duckling/src/branch/main/content/docs).

content/docs/gettingstarted/index.md

@@ -0,0 +1,48 @@
++++
+weight = 0
+title = "Getting Started"
+[extra]
+section = 0
++++
+
+Duckling is a theme for the [Zola](https://www.getzola.org/) static site generator.
+Follow the instructions in the [Getting Started section](https://www.getzola.org/documentation/getting-started/overview/) in their documentation.
+
+## Installation
+
+After having a Zola website setup, you can install the Duckling theme.
+
+First, if you already have Git setup, add this theme as a submodule:
+
+```bash
+git submodule init
+git submodule add https://git.aparoksha.dev/david-swift/duckling themes/duckling
+```
+
+Otherwise, simply clone it to your `themes` directory:
+
+```bash
+git clone https://git.aparoksha.dev/david-swift/duckling themes/duckling
+```
+
+It is highly recommended to switch from the `main` branch to the latest release:
+
+```bash
+cd themes/duckling
+git checkout tags/v0.1.0
+```
+
+Then, enable it in your `config.toml`:
+
+```toml
+theme = "duckling"
+```
+
+To update the theme, simply switch to a new tag:
+
+```bash
+git submodule update --remote --merge
+cd themes/duckling
+git checkout tags/v0.1.0
+```
+

content/docs/localization/index.md

@@ -0,0 +1,14 @@
++++
+weight = 0
+title = "Localization"
+[extra]
+section = 2
++++
+
+Duckling ships with a localization system based on one used in [tabi](https://github.com/welpo/tabi), which is easy to use and flexible at the same time.
+
+To add a translation, simply create a file in your site's `i18n` directory called `LANG_CODE.toml`, e.g `fr.toml`. The language code should be either [ISO 639-1](https://localizely.com/iso-639-1-list/) or [BCP 47](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
+
+Inside that file, copy-paste the [English translation from Duckling](https://git.aparoksha.dev/david-swift/duckling/src/branch/main/i18n/en.toml) and adapt it to your needs. You can also check [tabi](https://github.com/welpo/tabi/tree/main/i18n) translation files for reference.
+
+Additionally to translating Duckling, you can override the English strings by providing a `en.toml` file.

content/docs/overview/index.md

@@ -1,8 +0,0 @@
-+++
-weight = 0
-title = "Overview"
-[extra]
-section = 0
-+++
-
-This is overview's content!

content/docs/page2/index.md

@@ -1,8 +0,0 @@
-+++
-weight = 1
-title = "Page 2"
-[extra]
-section = 1
-+++
-
-Another page

content/docs/styling/index.md

@@ -0,0 +1,33 @@
++++
+weight = 1
+title = "Styling"
+[extra]
+section = 2
++++
+
+To add your own or override existing styles, create a custom style and add it in the `config.toml`:
+
+```toml
+[extra]
+styles = [
+  "YOUR_STYLE.css",
+  "ALSO_YOUR_STYLE.css"
+]
+```
+
+Additional styles are expected it to be in the `static` directory. Sass files will be compiled there by default.
+
+If for some reason overridden style is not respected, try using `!important` (don't use it unless needed). You can import styles from Duckling using:
+
+```scss
+@use "../themes/duckling/sass/NEEDED_FILE.scss";
+```
+
+You can also load styles per page/section by setting them inside the page's front matter:
+
+```toml
+[extra]
+styles = [
+  "YOUR_PAGE_STYLE.css"
+]
+```

content/docs/subprojects/index.md

@@ -0,0 +1,42 @@
++++
+weight = 2
+title = "Subprojects"
+[extra]
+section = 1
++++
+
+The subprojects feature is designed to showcase the capabilities of a project, but it can be used for many other purposes as well.
+Check out the demo [here](/subprojects).
+
+To create a collection of subprojects, start with a [Zola section](https://www.getzola.org/documentation/content/section/).
+Set the following front matter variables:
+
+```toml
+template = "subproject_list.html"
+page_template = "subproject.html"
+```
+
+Then, add [pages](https://www.getzola.org/documentation/content/page/).
+Make sure to set the `preview` front matter variable if you want to include a preview picture in the collection.
+
+## Options
+
+Use the default [Zola section front matter variables](https://www.getzola.org/documentation/content/section/#front-matter) to configure the subprojects collection.
+In addition to the [default front matter variables for pages](https://www.getzola.org/documentation/content/page/#front-matter), Duckling provides some additional variables that can be set under `[extra]`:
+
+- `preview`: Filename of the image displayed in the subprojects list.
+- `expand`: Make the subproject use the full width in the subprojects list.
+- `url`: Instead of showing the page's content, redirect from the subprojects list to the given URL.
+- `badge`: A label displayed in the item's corner in the subprojects list.
+- `banner`: Filename of the [colocated](https://www.getzola.org/documentation/content/overview/#asset-colocation) banner image. Recommended dimensions are 2:1 aspect ratio and 1920x960 resolution.
+- `banner_pixels` Makes the banner use nearest neighbor algorithm for scaling, useful for keeping pixel-art sharp.
+
+The following options are available in the `[extra.comments]` section:
+
+- `host`: The Mastodon server on which the post was posted.
+- `user`: The username of the poster.
+- `id`: ID of the post; the one in the URL.
+
+## Example
+
+The code for the [sample subproject collection](/subprojects) can be used as a reference or as a starting point. It is available [in the project's source code](https://git.aparoksha.dev/david-swift/duckling/src/branch/main/content/subprojects).

i18n/en.toml

@@ -0,0 +1,87 @@
+# Shown in language picker for multi-language sites
+language_name = "English"
+# Tera date format used for listing posts
+# (post publication date, tag posts list...).
+# Not used in comments, "date_locale" is used instead.
+# See https://docs.rs/chrono/0.4.31/chrono/format/strftime/index.html
+date_format = "%B %d, %Y"
+date_locale = "en_US"
+
+# Menu items.
+# Should match the names in config.extra.nav.links and config.extra.footer.links.
+Docs = "Docs"
+Blog = "Blog"
+Subprojects = "Subprojects"
+Demo = "Demo"
+Developer = "Developer"
+
+all_tags = "See all tags"
+archived = "Archived"
+author = "Author"
+author_conjunction = " and "
+author_separator = ", "
+back = "Back"
+backlinks = "Backlinks"
+blog_post_author = "Blog post author"
+boosts_from = "Boosts from $INSTANCE"
+by_author = "By $AUTHOR"
+caution = "Caution"
+comments = "Comments"
+comments_description = "You can comment on this blog post by publicly replying to this post using a Mastodon or other ActivityPub/Fediverse account. Known non-private replies are displayed below."
+comments_noscript = "Loading comments relies on JavaScript. Try enabling JavaScript and reloading, or visit the original post on Mastodon."
+comments_qr = "QR code to a Mastodon post"
+copy_code = "Copy Code"
+disclaimer = "Disclaimer"
+drafted = "Drafted"
+faves_from = "Favorites from $INSTANCE"
+featured = "Featured"
+feed = "Feed"
+file_an_issue = "File an Issue"
+filter_by_tag = "Filter by tag"
+first = "First"
+go_to_top = "Go to Top"
+hot = "Hot"
+important = "Important"
+language = "Language"
+last = "Last"
+load_comments = "Load Comments"
+loading = "Loading"
+many_minutes_read = "$NUMBER minutes read"
+many_posts = "$NUMBER posts in total"
+many_tags = "$NUMBER tags in total"
+minutes_read = "$NUMBER minute read"
+more_matches = "$MATCHES more matches"
+next = "Next"
+no_comments = "No Comments yet :/"
+note = "Note"
+one_posts = "$NUMBER post in total"
+one_tags = "$NUMBER tag in total"
+open_post = "Open Post"
+poor = "Poor"
+posts = "$NUMBER posts in total"
+posts_with_tag = "Posts with tag $TAG"
+powered_by = "Powered by $ZOLA and $DUCKQUILL"
+previous = "Previous"
+published = "Published on"
+reload = "Reload"
+repo = "Repository"
+search = "Search"
+search_for = "Search for"
+sensitive = "Sensitive Content"
+share = "Share"
+skip_to_content = "Skip to Main Content"
+source = "Website source"
+table_of_contents = "Table of Contents"
+tags = "tags"
+tags_title = "Tags"
+theme = "Theme"
+theme_dark = "Switch to Dark Theme"
+theme_light = "Switch to Light Theme"
+theme_system = "Use System Theme"
+tip = "Tip"
+trigger_warning = "Trigger Warning"
+updated = "Updated on"
+view_comment = "View Comment At"
+view_profile = "View Profile At"
+warning = "Warning"
+