+++
insert_anchor_links = "left"
title = "Home"
+++

{% crt() %}
```
      _          _          _          _          _
    >(')____,  >(')____,  >(')____,  >(')____,  >(') ___,
      (` =~~/    (` =~~/    (` =~~/    (` =~~/    (` =~~/
jgs~^~^`---'~^~^~^`---'~^~^~^`---'~^~^~^`---'~^~^~^`---'~^~^~
```
{% end %}

# Duckling

Duckquill is an minimal and feature-rich [Zola](https://www.getzola.org) theme that has the purpose of greatly simplifying the process of rolling up your project website. It aims to provide all the necessary options for comfortable writing, while keeping the balance of simplicity.

It is based on the [Duckquill](https://duckquill.daudix.one) theme for blogs.

Some of the features Duckling has to offer:

- Cute and informative social media cards for Discourse, Facebook, LinkedIn, Mastodon and more.
- [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.

<!-- TODO: Add instructions for documentation and subprojects -->

### Blog Post Specific

<!-- TODO: Check archived/featured/hot/poor -->

- `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.

### 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

- [duckling.aparoksha.dev](https://duckling.aparoksha.dev)
- Yours? <small>(feel free to send a pull request)</small>

## Thanks To

- [David Lapshin](https://daudix.one) for [Duckquill](https://duckquill.daudix.one)
- [Everything Duckquill is based on](https://duckquill.daudix.one/#thanks-to)