💾 Archived View for gemini.hyperlinkyourheart.com › gemicandocs › pages › creating-themes.gmi captured on 2022-04-28 at 17:19:37. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-11-30)
-=-=-=-=-=-=-
To generate its Gemtext output, Gemican uses the Jinja[1] templating engine due to its flexibility and straightforward syntax. If you want to create your own theme, feel free to take inspiration from the "simple" theme[2].
To generate your site using a theme you have created (or downloaded manually and then modified), you can specify that theme via the `-t` flag:
gemican content -s gemicanconf.py -t /projects/your-site/themes/your-theme
If you'd rather not specify the theme on every invocation, you can define `THEME` in your settings to point to the location of your preferred theme.
To make your own theme, you must follow the following structure:
├── static
│ ├── css
│ └── images
└── templates
├── archives.gmi // to display archives
├── period_archives.gmi // to display time-period archives
├── article.gmi // processed for each article
├── author.gmi // processed for each author
├── authors.gmi // must list all the authors
├── categories.gmi // must list all the categories
├── category.gmi // processed for each category
├── index.gmi // the index (list all the articles)
├── page.gmi // processed for each page
├── tag.gmi // processed for each tag
└── tags.gmi // must list all the tags. Can be a tag cloud.
The idea is to use a simple syntax that you can embed into your Gemtext pages. This document describes which templates should exist in a theme, and which variables will be passed to each template at generation time.
All templates will receive the variables defined in your settings file, as long as they are in all-caps. You can access them directly.
All of these settings will be available to all templates.
=============== ===================================================
Variable Description
=============== ===================================================
output_file The name of the file currently being generated. For
instance, when Gemican is rendering the home page,
output_file will be "index.gmi".
articles The list of articles, ordered descending by date.
All the elements are `Article` objects, so you can
access their attributes (e.g. title, summary, author
etc.). Sometimes this is shadowed (for instance, in
the tags page). You will then find info about it
in the `all_articles` variable.
dates The same list of articles, but ordered by date,
ascending.
hidden_articles The list of hidden articles
drafts The list of draft articles
authors A list of (author, articles) tuples, containing all
the authors and corresponding articles (values)
categories A list of (category, articles) tuples, containing
all the categories and corresponding articles (values)
tags A list of (tag, articles) tuples, containing all
the tags and corresponding articles (values)
pages The list of pages
hidden_pages The list of hidden pages
draft_pages The list of draft pages
=============== ===================================================
URL wrappers (currently categories, tags, and authors), have comparison methods that allow them to be easily sorted by name:
{% for tag, articles in tags|sort %}
If you want to sort based on different criteria, Jinja's sort command[3] has a number of options.
Gemican formats the date according to your settings and locale (`DATE_FORMATS`/`DEFAULT_DATE_FORMAT`) and provides a `locale_date` attribute. On the other hand, the `date` attribute will be a datetime[4] object. If you need custom formatting for a date different than your settings, use the Jinja filter `strftime` that comes with Gemican. Usage is same as Python strftime[5] format, but the filter will do the right thing and format your date according to the locale given in your settings:
{{ article.date|strftime('%d %B %Y') }}
This is the home page or index of your blog, generated at `index.gmi`.
If pagination is active, subsequent pages will reside in `index{number}.gmi`.
====================== ===================================================
Variable Description
====================== ===================================================
articles_paginator A paginator object for the list of articles
articles_page The current page of articles
articles_previous_page The previous page of articles (`None` if page does
not exist)
articles_next_page The next page of articles (`None` if page does
not exist)
dates_paginator A paginator object for the article list, ordered by
date, ascending.
dates_page The current page of articles, ordered by date,
ascending.
dates_previous_page The previous page of articles, ordered by date,
ascending (`None` if page does not exist)
dates_next_page The next page of articles, ordered by date,
ascending (`None` if page does not exist)
page_name 'index' -- useful for pagination links
====================== ===================================================
This template will be processed for each of the existing authors, with output generated according to the `AUTHOR_SAVE_AS` setting (Default: `author/{slug}.gmi`). If pagination is active, subsequent pages will by default reside at `author/{slug}{number}.gmi`.
====================== ===================================================
Variable Description
====================== ===================================================
author The name of the author being processed
articles Articles by this author
dates Articles by this author, but ordered by date,
ascending
articles_paginator A paginator object for the list of articles
articles_page The current page of articles
articles_previous_page The previous page of articles (`None` if page does
not exist)
articles_next_page The next page of articles (`None` if page does
not exist)
dates_paginator A paginator object for the article list, ordered by
date, ascending.
dates_page The current page of articles, ordered by date,
ascending.
dates_previous_page The previous page of articles, ordered by date,
ascending (`None` if page does not exist)
dates_next_page The next page of articles, ordered by date,
ascending (`None` if page does not exist)
page_name AUTHOR_URL where everything after `{slug}` is
removed -- useful for pagination links
====================== ===================================================
This template will be processed for each of the existing categories, with output generated according to the `CATEGORY_SAVE_AS` setting (Default: `category/{slug}.gmi`). If pagination is active, subsequent pages will by default reside at `category/{slug}{number}.gmi`.
====================== ===================================================
Variable Description
====================== ===================================================
category The name of the category being processed
articles Articles for this category
dates Articles for this category, but ordered by date,
ascending
articles_paginator A paginator object for the list of articles
articles_page The current page of articles
articles_previous_page The previous page of articles (`None` if page does
not exist)
articles_next_page The next page of articles (`None` if page does
not exist)
dates_paginator A paginator object for the list of articles,
ordered by date, ascending
dates_page The current page of articles, ordered by date,
ascending
dates_previous_page The previous page of articles, ordered by date,
ascending (`None` if page does not exist)
dates_next_page The next page of articles, ordered by date,
ascending (`None` if page does not exist)
page_name CATEGORY_URL where everything after `{slug}` is
removed -- useful for pagination links
====================== ===================================================
This template will be processed for each article, with output generated according to the `ARTICLE_SAVE_AS` setting (Default: `{slug}.gmi`). The following variables are available when rendering.
============= =================================================== Variable Description ============= =================================================== article The article object to be displayed category The name of the category for the current article ============= ===================================================
Any metadata that you put in the header of the article source file will be available as fields on the `article` object. The field name will be the same as the name of the metadata field, except in all-lowercase characters.
For example, you could add a field called Image to your article metadata, as shown below:
Title: I love Python more than music Date: 2013-11-06 10:06 Tags: personal, python Category: Tech Slug: python-je-l-aime-a-mourir Author: Francis Cabrel Image: gemini://franciscabrel.com/images/pythonlove.png
This new metadata will be made available as article.image in your article.gmi template. This would allow you, for example, to specify an image to link to at a specific location:
=> {{ article.image }} Article image
This template will be processed for each page, with output generated according to the `PAGE_SAVE_AS` setting (Default: `pages/{slug}.gmi`). The following variables are available when rendering.
============= ===================================================
Variable Description
============= ===================================================
page The page object to be displayed. You can access its
title, slug, and content.
============= ===================================================
This template will be processed for each tag, with output generated according to the `TAG_SAVE_AS` setting (Default: `tag/{slug}.gmi`). If pagination is active, subsequent pages will by default reside at `tag/{slug}{number}.gmi`.
====================== ===================================================
Variable Description
====================== ===================================================
tag The name of the tag being processed
articles Articles related to this tag
dates Articles related to this tag, but ordered by date,
ascending
articles_paginator A paginator object for the list of articles
articles_page The current page of articles
articles_previous_page The previous page of articles (`None` if page does
not exist)
articles_next_page The next page of articles (`None` if page does
not exist)
dates_paginator A paginator object for the list of articles,
ordered by date, ascending
dates_page The current page of articles, ordered by date,
ascending
dates_previous_page The previous page of articles, ordered by date,
ascending (`None` if page does not exist)
dates_next_page The next page of articles, ordered by date,
ascending (`None` if page does not exist)
page_name TAG_URL where everything after `{slug}` is removed
-- useful for pagination links
====================== ===================================================
This template will be processed for each year of your posts if a path for `YEAR_ARCHIVE_SAVE_AS` is defined, each month if `MONTH_ARCHIVE_SAVE_AS` is defined, and each day if `DAY_ARCHIVE_SAVE_AS` is defined.
=================== ===================================================
Variable Description
=================== ===================================================
period A tuple of the form (`year`, `month`, `day`) that
indicates the current time period. `year` and `day`
are numbers while `month` is a string. This tuple
only contains `year` if the time period is a
given year. It contains both `year` and `month`
if the time period is over years and months and
so on.
period_num A tuple of the form (`year`, `month`, `day`),
as in `period`, except all values are numbers.
=================== ===================================================
You can see an example of how to use `period` in the `"simple"` theme period_archives.gmi template[6]
Detail objects attributes that are available and useful in templates. Not all attributes are listed here, this is a selection of attributes considered useful in a template.
The string representation of an Article is the source_path attribute.
====================== ===================================================
Attribute Description
====================== ===================================================
author The Author of this article.
authors A list of Authors of this article.
category The Category of this article.
content The rendered content of the article.
date Datetime object representing the article date.
date_format Either default date format or locale date format.
default_template Default template name.
in_default_lang Boolean representing if the article is written
in the default language.
lang Language of the article.
locale_date Date formatted by the `date_format`.
metadata Article header metadata `dict`.
save_as Location to save the article page.
slug Page slug.
source_path