Posting and Listing

This post describes post, update, and postlist directives.

Posting

Any page in a Sphinx project can be converted to a post using the following directive:

.. post::

All possible directive options are shown below:

.. post:: 15 Apr, 2013
   :tags: tips, ablog, directive
   :category: Example, How To
   :author: Ahmet, Durden
   :location: Pittsburgh, SF
   :redirect: blog/old-page-name-for-the-post
   :excerpt: 2
   :image: 1
   :nocomments:

Drafts & Posts

Posts without dates or with future dates are considered as drafts and are published only in Drafts archive page.

Posts with dates that are older than the day Sphinx project is built are published in Posts page.

Post date format must follow the format specified with post_date_format configuration option.

Tags & Categories

You can specify multiple tags and categories by separating them with commas. Posts will be listed in archive pages generated for each unique tag and category.

Authors, Languages, & Locations

Likewise, you can specify authors, languages, and locations of a post using :author:, :language:, and :location: options. All of these option names are in their singular form, but multiple values separated by commas are accepted.

Using blog_authors, blog_languages, and blog_locations configuration variables, you can also provide home pages and/or full display names of authors, languages, and locations, which will be displayed in archive pages generated for all unique authors, languages, and locations.

Redirections

You can make ABlog create pages that will redirect to current post using :redirect: option. It takes a comma separated list of paths, relative to the root folder. The redirect page waits for post_redirect_refresh seconds before redirection occurs.

Disable comments

You can disable comments for the current post using the :nocomments: option. Currently there is no way to disable comments in a specific page.

Excerpts & Images

By default, ABlog uses the first paragraph of a page as post excerpt. You can change this behavior and also add an image to the excerpt. To find out how, see Post Excerpts and Images.

Update Notes

.. update::

Update in a post can be noted anywhere in the post as follows:

.. update:: 20 Apr, 2014

   Added :rst:dir:`update` directive and :ref:`posting-sections`
   section. Also revised the text here and there.

Update date format must follow the format specified with post_date_format configuration option.

Update directive renders like the updates that are at the end of this post.

Posting Sections

post directive can be used multiple times in a single page to create multiple posts of different sections of the document.

When post is used more than once, post titles and excerpts are extracted from the sections that contain the directives. This behavior can also be set as the default behavior using post_always_section configuration options.

Some caveats and differences from posting a document once are:

  • Next and previous links at the bottom will only regard the first post in the document.
  • Information displayed on the sidebar will belong to the first post.
  • References for section posts is not automatically created. Labels for cross-referencing needs to be created manually, e.g. .. _posting-sections. See Cross-referencing syntax for details.

Multiple use of post may be suitable for major additions to a previous post. For minor changes, update directive may be preferred.

Listing

A list of posts can be displayed in any page using the following directive:

.. postlist::

Following example display all the options the directive takes:

.. postlist:: 5
   :author: Ahmet
   :category: Manual
   :location: Pittsburgh
   :language: en
   :tags: tips
   :date: %A, %B %d, %Y
   :format: {title} by {author} on {date}
   :list-style: circle
   :excerpts:
   :sort:

This will result in a bullet list of up to 5 posts (default is all) authored by Ahmet Bakan in English when he was in Pittsburgh, PA and posted in Manual with tags tips. Posts will be in :sort:ed to appear in chronological order and listed with their :excerpts:. Here are those posts:

  • Cross-referencing Blog Pages by Ahmet Bakan on Sunday, May 11, 2014

    ABlog creates references to all post and archive pages. Posts can be cross-referenced using the name of the file, or when the file is named index, the name of the folder that contains the file.

When no options are given all posts will be considered and they will be ordered by recency. Also, note that if the current post is one of the most recent posts, it will be omitted.

Updated on Aug 20, 2014

Added update directive and Posting Sections section. Also revised the text here and there.

Updated on Sep 15, 2014

  • post directive has :language: option.
  • postlist directive takes arguments to filter posts.

Updated on Mar 28, 2015

Added :excerpts: option to postlist to list posts with their excerpts.

Updated on Apr 14, 2015

Added :list-style: option to postlist to control bullet list style. circle, disk, and none (default) are recognized.

Comments

comments powered by Disqus