Migrando mi blog de Nikola a Sphinx#
Migrar de un generador estático a otro no es un proceso del todo transparente, así que aquí te explico algunos por menores para hacer una migración de Nikola a Sphinx.
Pero antes, es necesario tener presente, que lo básico del proceso de migración, inicia por tener lo mínimo desde cero, con Sphinx. Para este fin, debes seguir las indicaciones dadas en Crear un blog con Sphinx.
Migrando#
Bueno, una vez tenemos la base de nuestro blog, sigue hacer los ajustes para que nuestras entradas previas sigan funcionando.
Publicación#
Front matter#
Dado que en la configuración inicial añadimos un patrón de ruta
para las publicaciones, no es necesario agregar la directiva de ..post: o el
atributo de :blogpost: true. Solo ubica los archivos en la ruta que cumpla el
patrón 👀.
Importante, en Nikola definíamos la ruta de navegación mediante el ..slug:,
pero esto en Sphinx depende del nombre del archivo y su ruta en el directorio.
Asegurate de usar la misma ruta de directorios al definido en el slug y el
nombre del archivo igual a la parte final de este 👀. Otra opción, es que sin
importar el nombre y ruta de directorios, uses el valor del slug como valor de
:redirect: (en este caso, añade al archivo de configuración
post_redirect_refresh=0).
Para indicar el título en Nikola, se usaba el atributo de .. title:, pero
ahora este debe ser explícito en la marcación de la publicación. Ejemplo:
Migrando mi blog de Nikola a Sphinx
===================================
# Migrando mi blog de Nikola a Sphinx
Esto hace que los títulos ya existentes, deban aumentar de nivel 👀.
En ablog no tenemos el equivalente del ..status: de Nikola, pero se puede
controlar que una fecha actual o pasada sea equivalente a published y si es
una fecha futura o sin fecha es el equivalente de draft. El caso del private
podríamos hacerlo excluyendo el archivo. El caso featured es
más personalizado, pero se podría explorar con el objeto de las cards en el
índice.
Si queremos indicar la imagen de previsualización, en Nikola se usaba
.. previewimage:, pero en ablog lo hacemos con :image: y el valor no es la
ruta de la imagen, sino el número asociado en orden de aparición en la
publicación. Esto se puede dejar con un valor por defecto acorde a la variable
en el archivo de configuración de post_auto_image.
El atributo de .. description: es tomado por defecto por truncamiento del
primer párrafo de la publicación (esto se usa en los metadatos de la
publicación), pero también podemos dejarlo si lo queremos personalizado (esto se
hace con la extensión de open-graph).
El caso de .. link: se debe convertir en :external_link:.
Para la las actualizaciones, esto en lugar de ser un atributo, pasa a ser una anotación con marca de tiempo, pero con información de contexto.
.. update:: 2011-12-15
Se añade info extra
```{update} 2011-12-15
Se añade info extra
Con los atributos de .. nocomments:, .. tags:, .. date:, .. author: y
.. category:, basta con cambiar .. inicial por :.
Respecto a la fecha es importante tener claro, que a diferencia de Nikola no
podemos mezclar tipos de formato de fecha. Estos deben añadirse según la
definición que se tenga en el archivo de configuración, en la variable
post_date_format.
No es necesario un atributo para habilitar las ecuaciones, ya que Sphinx las
habilita por defecto. En Nikola era necesario con .. has_math: true.
El caso de .. type: no posee equivalente.
⚠️ Si estamos usando markdown, la diferencia es quitar el : inicial, tal
como se evidencia en la sección de
primera publicación, y
el separador <!-- --> pasa a ---.
Contenido#
En algunos casos, podíamos recurrir a listados de publicaciones mediante algún
filtro con .. post-list:: y el atributo de :categories. Esto ahora pasa a
.. postlist:: con el atributo :category: (puedes usar otros filtros
también).
Respecto a .. thumbnail:: esta directiva no existe, y se reemplaza por
.. figure::.
La definición del teaser en Nikola dependía de una marcación específica como
directiva para el texto, pero en ablog esto es controlado por el atributo
:excerpt:, para denotar el número de párrafos a incluir. Pero podemos dejarlo
con un valor por defecto acorde a post_auto_excerpt en el archivo de
configuración.
Para las referencias a documentos, en Markdown pasamos de
{{% doc %}} path {{% /doc %}} a <project:path> o [](path), mientras que en
RST podemos mantener :doc: siempre y cuando no apunte a una etiqueta, en cuyo
caso sería :ref:.
Configuración#
Archivos en el raíz#
Los archvos en el raíz, se definen en un directorio que disponemos con la
variable html_extra_path, la cual podemos definir con el mismo nombre que
viene en Nikola (files).
Sistema de comentarios#
Si usamos Disqus (en Nikola, COMMENT_SYSTEM='disqus'), el disqus_shortname
en el archivo de configuración toma el valor del antiguo COMMENT_SYSTEM_ID.
Nota
La verdad, he decidido retirar el sistema de comentarios de Disqus. Aporta poco valor respecto a lo que introduce en tiempo de carga. Posiblemente explore disponer el enlace de la publicación en Mastodon para que se desarrolle la eventual discusión.
Youtube#
Necesitamos instalar sphinxcontrib-youtube y habilitar sphinxcontrib.youtube
en las extensiones. De esta forma, la directiva de .. youtube:: sigue tal
cual.