` can be given as page-level front-matter as well.
106 |
107 | .. admonition:: Automatically detect blog posts with a ``glob`` pattern
108 | :class: tip
109 |
110 | Instead of adding ``blogpost: true`` to each page, you may also provide a pattern (or list of patterns) in your ``conf.py`` file using the ``blog_post_pattern`` option.
111 | Any filenames that match this pattern will be treated as blog posts (and page front-matter will be used to classify the blog post).
112 | For example, the following configuration would match all ``rst`` files in the ``posts/`` folder:
113 |
114 | .. code-block:: python
115 |
116 | blog_post_pattern = "posts/*.rst"
117 |
118 | and this configuration will match all blog posts that match either ``rst`` or ``md``:
119 |
120 | .. code-block:: python
121 |
122 | blog_post_pattern = ["posts/*.rst", "posts/*.md"]
123 |
124 | .. _posting-sections:
125 |
126 | Posting Sections
127 | ----------------
128 |
129 | .. post:: Aug 20, 2014
130 | :tags: directive
131 | :category: Manual
132 | :location: SF
133 | :author: Ahmet
134 |
135 | :rst:dir:`post` directive can be used multiple times in a single page to create multiple posts of different sections of the document.
136 |
137 | When :rst:dir:`post` is used more than once, post titles and excerpts are extracted from the sections that contain the directives.
138 | This behavior can also be set as the default behavior using :confval:`post_always_section` configuration options.
139 |
140 | Some caveats and differences from posting a document once are:
141 |
142 | * Next and previous links at the bottom will only regard the first post in the document.
143 | * Information displayed on the sidebar will belong to the first post.
144 | * References for section posts is not automatically created. Labels for cross-referencing needs to be created manually, e.g., ``.. _posting-sections``. See :ref:`xref-syntax` for details.
145 |
146 | Multiple use of :rst:dir:`post` may be suitable for major additions to a previous post. For minor changes, :rst:dir:`update` directive may be preferred.
147 |
148 | Listing
149 | -------
150 |
151 | A list of posts can be displayed in any page using the following directive:
152 |
153 | .. rst:directive:: postlist
154 |
155 | Following example display all the options the directive takes::
156 |
157 | .. postlist:: 5
158 | :author: Ahmet
159 | :category: Manual
160 | :location: Pittsburgh
161 | :language: en
162 | :tags: tips
163 | :date: %A, %B %d, %Y
164 | :format: {title} by {author} on {date}
165 | :list-style: circle
166 | :excerpts:
167 | :sort:
168 | :expand: Read more ...
169 |
170 | This will result in a bullet list of up to 5 posts (default is all) authored by `:ref:`author-ahmet`` in `:ref:`language-en`` when he was in `:ref:`location-pittsburgh`` and posted in `:ref:`category-manual`` with tags `:ref:`tag-tips``.
171 | Posts will be in ``:sort:``\ed to appear in chronological order and listed with their ``:excerpts:``.
172 | Here are those posts:
173 |
174 | .. postlist:: 5
175 | :author: Ahmet
176 | :category: Manual
177 | :location: Pittsburgh
178 | :language: en
179 | :tags: tips
180 | :date: %A, %B %d, %Y
181 | :format: {title} by {author} on {date}
182 | :list-style: circle
183 | :excerpts:
184 | :sort:
185 | :expand: Read more ...
186 |
187 | When no options are given all posts will be considered and they will be ordered by recency.
188 | Also, note that if the current post is one of the most recent posts, it will be omitted.
189 |
190 | .. update:: Aug 21, 2014
191 |
192 | Added :rst:dir:`update` directive and
193 | :ref:`posting-sections` section.
194 | Also revised the text here and there.
195 |
196 | .. update:: Sep 15, 2014
197 |
198 | * :rst:dir:`post` directive has ``:language:`` option.
199 | * :rst:dir:`postlist` directive takes arguments to filter posts.
200 |
201 | .. update:: Mar 28, 2015
202 |
203 | Added ``:excerpts:`` option to :rst:dir:`postlist` to list posts with their excerpts.
204 |
205 | .. update:: Apr 14, 2015
206 |
207 | Added ``:list-style:`` option to :rst:dir:`postlist` to control bullet list style.
208 | *circle*, *disc*, and *none* (default) are recognized.
209 |
210 | .. update:: May 25, 2021
211 |
212 | Added ``:expand:`` option to :rst:dir:`postlist` to add a call to action to continue reading the post.
213 |
--------------------------------------------------------------------------------
/docs/manual/templates-themes.rst:
--------------------------------------------------------------------------------
1 | Templating and Themes Support
2 | =============================
3 |
4 | .. post:: Oct 26, 2024
5 | :tags: themes
6 | :category: Manual
7 | :author: Libor
8 |
9 | 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.
10 |
11 | .. _Sphinx templates: https://www.sphinx-doc.org/en/master/development/html_themes/templating.html
12 |
13 | .. versionchanged:: 0.11
14 | The :doc:`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.
15 |
16 | .. _sidebars:
17 |
18 | Blog sidebars
19 | -------------
20 |
21 | 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_ :confval:`html_sidebars` configuration option (in addition to your theme sidebars).
22 |
23 | - ``ablog/postcard.html`` provides information regarding the current post (when on a post page).
24 | - ``ablog/recentposts.html`` lists the most recent five posts.
25 | - ``ablog/tagcloud.html`` provides links to archive pages generated for each tag.
26 | - ``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)").
27 |
28 | For example, the sidebars that you see on this website on the left are:
29 |
30 | .. code-block:: python
31 |
32 | html_sidebars = {
33 | "**": [
34 | # Comes from Alabaster theme
35 | "about.html",
36 | "searchfield.html",
37 | # Ablog sidebars
38 | "ablog/postcard.html",
39 | "ablog/recentposts.html",
40 | "ablog/tagcloud.html",
41 | "ablog/categories.html",
42 | "ablog/archives.html",
43 | "ablog/authors.html",
44 | "ablog/languages.html",
45 | "ablog/locations.html",
46 | ]
47 | }
48 |
49 | Styling default Ablog sidebars
50 | ------------------------------
51 |
52 | Ablog standard sidebars are wrapped in ```` with CSS classes like :samp:`ablog-sidebar-item ablog__{}`, making them easier to style.
53 |
54 | For example, the ``recentposts.html`` template is wrapped in ``
Comments
26 | 27 | 44 | 50 | 51 | comments powered by Disqus 52 | 53 |