hak8or/blog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bf2f3a61585d2acb7be3b69cd4476eaac8568f1b
blog/content/_index.md

12 KiB
Raw Blame History

+++ insert_anchor_links = "right" title = "Home" +++

{% crt() %}

      _          _          _          _          _
    >(')____,  >(')____,  >(')____,  >(')____,  >(') ___,
      (` =~~/    (` =~~/    (` =~~/    (` =~~/    (` =~~/
jgs~^~^`---'~^~^~^`---'~^~^~^`---'~^~^~^`---'~^~^~^`---'~^~^~

{% end %}

Duckquill

Duckquill is an opinionated, modern, pretty, and clean Zola theme that has the purpose of greatly simplifying the process of rolling up your blog. It aims to provide all the necessary options for comfortable writing, while keeping the balance of simplicity.

With it, you can change some configuration variables, tweak some of the included graphics, and have a nice blog up in minutes!

Some of the features Duckquill has to offer:

  • Cute and informative social media cards for Discourse, Facebook, LinkedIn, Mastodon and more.
  • Mastodon-powered comments; comment under a post by using your Mastodon account.
  • Lightweight by default, powerful when needed; no JavaScript is used by default.
  • Privacy respecting analytics using GoatCounter, with support for self-hosting.
  • Estimated read time of the post; put away those with short attention spans.
  • Everything is tinted with the user-defined primary color for a pleasant look.
  • Light/dark/system theme switcher (for some reason everyone likes these).
  • 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.
  • Social links in the footer, with special styling.
  • LaTeX markup support via the KaTeX library.
  • Emoji favicon if you're lazy to draw one.
  • Copy button for code blocks.
  • Search functionality.

{% alert(note=true) %} Although Duckquill is made based on the needs of my website, I am very open to feature requests as long as they are somewhat useful to others, so if you need a feature/configuration that does not exist, feel free to open an issue, or better yet, a pull request! {% end %}

{% alert(tip=true) %} If you use Duckquill and enjoy it, or just like my work, please consider buying me a coffee, it would mean the world to me ^^. {% end %}

Installation

First, if you already have Git setup, add this theme as a submodule:

git submodule init
git submodule add https://codeberg.org/daudix/duckquill.git themes/duckquill

Otherwise, simply clone it to your themes directory:

git clone https://codeberg.org/daudix/duckquill.git themes/duckquill

{% alert(important=true) %} It is highly recommended to switch from the main branch to the latest release: {% end %}

cd themes/duckquill
git checkout tags/v4.8.0

Then, enable it in your config.toml:

theme = "duckquill"

To update the theme, simply switch to a new tag:

git submodule update --remote --merge
cd themes/duckquill
git checkout tags/v4.8.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

Duckquill 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

Duckquill has some front matter variables that you can use by setting them in the [extra] section:

Global

  • archive: Make the post visually stand out in the post list. Also accepts message as a value.
  • trigger: Displays a trigger warning message.
  • disclaimer: Displays a disclaimer message.
  • toc: Enables table of contents. Only first 2 levels of headings are listed.

Blog post specific:

  • banner: Filename of the colocated banner image. Recommended dimensions are 2:1 aspect ratio and 1920x960 resolution.
  • featured: Make the post visually stand out in the post list.
  • 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

Duckquill ships with a localization system based on one used in 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 or BCP 47.

Inside that file, copy-paste one of the existing translations from Duckquill and adapt it to your needs. You can also check tabi translation files for reference.

Additionally to translating Duckquill, you can also override the English stings by copy-pasting en.toml from Duckquill to the i18n directory of your website and adjusting the values to your liking.

Custom Stylesheets

To add your own or override existing styles, create a custom stylesheet and add it in the config.toml:

[extra]
stylesheets = [
  "YOUR_STYLE.css",
  "ALSO_YOUR_STYLE.css"
]

Additional stylesheets 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 Duckquill using:

@use "../themes/duckquill/sass/NEEDED_FILE.scss";

You can also load stylesheets per page/section by setting them inside page's front matter:

[extra]
stylesheets = [
  "YOUR_PAGE_STYLE.css"
]

Primary Color

Duckquill respects chosen primary color everywhere. To use your own, simply change the primary color in config.toml:

[extra]
primary_color = "#3584e4"

Additionally, you can set a separate color for dark mode:

[extra]
primary_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

This list is starting to get long, so click on it to expand it.

In Credits

Assets Sources

All sources for Duckquill's assets are available here and licensed under CC BY-SA 4.0. The reason for not putting the sources in the same repo as Duckquill itself is simple: I want it to be as small as possible, so that repo cloning is fast and doesn't make the site significantly heavier; this is also why the demo uses remote images instead of local copies.

Credits

Tools Used

As for the code formatter I use built-in VSCodium one. Prettier is good but I don't like how it tries to make code fit in a very narrow column, this can be changed of course, but built-in formatter does it's job so I don't bother doing so.

Thanks To