python/ablog
1
0
Fork 0
Code Issues Activity

Adding upstream version 0.11.12.

Browse source 
Signed-off-by: Daniel Baumann <daniel@debian.org>
This commit is contained in:
Daniel Baumann 2025-02-10 17:15:56 +01:00
parent f89f073565
commit 2f2c7f3767
Signed by: daniel
GPG key ID: FBB4F0E80A80222F
146 changed files with 9553 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

178
docs/manual/ablog-commands.rst Normal file
View file

@ -0,0 +1,178 @@
.. _commands:
ABlog Commands
==============
.. post:: Mar 1, 2015
:tags: config, commands
:author: Ahmet, Mehmet
:category: Manual
:location: SF
``ablog`` commands are for streamlining blog operations, i.e. building, serving, and viewing blog pages, as well as starting a new blog::
$ ablog
usage: ablog [-h] [-v] {start,build,clean,serve,post,deploy} ...
ABlog for blogging with Sphinx
optional arguments:
-h, --help show this help message and exit
-v, --version print ABlog version and exit
subcommands:
{start,build,clean,serve,post,deploy}
start start a new blog project
build build your blog project
clean clean your blog build files
serve serve and view your project
post create a blank post
deploy deploy your website build files
See 'ablog <command> -h' for more information on a specific command.
.. contents:: Here are all the things you can do:
:local:
:backlinks: top
.. _start:
Start a New Project
-------------------
``ablog start`` command is for quickly setting up a blog project.
See :ref:`quick-start` for how it works and what it prepares for you::
$ ablog start -h
usage: ablog start [-h]
Start a new blog project by answering a few questions. You will end up with a
configuration file and sample pages.
optional arguments:
-h, --help show this help message and exit
.. _build:
Build your Website
------------------
Running ``ablog build`` in your project folder builds your website HTML pages::
$ ablog build -h
usage: ablog build [-h] [-a] [-b BUILDER] [-s SOURCEDIR] [-w WEBSITE]
[-d DOCTREES] [-T] [-P]
Path options can be set in conf.py. Default values of paths are relative to
conf.py.
optional arguments:
-h, --help show this help message and exit
-a write all files; default is to only write new and changed
files
-b BUILDER builder to use, default `ablog_builder` or dirhtml
-s SOURCEDIR root path for source files, default is path to the folder that
contains conf.py
-w WEBSITE path for website, default is _website when `ablog_website` is
not set in conf.py
-d DOCTREES path for the cached environment and doctree files, default
.doctrees when `ablog_doctrees` is not set in conf.py
-T show full traceback on exception
-P run pdb on exception
Serve and View Locally
----------------------
Running ``ablog serve``, after building your website, will start a Python server and open up browser tab to view your website::
$ ablog serve -h
usage: ablog serve [-h] [-w WEBSITE] [-p PORT] [-n] [-r] [--patterns]
Serve options can be set in conf.py. Default values of paths are relative to
conf.py.
optional arguments:
-h, --help show this help message and exit
-w WEBSITE path for website, default is _website when `ablog_website` is
not set in conf.py
-p PORT port number for HTTP server; default is 8000
-n do not open website in a new browser tab
-r rebuild when a file matching patterns change or get added
--patterns patterns for triggering rebuilds
.. _deploy:
Deploy to GitHub Pages
----------------------
Running ``ablog deploy`` will push your website to GitHub::
$ ablog deploy -h
usage: ablog deploy [-h] [-w WEBSITE] [-p REPODIR] [-g GITHUB_PAGES]
[-m MESSAGE] [-f] [--push-quietly]
[--github-branch GITHUB_BRANCH] [--github-ssh]
[--github-token GITHUB_TOKEN] [--github-url GITHUB_URL]
Path options can be set in conf.py. Default values of paths are relative to
conf.py.
options:
-h, --help show this help message and exit
-w WEBSITE path for website, default is _website when
`ablog_website` is not set in conf.py
-p REPODIR path to the location of repository to be deployed, e.g.
`../username.github.io`, default is folder containing
`conf.py`
-g GITHUB_PAGES GitHub username for deploying to GitHub pages
-m MESSAGE commit message
-f overwrite last commit, i.e. `commit --amend; push -f`
--push-quietly be more quiet when pushing changes
--github-branch GITHUB_BRANCH
Branch to use. Default is 'master'.
--github-ssh use ssh when cloning website
--github-token GITHUB_TOKEN
environment variable name storing GitHub access token
--github-url GITHUB_URL
Custom GitHub URL. Useful when multiple accounts are
configured on the same machine. Default is:
git@github.com
Create a Post
-------------
Finally, ``ablog post`` will make a new post template file::
$ ablog post -h
usage: ablog post [-h] [-t TITLE] filename
positional arguments:
filename filename, e.g. my-nth-post (.rst appended)
optional arguments:
-h, --help show this help message and exit
-t TITLE post title; default is formed from filename
Clean Build Files
-----------------
In case you needed, running ``ablog clean`` will remove build files and do a deep clean with ``-D`` option::
$ ablog clean -h
usage: ablog clean [-h] [-d DOCTREES] [-w WEBSITE] [-D]
Path options can be set in conf.py. Default values of paths are relative to
conf.py.
optional arguments:
-h, --help show this help message and exit
-d DOCTREES path for the cached environment and doctree files, default
.doctrees when `ablog_doctrees` is not set in conf.py
-w WEBSITE path for website, default is _website when `ablog_website` is
not set in conf.py
-D deep clean, remove cached environment and doctree files
.. update:: Apr 7, 2015
Added ``ablog clean`` and ``ablog deploy`` commands.

291
docs/manual/ablog-configuration-options.rst Normal file
View file

@ -0,0 +1,291 @@
.. _config:
ABlog Configuration Options
===========================
.. post:: May 10, 2014
:tags: config
:author: Ahmet
:category: Manual
:location: Pittsburgh
This post describes ABlog configuration options that go in :ref:`Sphinx build configuration file <sphinx:build-config>`.
General options
---------------
.. confval:: blog_path
A path relative to the configuration directory for blog archive pages.
Default is ``'blog'``.
Authors, languages, & locations
-------------------------------
.. confval:: 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'),
}
.. confval:: blog_default_author
Name of the default author defined in :confval:`blog_authors`.
Default is ``None``.
.. confval:: blog_languages
A dictionary of language code names mapping to full display names and links of these languages.
Similar to :confval:`blog_authors`, dictionary keys should be used in ``post`` directive to refer to the locations.
Default is ``{}``.
Example::
blog_languages = {
'en': ('English', None),
}
.. confval:: blog_default_language
Code name of the default language defined in :confval:`blog_languages`.
Default is ``None``.
.. confval:: blog_locations
A dictionary of location names mapping to full display names and links of these locations.
Similar to :confval:`blog_authors`, dictionary keys should be used in ``post`` directive to refer to the locations.
Default is ``{}``.
.. confval:: blog_default_location
Name of the default location defined in :confval:`blog_locations`.
Default is ``None``.
.. update:: Sep 15, 2014
Added :confval:`blog_languages` and :confval:`blog_default_language` configuration variables.
Post related
------------
.. confval:: post_date_format
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`.
.. confval:: post_date_format_short
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`.
.. confval:: 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 :rst:dir:`post` directive option ``excerpt``.
See :ref:`post-excerpts-and-images` for a more detailed discussion.
.. confval:: 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 :rst:dir:`post` directive option ``image``.
.. confval:: post_redirect_refresh
Number of seconds (default is ``5``) that a redirect page waits before refreshing the page to redirect to the post.
.. confval:: post_always_section
When ``True``, post title and excerpt is always taken from the section that contains the :rst:dir:`post` directive, instead of the document.
This is the behavior when :rst:dir:`post` is used multiple times in a document.
Default is ``False``.
.. confval:: post_show_prev_next
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 :confval:`blog_baseurl` configuration variable.
.. confval:: blog_baseurl
Base URL for the website, turns on generating feeds. E.g., ``https://ablog.readthedocs.io``.
Then optionally set the following:
.. confval:: blog_title
The “title” for the blog, used in feeds title (not archive web pages title). Default is ``'Blog'``.
.. confval:: blog_archive_titles
Choose to archive only post titles in collection pages, default is ``False``.
.. confval:: blog_feed_archives
Choose to create feeds per author, location, tag, category, and year, default is ``False``.
.. confval:: blog_feed_fulltext
Choose to display full text in blog feeds, default is ``False``.
.. confval:: blog_feed_subtitle
Blog feed subtitle, default is ``None``.
.. confval:: blog_feed_titles
Choose to feed only post titles, default is ``False``.
.. confval:: 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::
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 %}",
},
}
.. confval:: blog_feed_length
Specify number of recent posts to include in feeds, default is ``None`` for all posts.
.. update:: Aug 24, 2014
Added :confval:`blog_feed_archives`, :confval:`blog_feed_fulltext`, :confval:`blog_feed_subtitle`, and :confval:`post_always_section` options.
.. update:: Nov 27, 2014
Added :confval:`blog_feed_titles`, :confval:`blog_feed_length`, and :confval:`blog_archive_titles` options.
.. update:: Mar 20, 2021
Added :confval:`blog_feed_templates` option.
.. _fa:
.. _Jinja2: https://jinja.palletsprojects.com/
.. _font-awesome:
Font awesome
------------
ABlog templates will use of `Font Awesome`_ icons if one of the following is set:
.. _Font Awesome: https://fontawesome.com/
.. confval:: fontawesome_link_cdn
URL to `Font Awesome`_ :file:`.css` hosted at `Bootstrap CDN`_ or anywhere else.
Default: ``None``
.. _Bootstrap CDN: https://www.bootstrapcdn.com/fontawesome/
.. update:: Jul 29, 2015
:confval:`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'``.
.. confval:: fontawesome_included
Sphinx_ theme already links to `Font Awesome`_.
Default: ``False``
Alternatively, you can provide the path to `Font Awesome`_ :file:`.css` with the following configuration option:
.. confval:: fontawesome_css_file
Path to `Font Awesome`_ :file:`.css` (default is ``None``) that will be linked to in HTML output by ABlog.
.. _disqus-integration:
Disqus integration
------------------
Of course one cannot think of a blog that doesn't allow for visitors to comment.
You can enable Disqus_ by setting :confval:`disqus_shortname` and :confval:`blog_baseurl` variables.
The reason for requiring :confval:`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.
.. confval:: disqus_shortname
Disqus_ short name for the website.
.. confval:: disqus_pages
Choose to disqus pages that are not posts, default is ``False``.
.. confval:: disqus_drafts
Choose to disqus posts that are drafts (without a published date), default is ``False``.
Isso integration
----------------
An alternative to Disqus, is `Isso <https://isso-comments.de/>`__.
Integration is provided by `sphinxnotes-isso`_ and the instructions there.
.. _sphinxnotes-isso: https://sphinx-notes.github.io/isso/
Command Options
---------------
.. update:: Apr 7, 2015
Added :ref:`commands` options.
.. confval:: ablog_website
Directory name for build output files. Default is ``_website``.
.. confval:: ablog_doctrees
Directory name for build cache files. Default is ``.doctrees``.
.. confval:: 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.
.. confval:: github_pages
GitHub user name used by ``ablog deploy`` command.
See :ref:`deploy` and :ref:`deploy-to-github-pages` for more information.

56
docs/manual/ablog-i18n.rst Normal file
View file

@ -0,0 +1,56 @@
ABlog Internationalization
==========================
.. post:: Aug 30, 2014
:tags: i18n
:category: Manual
:author: Luc, Ahmet
:language: Chinese
ABlog automatically generates certain labels like :ref:`blog-posts` and :ref:`blog-categories`.
If these labels appear in English on your blog although you specified another language, then this page is for you.
ABlog needs your help for translation of these labels.
Translation process involves the following steps:
* Update translatable messages:
Execute extract_messages_ each time a translatable message text is changed or added::
$ python setup.py extract_messages -o ablog/locales/sphinx.pot
...
This will create or update :file:`ablog/locales/sphinx.pot` file, the central messages catalog used by the different translations.
Either:
* Create new translation catalog:
Execute init_catalog_ once for each *new* language, e.g.::
$ python setup.py init_catalog -l de -i ablog/locales/sphinx.pot -o ablog/locales/de/LC_MESSAGES/sphinx.po
This will create a file :file:`ablog/locales/de/LC_MESSAGES/sphinx.po` in which translations needs to be placed.
* Update translation catalog:
Execute update_catalog_ for each *existing* language, e.g.::
$ python setup.py update_catalog -l de -i ablog/locales/sphinx.pot -o ablog/locales/de/LC_MESSAGES/sphinx.po
This will update file :file:`ablog/locales/de/LC_MESSAGES/sphinx.po` where translations of new text needs to be placed.
Finally:
* Compile catalogs:
Execute compile_catalog_ for each existing language, e.g::
$ python setup.py compile_catalog --directory ablog/locales/ --domain sphinx --locale de
If you remove ``--locale de`` then all catalogs will be compiled.
.. _extract_messages: https://babel.pocoo.org/en/latest/setup.html#extract-messages
.. _init_catalog: https://babel.pocoo.org/en/latest/setup.html#init-catalog
.. _update_catalog: https://babel.pocoo.org/en/latest/setup.html#update-catalog
.. _compile_catalog: https://babel.pocoo.org/en/latest/setup.html#compile-catalog

126
docs/manual/ablog-quick-start.rst Normal file
View file

@ -0,0 +1,126 @@
.. _quick-start:
ABlog Quick Start
=================
.. post:: Mar 1, 2015
:tags: config, tips
:author: Mehmet, Ahmet
:category: Manual
:location: SF
This short walk through of blogging work flow assumes that you have already installed ABlog. If not, see :ref:`installation` guide.
*Note that this post is a working draft. Feel free to revise it on GitHub.*
Start a Project
---------------
To start a new project, run ``ablog start`` command in a directory where you want to keep your project source files.
This command will ask you a few questions and create the following files:
* :file:`conf.py` that contains project configuration for building HTML pages.
* :file:`first-post.rst`, a blog post example.
* :file:`index.rst` that contains content for the *landing* page of your website.
* :file:`about.rst`, another non-post page example.
Build and View
--------------
With no further delay, let's see what your project will look like.
First run ``ablog build``, in your project folder, to have HTML pages built in :file:`_website` folder.
Then, call ``ablog serve`` to view them in your default web browser.
See :ref:`commands` for more information about these commands.
Your landing page is built from :file:`index.rst` and contains links to your first post and about page.
Take a look at :file:`index.rst` for some tips on navigation links within the project.
Write Content
-------------
If you are new to Sphinx_ and reStructuredText markup language, you might find `reStructuredText Primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__ useful.
Pages
^^^^^
Pages in your project are :file:`.rst` files that are only a :rst:dir:`post` directive short of becoming blog posts.
To make regular pages accessible from the navigation bar, you need to list them in a :rst:dir:`toctree`.
This is shown for *about* page into :file:`index.rst`.
Posts
^^^^^
You can convert any page to a post with a :rst:dir:`post` directive.
ABlog will take care of listing posts in specified archives and sidebars.
Blog posts
^^^^^^^^^^
You can start new blog posts with either a front-matter or a directive using ABlog.
Simply use something based on the following template as the front-matter::
:blogpost: true
:date: January 1, 2020
:author: A. Author
:location: World
:category: Blog
:language: English
:tags: blog
Simply use something based on the following template as the directive for ABlog::
.. post:: January 1, 2020
:author: A. Author
:location: World
:category: Blog
:language: English
:tags: blog
For more information, see :ref:`posting-directive` and :ref:`posting-front-matter`.
Comments
--------
You can enable comments in your website by creating a Disqus_ account and obtaining a unique identifier, i.e. :confval:`disqus_shortname`.
See :ref:`disqus-integration` for configuration options.
Analytics
---------
ABlog uses Alabaster_ theme by default. You can use theme options to set your `Google Analytics`__ identifier to enable tracking.
__ https://www.google.com/analytics/
Configuration
-------------
There are four major groups of configuration options that can help you customize how your website looks:
* :ref:`config` - add blog authors, post locations and languages to your blog, adjust archive and feed content, etc.
* `General configuration <https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration>`__ and `project information <https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information>`__
* :ref:`html-options` - configure appearance of your website.
* Alabaster_ theme options - link to your GitHub account and project, set up tracking, etc.
Other Folders
-------------
You might have noticed that your project contains three folders that we have not mention yet.
Here they are:
* :file:`_static` is for keeping image, :file:`.js`, and :file:`.css` files.
:confval:`html_static_path` Sphinx option for more information.
* :file:`_templates` is for custom HTML templates.
See :confval:`templates_path` for more information.
* :file:`.doctree` folder, created after build command is called, is where Sphinx_ stores the state of your project.
Files in this folder saves time when you rebuild your project.

20
docs/manual/api.rst Normal file
View file

@ -0,0 +1,20 @@
.. api:
ABlog API
=========
.. post:: Feb 17, 2018
:tags: api
:author: Nabil Freij
:category: Manual
:location: World
.. automodapi:: ablog
.. automodapi:: ablog.blog
.. automodapi:: ablog.commands
.. automodapi:: ablog.post
.. automodapi:: ablog.start

47
docs/manual/cross-referencing-blog-pages.rst Normal file
View file

@ -0,0 +1,47 @@
Cross-referencing Blog Pages
============================
.. post:: May 11, 2014
:tags: tips, Sphinx
:category: Manual
:location: Pittsburgh
:author: Ahmet
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 :file:`index`, the name of the folder that contains the file.
This page, :ref:`cross-referencing-blog-pages`, for example is referenced as ``:ref:`cross-referencing-blog-pages``` using :rst:role:`ref` role.
When posts have long file names, it may be inconvenient to use them repeatedly for cross-referencing.
An alternative that Sphinx_ offers is creating your own short and unique labels for cross-referencing to posts. See :ref:`xref-syntax` for details.
.. _archives:
Archive pages
-------------
Archive pages, on the other hand, can be cross-referenced by combining archive type and archive name as follows:
============== ========================== ===============================
Archive Example reStructured Text
============== ========================== ===============================
Posts :ref:`blog-posts` ``:ref:`blog-posts```
Drafts :ref:`blog-drafts` ``:ref:`blog-drafts```
Blog Feed :ref:`blog-feed` ``:ref:`blog-feed```
Author :ref:`author-ahmet` ``:ref:`author-ahmet```
Language :ref:`language-en` ``:ref:`language-en```
Location :ref:`location-pittsburgh` ``:ref:`location-pittsburgh```
============== ========================== ===============================
Following archive pages list all posts by grouping them:
============== ========================== ===============================
Archive Example reStructured Text
============== ========================== ===============================
By tag :ref:`blog-tags` ``:ref:`blog-tags```
By author :ref:`blog-authors` ``:ref:`blog-authors```
By language :ref:`blog-languages` ``:ref:`blog-languages```
By location :ref:`blog-locations` ``:ref:`blog-locations```
By category :ref:`blog-categories` ``:ref:`blog-categories```
By archive :ref:`blog-archives` ``:ref:`blog-archives```
============== ========================== ===============================

41
docs/manual/deploy-to-github-pages.rst Normal file
View file

@ -0,0 +1,41 @@
Deploy to GitHub Pages
======================
.. post:: Apr 07, 2015
:tags: deploy
:author: Ahmet
:category: Manual
:location: SF
If you are looking for a place to publish your blog, `GitHub Pages`__ might be the place for you.
__ https://pages.github.com/
Assuming that you have a GitHub account, here are what you need to do to get published:
1. Head over to GitHub_ and create a new repository named ``username.github.io``, where username is your username (or organization name) on GitHub.
2. (optional) If you followed the link, you might as well give a star to ABlog ;)
3. Set :confval:`github_pages` configuration variable in :file:`conf.py` file.
4. Run ``ablog build`` in your project folder.
5. Run ``ablog deploy``. This command will
i. clone your GitHub pages repository to project folder,
ii. copy all files from build folder (:file:`_website`) to :file:`username.github.io`,
iii. add and commit copied files,
iv. add `.nojekyll <https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#troubleshooting-publishing-from-a-branch>`_
file, since this ain't no Jekyll_
v. and finally push the changes to publish.
Let us know how this works for you!
.. _Jekyll: https://jekyllrb.com/

10
docs/manual/external-post.rst Normal file
View file

@ -0,0 +1,10 @@
:blogpost: true
:date: September 01, 2021
:author: Chris
:category: Manual
:external_link: https://www.sphinx-doc.org/en/master/
External post
=============
This text will be in auto-generated post previews, but links to the post will direct to ``external_link``.

33
docs/manual/forever-draft.rst Normal file
View file

@ -0,0 +1,33 @@
Draft Example
=============
.. post::
:tags: draft
:category: Manual
As the title suggests, this is a draft example and shall remain so until the end of time or internet.
How do you draft a post?
------------------------
Just indicate that the page is a post using :rst:dir:`post` directive, but do not provide give a published date:
.. code-block:: rst
.. post::
:tags: draft
:category: Manual
You can still label a post you are drafting with tags and categories, but the post will not be listed in corresponding archive pages until it is published.
How can you see a list of drafts?
---------------------------------
See :ref:`blog-drafts` archive page, which can be referred to as ``:ref:`blog-drafts```.
Why would you make a post draft?
--------------------------------
Let's say you are using Disqus_ on your website, and allowing non-post pages to be discussed as well, but you don't want a draft to be discussed before it is published.
By adding :rst:dir:`post` directive without published date and keeping configuration variable :confval:`disqus_drafts` as ``False``, you can achieve that.

BIN
docs/manual/images/notebook_cells.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 13 KiB

56
docs/manual/markdown.md Normal file
View file

@ -0,0 +1,56 @@
---
blogpost: true
date: Oct 10, 2020
author: Nabil Freij
location: World
category: Manual
language: English
---
# Markdown Support
ABlog can support markdown pages using [myst-parser](https://pypi.org/project/myst-parser/).
This page is a markdown file underneath.
You will need to do a few things to get setup.
1. Install [myst-parser](https://pypi.org/project/myst-parser/)
2. Add these options to your config, `conf.py`
```python
extensions = [
...
"myst_parser",
...
]
myst_update_mathjax = False
```
Then use the new blogpost metadata format (with a slight twist):
```
---
blogpost: true
date: Oct 10, 2020
author: Nabil Freij
location: World
category: Manual
language: English
---
```
Notice here we do not have a ":" at the start since the markdown metadata format is different from rst.
Please be aware that adding "myst-parser" will mean it will read all markdown files and try to parse them.
You will need to use the following in your `conf.py` to prevent this:
```python
exclude_patterns = [
"posts/*/.ipynb_checkpoints/*",
".github/*",
".history",
"github_submodule/*",
"LICENSE.md",
"README.md",
]
```

81
docs/manual/notebook_support.ipynb Normal file
View file

@ -0,0 +1,81 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Jupyter Notebook Posting"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
".. post:: 27 Oct 2018\n",
" :author: Nabil Freij, Second Author\n",
" :tags: posting\n",
" :category: Manual"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To add support for Notebooks to your Ablog instance, you need to configure your `docs/conf.py` (or wherever your `conf.py` is located.\n",
"\n",
"You will need to add\n",
"\n",
"```\n",
" extensions = [..., 'nbsphinx', ...]\n",
" exclude_patterns = ['docs/manual/.ipynb_checkpoints/*'] (To exclude the notebook autosaves)\n",
"```\n",
"\n",
"You will need to install [nbsphinx](https://nbsphinx.readthedocs.io/) either from `Anaconda` or `pip`. You might need to install [ipython](https://ipython.org/) to make sure the notebook can be run."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Within the notebook you need to make sure the cells are in this order: Titlte cell, post cell. So for this notebook, it looks like this: ![posting](images/notebook_cells.png)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"So the information is similar to how you create a normal RST post."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Another working example is SunPy's website which runs [Ablog](https://sunpy.org/blog.html). The Pull Request that added support can be found [here](https://github.com/sunpy/sunpy.org/pull/131) and how to link them to a [Binder](https://mybinder.org/) instance [here](https://github.com/sunpy/sunpy.org/pull/134)."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.6.6"
}
},
"nbformat": 4,
"nbformat_minor": 2
}

44
docs/manual/post-excerpts-and-images.rst Normal file
View file

@ -0,0 +1,44 @@
Post Excerpts and Images
========================
.. post:: May 12, 2014
:tags: directive
:category: Manual
:location: Pittsburgh
:author: Ahmet
:exclude:
:image: 2
This post describes how to choose an excerpt and an image image for a post to be displayed in archive pages.
Excerpts
--------
ABlog, by default, uses first paragraph of the document as post excerpt.
Default number of paragraphs to use in excerpts is controlled via :confval:`post_auto_excerpt` configuration variable.
This option can be overwritten using ``:excerpt:`` option in :rst:dir:`post` directive.
Alternatively, you can provide some content in a post directive as follows::
.. post:: Apr 15, 2014
This is all of the excerpt for this post.
This content is going to be used as excerpt in archive pages.
Furthermore, if you do not want the excerpt to be included in the post, you can use ``:exclude:`` option as follows::
.. post:: Apr 15, 2014
:exclude:
This is all of the excerpt for this post.
It will be displayed in archive pages and excluded from the post page.
Images
------
Let's first include a local and a non-local image in this post.
.. image:: /_static/ablog.png
.. image:: https://www.python.org/static/community_logos/python-logo.png
To link the second one of these, we add ``:image: 2`` option in :rst:dir:`post` directive.

212
docs/manual/posting-and-listing.rst Normal file
View file

@ -0,0 +1,212 @@
Posting and Listing
===================
.. post:: May 9, 2014
:tags: directive
:category: Manual
:location: Pittsburgh
:author: Ahmet
This post describes :rst:dir:`post`, :rst:dir:`update`, and :rst:dir:`postlist` directives.
.. _posting-directive:
Posting with a Directive
------------------------
Any page in a Sphinx_ project can be converted to a post using the following directive:
.. rst: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
:external_link: https://anexternalwebsite.org
:nocomments:
**Drafts & Posts**
Posts without dates or with future dates are considered as drafts and are published only in :ref:`blog-drafts` archive page.
Posts with dates that are older than the day Sphinx project is built are published in :ref:`blog-posts` page.
Post date format must follow the format specified with confval:`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 :confval:`blog_authors`, :confval:`blog_languages`, and :confval:`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 :confval:`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 :ref:`post-excerpts-and-images`.
**Canonical links**
If you re-publish content already existing on another URL (e.g., if you re-publish content from an employer's blog your personal one), use the ``canonical_link`` parameter to create a [canonical link relation](https://datatracker.ietf.org/doc/html/rfc6596) to the original version.
**External links**
If you'd like a post to point to an external website (e.g., if you host your posts on a blogging platform like Medium but wish to maintain a list of posts on your ``Ablog`` site), use the ``external_link`` parameter and this will be used instead.
**Update Notes**
.. rst:directive:: 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 :confval:`post_date_format` configuration option.
Update directive renders like the updates that are at the end of this post.
.. _posting-front-matter:
Posting with page front-matter
------------------------------
If you'd prefer to use `page front matter <https://www.sphinx-doc.org/en/1.7/markup/misc.html>`__ instead of using a directive, you may mark a page as a "blog post" by adding the following front-matter at the top:
.. code-block:: rst
:blogpost: true
``ABlog`` will treat any pages with this front-matter as a blog post.
All fields that are available to the :ref:`posting directive <posting-directive>` can be given as page-level front-matter as well.
.. admonition:: Automatically detect blog posts with a ``glob`` pattern
:class: tip
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.
Any filenames that match this pattern will be treated as blog posts (and page front-matter will be used to classify the blog post).
For example, the following configuration would match all ``rst`` files in the ``posts/`` folder:
.. code-block:: python
blog_post_pattern = "posts/*.rst"
and this configuration will match all blog posts that match either ``rst`` or ``md``:
.. code-block:: python
blog_post_pattern = ["posts/*.rst", "posts/*.md"]
.. _posting-sections:
Posting Sections
----------------
.. post:: Aug 20, 2014
:tags: directive
:category: Manual
:location: SF
:author: Ahmet
:rst:dir:`post` directive can be used multiple times in a single page to create multiple posts of different sections of the document.
When :rst:dir:`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 :confval:`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 :ref:`xref-syntax` for details.
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.
Listing
-------
A list of posts can be displayed in any page using the following directive:
.. rst: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:
:expand: Read more ...
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``.
Posts will be in ``:sort:``\ed to appear in chronological order and listed with their ``:excerpts:``.
Here are those posts:
.. 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:
:expand: Read more ...
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.
.. update:: Aug 21, 2014
Added :rst:dir:`update` directive and
:ref:`posting-sections` section.
Also revised the text here and there.
.. update:: Sep 15, 2014
* :rst:dir:`post` directive has ``:language:`` option.
* :rst:dir:`postlist` directive takes arguments to filter posts.
.. update:: Mar 28, 2015
Added ``:excerpts:`` option to :rst:dir:`postlist` to list posts with their excerpts.
.. update:: Apr 14, 2015
Added ``:list-style:`` option to :rst:dir:`postlist` to control bullet list style.
*circle*, *disc*, and *none* (default) are recognized.
.. update:: May 25, 2021
Added ``:expand:`` option to :rst:dir:`postlist` to add a call to action to continue reading the post.

101
docs/manual/templates-themes.rst Normal file
View file

@ -0,0 +1,101 @@
Templating and Themes Support
=============================
.. post:: Oct 26, 2024
:tags: themes
:category: Manual
:author: Libor
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.
.. _Sphinx templates: https://www.sphinx-doc.org/en/master/development/html_themes/templating.html
.. versionchanged:: 0.11
The :doc:`Ablog 0.11 </release/ablog-v0.11-released>` 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.
.. _sidebars:
Blog sidebars
-------------
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).
- ``ablog/postcard.html`` provides information regarding the current post (when on a post page).
- ``ablog/recentposts.html`` lists the most recent five posts.
- ``ablog/tagcloud.html`` provides links to archive pages generated for each tag.
- ``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)").
For example, the sidebars that you see on this website on the left are:
.. code-block:: python
html_sidebars = {
"**": [
# Comes from Alabaster theme
"about.html",
"searchfield.html",
# Ablog sidebars
"ablog/postcard.html",
"ablog/recentposts.html",
"ablog/tagcloud.html",
"ablog/categories.html",
"ablog/archives.html",
"ablog/authors.html",
"ablog/languages.html",
"ablog/locations.html",
]
}
Styling default Ablog sidebars
------------------------------
Ablog standard sidebars are wrapped in ``<div>`` with CSS classes like :samp:`ablog-sidebar-item ablog__{<template_name>}`, making them easier to style.
For example, the ``recentposts.html`` template is wrapped in ``<div class="ablog-sidebar-item ablog__recentposts">``.
.. seealso::
Built-in sidebars can be found in the ``ablog/`` folder in the `Ablog source code <https://github.com/sunpy/ablog/tree/main/src/ablog/templates/ablog>`_.
If styling is not enough, you can override the Ablog templates in your Sphinx project or in the Sphinx theme.
Partial or complete override of Ablog templates
-----------------------------------------------
To control whether Ablog injects its own templates into the Sphinx build, you can use the following ``conf.py`` configuration option:
.. confval:: skip_injecting_base_ablog_templates
If set to ``True``, Ablog will not inject its own templates into the Sphinx build. This is useful if you want to completely override Ablog templates in your Sphinx project or in the Sphinx theme. The default is ``False``.
Customizing templates in the project
------------------------------------
All Ablog templates are under the ``ablog/`` folder space. For example, ``ablog/postcard.html``. You can override these templates by placing them in the ``ablog/`` folder in your project templates folder.
#. Add the :confval:`templates_path` option in your ``conf.py`` file:
.. code-block:: python
templates_path = ["_templates"]
#. Create a folder ``_templates/`` next to your ``conf.py`` file. It will hold your custom templates.
#. Create a folder ``ablog/`` inside the ``_templates/`` folder.
#. Create a file here with the same name as the template you want to override. For example, ``postcard.html``. This file will be used as a custom template for the sidebar. You can copy the content of the original template from the Ablog source code and modify it as you need.
#. Optionally: if you want to completely override all Ablog templates, set the :confval:`skip_injecting_base_ablog_templates` option to ``True``, copy all Ablog templates here, and customize them as you need.
Customizing templates in the theme
----------------------------------
If you are a Sphinx theme author, you can ship customized Ablog templates in your theme. You can override Ablog templates by placing them in the ``ablog/`` folder in your theme templates, e.g., ``ablog/postcard.html``.
#. In the theme root (where the ``theme.toml`` (or ``theme.ini`` in older Sphinx themes) file is), create a folder ``ablog/``.
#. Create a file here with the same name as the template you want to override. For example, ``postcard.html``.
#. This file will be used as a custom template for the sidebar. You can copy the content of the original template from the Ablog source code and modify it as you need.
#. In your ``theme.toml`` file, add the following (under the ``[options]`` section):
.. code-block:: toml
ablog_inject_templates_after_theme = true
This will ensure that Ablog templates are injected *after* the theme templates, so you can override them while still using the Ablog templates as a fallback.

21
docs/manual/watch-yourself-blogging.rst Normal file
View file

@ -0,0 +1,21 @@
Watch Yourself Blogging
=======================
.. post:: Apr 19, 2015
:tags: commands, tips
:category: Manual
:author: Ahmet
:location: SF
:language: en
Wouldn't you like your blog being rebuilt and served to you automatically as you are blogging on a sunny Sunday afternoon?
It's now possible with the improved ``ablog serve`` command.
First, you need to install Watchdog_ Python package, e.g. `pip install watchdog`.
Then, you need to run ``ablog serve -r``.
Regardless of the weather being sunny or the day of the week, your project will be rebuilt when you change a page or add a new one.
This won't refresh your browser page though.
Unless you want to hit refresh once in a while, you can easily find an auto refresher extension for you browser.
.. _Watchdog: https://github.com/gorakhargosh/watchdog