Skip to content

Commit c17d644

Browse files
authored
Merge pull request #292 from liborjelinek/main
2 parents 20d5987 + c75a8b7 commit c17d644

File tree

1 file changed

+48
-36
lines changed

1 file changed

+48
-36
lines changed

docs/manual/ablog-configuration-options.rst

+48-36
Original file line numberDiff line numberDiff line change
@@ -20,18 +20,6 @@ General options
2020
A path relative to the configuration directory for blog archive pages.
2121
Default is ``'blog'``.
2222

23-
.. confval:: blog_title
24-
25-
The “title” for the blog, used in acthive pages. Default is ``'Blog'``.
26-
27-
.. confval:: blog_baseurl
28-
29-
Base URL for the website, required for generating feeds.
30-
31-
.. confval:: blog_archive_titles
32-
33-
Choose to archive only post titles in collection pages, default is ``False``.
34-
3523
Authors, languages, & locations
3624
-------------------------------
3725

@@ -48,6 +36,11 @@ Authors, languages, & locations
4836
'https://en.wikipedia.org/wiki/Tyler_Durden'),
4937
}
5038

39+
.. confval:: blog_default_author
40+
41+
Name of the default author defined in :confval:`blog_authors`.
42+
Default is ``None``.
43+
5144
.. confval:: blog_languages
5245

5346
A dictionary of language code names mapping to full display names and links of these languages.
@@ -59,22 +52,17 @@ Authors, languages, & locations
5952
'en': ('English', None),
6053
}
6154

55+
.. confval:: blog_default_language
56+
57+
Code name of the default language defined in :confval:`blog_languages`.
58+
Default is ``None``.
59+
6260
.. confval:: blog_locations
6361

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

68-
.. confval:: blog_default_author
69-
70-
Name of the default author defined in :confval:`blog_authors`.
71-
Default is ``None``.
72-
73-
.. confval:: blog_default_language
74-
75-
Code name of the default language defined in :confval:`blog_languages`.
76-
Default is ``None``.
77-
7866
.. confval:: blog_default_location
7967

8068
Name of the default location defined in :confval:`blog_locations`.
@@ -89,11 +77,11 @@ Post related
8977

9078
.. confval:: post_date_format
9179

92-
Date display format (default is ``'%b %d, %Y'``) for published posts that goes as input to :meth:`datetime.date.strftime`.
80+
Date display format (default is ``'%b %d, %Y'``, e.g., ``12 August 2024``) for published posts that goes as input to :meth:`datetime.date.strftime`.
9381

9482
.. confval:: post_date_format_short
9583

96-
Date display format in recent posts (default is ``'%d %B'``) for published posts that goes as input to :meth:`datetime.date.strftime`.
84+
Date display format in recent posts sidebar (default is ``'%d %B'``, e.g., ``12 October``) for published posts that goes as input to :meth:`datetime.date.strftime`.
9785

9886
.. confval:: post_auto_excerpt
9987

@@ -130,6 +118,20 @@ Blog feeds
130118

131119
Turn feeds on by setting :confval:`blog_baseurl` configuration variable.
132120

121+
.. confval:: blog_baseurl
122+
123+
Base URL for the website, turns on generating feeds. E.g., ``https://ablog.readthedocs.io``.
124+
125+
Then optionally set the following:
126+
127+
.. confval:: blog_title
128+
129+
The “title” for the blog, used in feeds title (not archive web pages title). Default is ``'Blog'``.
130+
131+
.. confval:: blog_archive_titles
132+
133+
Choose to archive only post titles in collection pages, default is ``False``.
134+
133135
.. confval:: blog_feed_archives
134136

135137
Choose to create feeds per author, location, tag, category, and year, default is ``False``.
@@ -268,24 +270,34 @@ Integration is provided by `sphinxnotes-isso`_ and the instructions there.
268270
Blog sidebars
269271
-------------
270272

271-
Finally, there are seven sidebars you can include in your HTML output using Sphinx_ :confval:`html_sidebars` configuration option.
272-
Sidebars that you see on the left are listed below in the same order:
273+
There are seven Ablog sidebars you can include in your HTML output using Sphinx_ :confval:`html_sidebars` configuration option (in addition to your theme sidebars).
274+
275+
- ``alog/postcard.html`` provides information regarding the current post (when on a post page)
276+
- ``alog/recentposts.html`` lists most recent five posts.
277+
- ``alog/tagcloud.html`` provides a links to a archive pages generated for each tag
278+
- ``alog/category.html``, ``alog/authors.html``, ``alog/languages.html``, and ``alog/locations.html`` sidebars generates list of link to respective archive pages with number of matching posts (e.g., "Manual 14)", "2023 (8)", "English (22")).
279+
280+
For example, sidebars that you see on this website on the left are:
273281

274282
.. code-block:: python
275283
276284
html_sidebars = {
277-
'**': [...,
278-
'ablog/postcard.html', 'ablog/recentposts.html',
279-
'ablog/tagcloud.html', 'ablog/categories.html',
280-
'ablog/archives.html', ]
285+
"**": [
286+
# Comes from Alabaster theme
287+
"about.html",
288+
"searchfield.html",
289+
# Ablog sidebards
290+
"ablog/postcard.html",
291+
"ablog/recentposts.html",
292+
"ablog/tagcloud.html",
293+
"ablog/categories.html",
294+
"ablog/archives.html",
295+
"ablog/authors.html",
296+
"ablog/languages.html",
297+
"ablog/locations.html",
298+
]
281299
}
282300
283-
284-
:file:`postcard.html` provides information regarding the current post.
285-
:file:`recentposts.html` lists most recent five posts.
286-
Others provide a link to a archive pages generated for each tag, category, and year.
287-
In addition, there are ``authors.html``, ``languages.html``, and ``locations.html`` sidebars that link to author and location archive pages.
288-
289301
Command Options
290302
---------------
291303

0 commit comments

Comments
 (0)