Templating and Themes Support

Ablog, being a Sphinx extension, has highly customizable HTML output. The generated HTML files are based on Sphinx templates. You, or Sphinx themes, can partially or completely override these templates to customize the resulting HTML.

Changed in version 0.11: The Ablog 0.11 has changed and improved the way you can customize templates and themes. Please note that this document describes the new way of customizing templates and themes support.

Blog sidebars

Sidebars are a common way to provide additional information to the reader. There are seven Ablog sidebars you can include in your HTML output using the Sphinx html_sidebars configuration option (in addition to your theme sidebars).

  • ablog/postcard.html provides information regarding the current post (when on a post page).

  • ablog/recentposts.html lists the most recent five posts.

  • ablog/tagcloud.html provides links to archive pages generated for each tag.

  • ablog/category.html, ablog/authors.html, ablog/languages.html, and ablog/locations.html sidebars generate lists of links to respective archive pages with the number of matching posts (e.g., “Manual (14)”, “2023 (8)”, “English (22)”).

For example, the sidebars that you see on this website on the left are:

html_sidebars = {
   "**": [
      # Comes from Alabaster theme
      "about.html",
      "searchfield.html",
      # Ablog sidebars
      "ablog/postcard.html",
      "ablog/recentposts.html",
      "ablog/tagcloud.html",
      "ablog/categories.html",
      "ablog/archives.html",
      "ablog/authors.html",
      "ablog/languages.html",
      "ablog/locations.html",
   ]
}

Styling default Ablog sidebars

Ablog standard sidebars are wrapped in <div> with CSS classes like ablog-sidebar-item ablog__<template_name>, making them easier to style.

For example, the recentposts.html template is wrapped in <div class="ablog-sidebar-item ablog__recentposts">.

See also

Built-in sidebars can be found in the ablog/ folder in the Ablog source code.

If styling is not enough, you can override the Ablog templates in your Sphinx project or in the Sphinx theme.

Partial or complete override of Ablog templates

To control whether Ablog injects its own templates into the Sphinx build, you can use the following conf.py configuration option:

skip_injecting_base_ablog_templates

If set to True, Ablog will not inject its own templates into the Sphinx build. This is useful if you want to completely override Ablog templates in your Sphinx project or in the Sphinx theme. The default is False.

Customizing templates in the project

All Ablog templates are under the ablog/ folder space. For example, ablog/postcard.html. You can override these templates by placing them in the ablog/ folder in your project templates folder.

  1. Add the templates_path option in your conf.py file:

    templates_path = ["_templates"]

  2. Create a folder _templates/ next to your conf.py file. It will hold your custom templates.

  3. Create a folder ablog/ inside the _templates/ folder.

  4. Create a file here with the same name as the template you want to override. For example, postcard.html. This file will be used as a custom template for the sidebar. You can copy the content of the original template from the Ablog source code and modify it as you need.

  5. Optionally: if you want to completely override all Ablog templates, set the skip_injecting_base_ablog_templates option to True, copy all Ablog templates here, and customize them as you need.

Customizing templates in the theme

If you are a Sphinx theme author, you can ship customized Ablog templates in your theme. You can override Ablog templates by placing them in the ablog/ folder in your theme templates, e.g., ablog/postcard.html.

  1. In the theme root (where the theme.toml (or theme.ini in older Sphinx themes) file is), create a folder ablog/.

  2. Create a file here with the same name as the template you want to override. For example, postcard.html.

  3. This file will be used as a custom template for the sidebar. You can copy the content of the original template from the Ablog source code and modify it as you need.

  4. In your theme.toml file, add the following (under the [options] section):

    ablog_inject_templates_after_theme = true

    This will ensure that Ablog templates are injected after the theme templates, so you can override them while still using the Ablog templates as a fallback.

ABlog v0.11 released  

Comments

comments powered by Disqus