diff --git a/config.toml b/config.toml index c61628e..b0b7b8f 100644 --- a/config.toml +++ b/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" } ] diff --git a/content/_index.md b/content/_index.md index 6a3c695..dbd46b7 100644 --- a/content/_index.md +++ b/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: - -- 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. -- `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. +
+ Getting Started +
## In the Wild diff --git a/content/docs/_index.md b/content/docs/_index.md index ca21d17..66f4b2b 100644 --- a/content/docs/_index.md +++ b/content/docs/_index.md @@ -5,6 +5,7 @@ page_template = "documentation_page.html" [extra] sections = [ - "More" + "Usage", + "Advanced" ] +++ diff --git a/content/docs/blogs/index.md b/content/docs/blogs/index.md new file mode 100644 index 0000000..112c1ac --- /dev/null +++ b/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). diff --git a/content/docs/config/index.md b/content/docs/config/index.md new file mode 100644 index 0000000..302c58e --- /dev/null +++ b/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. + diff --git a/content/docs/details/index.md b/content/docs/details/index.md deleted file mode 100644 index d983ed6..0000000 --- a/content/docs/details/index.md +++ /dev/null @@ -1,8 +0,0 @@ -+++ -weight = 2 -title = "Details" -[extra] -section = 1 -+++ - -This is overview's content! diff --git a/content/docs/docs/index.md b/content/docs/docs/index.md new file mode 100644 index 0000000..a62d32e --- /dev/null +++ b/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). diff --git a/content/docs/gettingstarted/index.md b/content/docs/gettingstarted/index.md new file mode 100644 index 0000000..ce718ce --- /dev/null +++ b/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 +``` + diff --git a/content/docs/localization/index.md b/content/docs/localization/index.md new file mode 100644 index 0000000..584daf4 --- /dev/null +++ b/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. diff --git a/content/docs/overview/banner.webp b/content/docs/overview/banner.webp deleted file mode 100644 index ae0672b..0000000 Binary files a/content/docs/overview/banner.webp and /dev/null differ diff --git a/content/docs/overview/index.md b/content/docs/overview/index.md deleted file mode 100644 index aba104c..0000000 --- a/content/docs/overview/index.md +++ /dev/null @@ -1,8 +0,0 @@ -+++ -weight = 0 -title = "Overview" -[extra] -section = 0 -+++ - -This is overview's content! diff --git a/content/docs/page2/index.md b/content/docs/page2/index.md deleted file mode 100644 index f3713b0..0000000 --- a/content/docs/page2/index.md +++ /dev/null @@ -1,8 +0,0 @@ -+++ -weight = 1 -title = "Page 2" -[extra] -section = 1 -+++ - -Another page diff --git a/content/docs/styling/index.md b/content/docs/styling/index.md new file mode 100644 index 0000000..a892faa --- /dev/null +++ b/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" +] +``` diff --git a/content/docs/subprojects/index.md b/content/docs/subprojects/index.md new file mode 100644 index 0000000..5317256 --- /dev/null +++ b/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). diff --git a/i18n/en.toml b/i18n/en.toml new file mode 100644 index 0000000..d58096e --- /dev/null +++ b/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" +