ABlog Configuration Options

This post describes ABlog configuration options that go in Sphinx build configuration file.

General options


A path relative to the configuration directory for blog archive pages. Default is 'blog'.


The “title” for the blog, used in acthive pages. Default is 'Blog'.


Base URL for the website, required for generating feeds.


Choose to archive only post titles in collection pages, default is False.

Authors, languages, & locations


A dictionary of author names mapping to author full display names and links. Dictionary keys are what should be used in post directive to refer to the author. Default is {}. Example:

blog_authors = {
    'Ahmet': ('Ahmet Bakan', 'http://ahmetbakan.com'),
    'Durden': ('Tyler Durden',

A dictionary of language code names mapping to full display names and links of these languages. Similar to blog_authors, dictionary keys should be used in post directive to refer to the locations. Default is {}. Example:

blog_languages = {
    'en': ('English', None),

A dictionary of location names mapping to full display names and links of these locations. Similar to blog_authors, dictionary keys should be used in post directive to refer to the locations. Default is {}.


Name of the default author defined in blog_authors. Default is None.


Code name of the default language defined in blog_languages. Default is None.


Name of the default location defined in blog_locations. Default is None.

Updated on 15 September 2014

Added blog_languages and blog_default_language configuration variables.

Post related


Date display format (default is '%b %d, %Y') for published posts that goes as input to datetime.date.strftime().


Date display format in recent posts (default is '%d %B') for published posts that goes as input to datetime.date.strftime().


Number of paragraphs (default is 1) that will be displayed as an excerpt from the post. Setting this 0 will result in displaying no post excerpt in archive pages. This option can be set on a per post basis using post directive option excerpt.

See Post Excerpts and Images for a more detailed discussion.


Index of the image that will be displayed in the excerpt of the post. Default is 0, meaning no image. Setting this to 1 will include the first image, when available, to the excerpt. This option can be set on a per post basis using post directive option image.


Number of seconds (default is 5) that a redirect page waits before refreshing the page to redirect to the post.


When True, post title and excerpt is always taken from the section that contains the post directive, instead of the document. This is the behavior when post is used multiple times in a document. Default is False.


When True, links to the previous and next posts will be rendered at the bottom of the page. Default is True

Blog feeds

Turn feeds on by setting blog_baseurl configuration variable.


Choose to create feeds per author, location, tag, category, and year, default is False.


Choose to display full text in blog feeds, default is False.


Blog feed subtitle, default is None.


Choose to feed only post titles, default is False.


A dictionary of feed filename roots mapping to nested dictionaries of feed entry elements, title, summary, and/or content, and a Jinja2 template which will be used to render the value used for that element in that feed. Templates are rendered with the the following context: - feed_length - feed_fulltext - feed_posts - pagename - feed_title - feed_url - feed - post - post_url - content - feed_entry - title - summary - blog - url - app Default is: {"atom": {}} Example to add an additional feed for posting to social media:

blog_feed_templates = {
      # Use defaults, no templates
      "atom": {},
      # Create content text suitable posting to social media
      "social": {
         # Format tags as hashtags and append to the content
         "content": "{{ title }}{% for tag in post.tags %}"
         " #{{ tag.name|trim()|replace(' ', '') }}"
         "{% endfor %}",

Specify number of recent posts to include in feeds, default is None for all posts.

Updated on 24 August 2014

Added blog_feed_archives, blog_feed_fulltext, blog_feed_subtitle, and post_always_section options.

Updated on 27 November 2014

Added blog_feed_titles, blog_feed_length, and blog_archive_titles options.

Updated on 20 March 2021

Added blog_feed_templates option.

Font awesome

ABlog templates will use of Font Awesome icons if one of the following is set:

URL to Font Awesome .css hosted at Bootstrap CDN or anywhere else. Default: None

Updated on 29 July 2015

fontawesome_link_cdn was a boolean option, and now became a string to enable using desired version of Font Awesome. To get the old behavior, use ‘https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.min.css'.


Sphinx theme already links to Font Awesome. Default: False

Alternatively, you can provide the path to Font Awesome .css with the following configuration option:


Path to Font Awesome .css (default is None) that will be linked to in HTML output by ABlog.

Disqus integration

Of course one cannot think of a blog that doesn’t allow for visitors to comment. You can enable Disqus by setting disqus_shortname and blog_baseurl variables. The reason for requiring blog_baseurl to be specified as of v0.7.2 is to ensure that Disqus associates correct URLs with threads when you serve new posts locally for the first time.


Disqus short name for the website.


Choose to disqus pages that are not posts, default is False.


Choose to disqus posts that are drafts (without a published date), default is False.

Isso integration

An alternative to Disqus, is Isso. Integration is provided by sphinxnotes-isso and the instructions there.

Blog sidebars

Finally, there are seven sidebars you can include in your HTML output using Sphinx html_sidebars configuration option. Sidebars that you see on the left are listed below in the same order:

html_sidebars = {
   '**': [...,
          'ablog/postcard.html', 'ablog/recentposts.html',
          'ablog/tagcloud.html', 'ablog/categories.html',
          'ablog/archives.html', ]

postcard.html provides information regarding the current post. recentposts.html lists most recent five posts. Others provide a link to a archive pages generated for each tag, category, and year. In addition, there are authors.html, languages.html, and locations.html sidebars that link to author and location archive pages.

Command Options

Updated on 07 April 2015

Added ABlog Commands options.


Directory name for build output files. Default is _website.


Directory name for build cache files. Default is .doctrees.


HTML builder, default is dirhtml. Build HTML pages, but with a single directory per document. Makes for prettier URLs (no .html) if served from a webserver. Alternative is html to build one HTML file per document.


GitHub user name used by ablog deploy command. See Deploy to GitHub Pages and Deploy to GitHub Pages for more information.


comments powered by Disqus