Migrating my blog from Nikola to Sphinx#
Migrating from a static generator to another isn’t an entirely transparent process, so I’ll explain some simpler steps to help you migrate your blog from Nikola to Sphinx.
But before we begin, keep in mind that the basic steps for migration start by having the bare minimum from scratch with Sphinx. For this purpose, follow the instructions given at Creating a blog with Sphinx.
Migrating#
Alright, once we have the foundation of our blog set up, continue making adjustments to ensure that our previous posts still function properly.
Post#
Front Matter#
Since we added a path pattern for publications during the
initial configuration, there is no need to add the ..post: directive or the
:blogpost: true attribute. Simply place your files in the path that matches
the pattern 👀.
It’s important to note that in Nikola, we defined navigation paths using the
..slug:, but in Sphinx, this depends on the file name and its location within
the directory. Make sure to use the same directory path as defined in the
slug, and ensure the file name is equal to the last part of the slug 👀.
Alternatively, you can set up a redirect by using the value of slug as the
value for :redirect: (in this case, add post_redirect_refresh=0 to your
configuration).
To indicate the title in Nikola, we used the attribute ..title:, but now it
must be explicitly defined in the publication markup. Example:
Migrating my blog from Nikola to Sphinx
=======================================
# Migrating my blog from Nikola to Sphinx
This requires that existing titles be increased in heading level 👀.
In ablog, we don’t have an equivalent for Nikola’s ..status:, but we can
control whether a current or past date is equivalent to published and if it’s
a future or no-date date, it’s the equivalent of draft. The case of private
could be handled by excluding the file. For featured,
it’s more customizable, but it could be explored with the card objects on the
index.
If we want to indicate the preview image, in Nikola it was done using
..previewimage:, but in ablog, we use :image: and the value is not the
path of the image, but the number associated with its appearance order in the
publication. This can be set to a default value based on the variable in the
configuration file’s post_auto_image.
The attribute ..description: is taken by default as a truncation of the first
paragraph of the post (this is used for the publication metadata), but we can
also leave it customized if needed (this is done with the Open Graph extension).
For the case of ..link:, this should be converted to :external_link:.
For updates, instead of being an attribute, it becomes a timestamp annotation with context information.
.. update:: 2011-12-15
Extra info added
```{update} 2011-12-15
Extra info added
With the attributes of .. nocomments:, .. tags:, .. date:, .. author:,
and .. category:, simply change the initial .. to :.
Regarding the date, it’s important to note that unlike in Nikola, we cannot mix
types of date formats. These should be added according to the definition in the
configuration file, specifically in the variable post_date_format.
There is no attribute needed to enable equations as Sphinx enables them by
default. In Nikola, it was necessary with .. has_math: true.
The case of .. type: does not have an equivalent.
⚠️ If we are using markdown, the difference is to remove the initial :, as
evidenced in the section on
the first publication, and the
separator <!-- --> changes to ---.
Content#
In some cases, we could use post lists with specific filters using
.. post-list:: and the attribute :categories. This now changes to
.. postlist:: with the attribute :category: (you can also use other filters
as well).
Regarding .. thumbnail::, this directive no longer exists and is replaced by
.. figure::.
The definition of the teaser in Nikola relied on a specific markup directive
for the text, but in ablog, this is controlled by the attribute :excerpt: to
denote the number of paragraphs to include. However, we can leave it with a
default value based on post_auto_excerpt in the configuration file.
For document references, in Markdown we transition from
{{% doc %}} path {{% /doc %}} to <project:path> or [](path), while in RST
we can continue using :doc: as long as it does not point to a label. In that
case, it would be :ref:.
Configuration#
Root Files#
Files in the root are defined in a directory that we set with the variable
html_extra_path, which can be named the same as it comes in Nikola (files).
YouTube#
We need to install sphinxcontrib-youtube and enable sphinxcontrib.youtube in
the extensions. In this way, the directive .. youtube:: remains unchanged.
Comment System#
If we use Disqus (in Nikola,
COMMENT_SYSTEM='disqus'), thedisqus_shortnamein the configuration file takes the value of the oldCOMMENT_SYSTEM_ID.