docs.pelican.bernatchez.net

Descripción general

Este es un proyecto de github que utiliza un generador de sitios llamado pelican para generar sitios web estáticos.

Al momento de escribir esto, el proyecto mantiene el contenido y la generación de tres sitios separados. Cada sitio se presenta en 3 idiomas: inglés, francés y español.

Por convención, nombramos cada uno de estos subdirectorios usando el nombre de dominio del sitio. Los scripts dependen de esta convención.

Sitios actualmente mantenidos

1. www.bernatchez.net

   Alojado en Bunny.net: www-bernatchez-net

2. www.ogopogo.biz

   Alojado en Bunny.net: www-ogopogo-biz

3. blog.bernatchez.net

   Alojado en Bunny.net: blog-bernatchez-net

4. docs.pelican.bernatchez.net

   Alojado sin publicar en el sistema de archivos local.

Generación del sitio web

Genere una versión local de un sitio para poder navegarlo y revisarlo antes de publicarlo.

cd ./blog.bernatchez.net
make html
xdg-open ./bucket/index.html
cd ..

Genere una versión en línea del sitio y publíquela.

cd ./blog.bernatchez.net
# Asegúrese de que el archivo deploy.bunny ejecute realmente un comando "nmx" en lugar de solo mostrarlo.
make pubhtml

# Invoque manualmente el comando impreso en la última línea por el make anterior
# Esto envía todo al caché del CDN
npx --yes bunny-transfer@latest purge blog-bernatchez-net-zone

Advertencia

Una vez que haya invocado "make pubhtml", el contenido de su "sitio local" ya no será adecuado para la visualización local. Si desea navegar tanto la versión local como la versión en línea de forma intercambiable, debe repetir "make html" una vez que haya publicado, dejando así los archivos locales configurados para la visualización local.

Mantenimiento del sitio web

Alcance

El proyecto git está organizado con 2 alcances para el contenido fuente del sitio.

*Alcance de fuente global*

   Los archivos .rst contenidos en subdirectorios del directorio principal del proyecto.
   Estos archivos pueden ser utilizados como fuente por cualquiera de nuestros sitios web.

*Alcance de fuente local*

   Los archivos .rst contenidos en subdirectorios bajo un subdirectorio de sitio dado.
   Estos archivos solo pueden ser utilizados como fuente por el sitio web correspondiente.

El subdirectorio "content" de un sitio dado contiene subdirectorios cuyos
nombres coinciden con subdirectorios de alcance global o local. Eso
determina lo que se incluirá en el sitio.

Los nombres de directorio que aparecen en el directorio "content" determinan
lo que se incluye en el sitio generado.

El archivo make se encarga de poblar dichos directorios con enlaces
simbólicos a los archivos fuente .rst en sus correspondientes directorios
de alcance local o global.

En lo que respecta al repositorio, solo se hace "git add" a los archivos .rst
que están en directorios de alcance global o local. Los
subdirectorios bajo content/ solo contendrán un "placeholder.txt"
dentro de git para asegurarse de que sus subdirectorios sean creados al
clonar.

Fuente pdf

Todos nuestros sitios también contienen versiones .pdf de sus páginas. Para
producir esos archivos pdf, cada directorio fuente también contiene dos
archivos de script ejecutables: **article2pdf** y **qarticle2pdf**.
El segundo es simplemente una versión menos detallada. Cada vez que modifique o
agregue contenido en un directorio fuente, recuerde regenerar los
archivos .pdf según corresponda.

En general, usted modifica su contenido y luego invoca "qarticle2pdf"
para asegurarse de que sus pdfs estén actualizados.

Si ha creado un nuevo directorio fuente, puede generar esos dos scripts
en él invocando el comando "genarticle2pdf -q" dentro del nuevo directorio.

Mantenimiento de github

Cuando clona el proyecto github en un directorio local, obtiene
un directorio principal que contiene subdirectorios de sitios web, cada
uno de ellos es un directorio independiente de generación de sitios web.

El directorio principal del proyecto contiene varios subdirectorios de *alcance de fuente global*
(ej.: ./examples, ./artwork, ./travel,
etc.). Cada uno de estos contiene archivos .rst que pueden servir como fuente
para la generación de contenido del sitio. Todos bajo control de revisión git.

Este contenido de *alcance de fuente global* puede usarse opcionalmente como fuente
para cualquiera de los sitios web.

Cada subdirectorio de sitio web también puede contener sus propios subdirectorios
con archivos .rst de *alcance de fuente local* específicos del sitio
(ej.: ./blog.bernatchez.net/pages/) destinados únicamente al sitio
correspondiente.

Para agregar cualquiera de estos directorios de contenido de *alcance local o global*
a un sitio web dado, debe crear un directorio con el mismo
nombre bajo el subdirectorio content del sitio correspondiente. También debe
agregar un archivo "placeholder.txt" y ponerlo bajo control de revisión
(ej.: git add placeholder.txt) para garantizar que ese nuevo directorio se
cree al usar "git clone".

Por ejemplo, hicimos esto para agregar ./examples al sitio web ./blog.bernatchez.net:

mkdir ./blog.bernatchez.net/content/examples/
cp ./blog.bernatchez.net/content/pages/placeholder.txt ./blog.bernatchez.net/content/examples/
git add ./blog.bernatchez.net/content/examples/placeholder.txt

También debe modificar el archivo .gitignore del proyecto para evitar agregar
los enlaces simbólicos generados bajo content/examples en el repositorio git.
Esos enlaces se regeneran en cada make.

Agregamos las líneas siguientes al archivo .gitignore:

blog.bernatchez.net/content/examples/
blog.bernatchez.net/content/examples/*