ABlog for Sphinx: ABlog Configuration Options

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

General options

blog_path

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

blog_title

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

blog_baseurl

Base URL for the website, required for generating feeds.

blog_archive_titles

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

Authors, languages, & locations

blog_authors

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',
               'https://en.wikipedia.org/wiki/Tyler_Durden'),
}

blog_languages

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),
}

blog_locations

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 {}.

blog_default_author

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

blog_default_language

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

blog_default_location

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

post_date_format

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

post_auto_excerpt

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.

post_auto_image

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.

post_redirect_refresh

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

post_always_section

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.

Blog feeds

Turn feeds on by setting blog_baseurl configuration variable.

blog_feed_archives

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

blog_feed_fulltext

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

blog_feed_subtitle

Blog feed subtitle, default is None.

blog_feed_titles

Choose to feed only post titles, default is False.

blog_feed_templates

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:

System Message: ERROR/3 (/home/docs/checkouts/readthedocs.org/user_builds/ablog/checkouts/latest/docs/manual/ablog-configuration-options.rst, line 164)

Unexpected indentation.

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": "{% for tag in post.tags %}"
        " #"
        "{% endfor %}",
    },
}

blog_feed_length

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:

System Message: INFO/1 (/home/docs/checkouts/readthedocs.org/user_builds/ablog/checkouts/latest/docs/manual/ablog-configuration-options.rst, line 200); backlink

Duplicate implicit target name: “font awesome”.

fontawesome_link_cdn

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'.

fontawesome_included

Sphinx theme already links to Font Awesome. Default: False

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

fontawesome_css_file

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_shortname

Disqus short name for the website.

disqus_pages

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

disqus_drafts

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

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 = {
   '**': [...,
          'postcard.html', 'recentposts.html',
          'tagcloud.html', 'categories.html',
          '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.

ablog_website

Directory name for build output files. Default is _website.

ablog_doctrees

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

ablog_builder

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_pages

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

from Planet Python
via read more