docs.pelican.bernatchez.net - pelican

Configure a New Bunny Site

2026-05-09T12:59:29+00:00

Example steps to set up a your bunny.net account to accomodate a new site.

In this example Our new site called: dummy.example.net

Change your names according to your site name.

login to your bunny.net account at: https://dash.bunny.net/
create a standard storage zone named: dummy-example-net [1]

[1]	Picture shows "docs-pelican-bernatchez-net" should show "dummy-example-net"

create a pull zone named: dummy-example-net-zone [2]

[2]	Shows "docs-pelican-bernatchez-net-zone" should show "dummy-example-net-zone"

login to your DNS service account.
On your DNS server create a record: dummy.example.net CNAME dummy-example-net-zone.b-cdn.net
Back on bunny.net add a custom hostname dummy.example.net to the pull zone [3]

[3]	Shows "docs.pelican.bernatchez.net" should show "dummy.example.net"

When you do this add, take the opportunity to confirm certificate is working.

Now your site is ready to serve. You can publish to it.

Getting it on one page

2026-04-26T01:36:19+00:00

My recipes consist of an image and the instructions to prepare it beneath that. For the sake of ".pdf" printing, I try to fit it all in a sindle page. That means I must keep the image small.

In practical terms, I take a picture with my cell phone. Then I open that up with the shotwell viewer and I crop the part I want from it.

Then whatever I end up with, I shrink to about 1000 pixels wide.

shrink command

convert original.jpg -resize 1000x pagefit.jpg

snippet that includes the image in the RST source

|

.. image:: ../images/pagefit.jpg
    :class: img-responsive
    :scale: 30%
    :alt: The result

I have included such an image above as illustration.

Creation of a .rst site

2026-04-16T01:47:25+00:00

We go through the process of creating a new site subdirectory in our git repository here to record a walk through of starting a new site.

For the actual creation of hosting infrastructure within a bunny.net account see: newbunny site

mypelican_static_sites is the git repository project where we set it up.

We make a new site is called: dummy.bernatchez.net

Create the new site directory and populate it

# create
cd ${HOME}/repos/mypelican_static_sites
mkdir dummy.bernatchez.net

# populate
cp -r -P init.files/* dummy.bernatchez.net/

reference the pre-existing pelican/ articles within our dummy site

You only need for the directory to exist under content/ for that. The Makefile takes care of populating the subdirectory.

We will add a placeholder.txt file in that directory so that git clone will create the subdirectory in the future.

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net
mkdir content/pelican

# this assures pelican/ directory is created henceforth upon git clone
cp content/pages/placeholder.txt content/pelican/placeholder.txt
git add content/pelican/placeholder.txt

Add the following lines to the end of ".gitignore"

cd ${HOME}/repos/mypelican_static_sites

cat >>.gitignore <<EOFGITIGNORE
##
## BEGIN added for a new site
##

# dummy.bernatchez.net softlinks

dummy.bernatchez.net/content/favicon.ico
dummy.bernatchez.net/content/images/
dummy.bernatchez.net/content/site-only/
dummy.bernatchez.net/content/pages/
dummy.bernatchez.net/content/pelican/

dummy.bernatchez.net/content/images/*
dummy.bernatchez.net/content/site-only/*
dummy.bernatchez.net/content/pages/*
dummy.bernatchez.net/content/pelican/*


# dummy.bernatchez.net bucket is all generated
dummy.bernatchez.net/bucket/
dummy.bernatchez.net/bucket/*

##
## END additions for a new site
##
EOFGITIGNORE

cd ${HOME}/repos/mypelican_static_sites
git add .gitignore

Put the customizable files under version control

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net

git add Makefile
git add deploy.bunny
git add favicon.ico
git add login.bunny
git add names.bunny
git add notes.txt
git add pelicanconf-en.py
git add pelicanconf-es.py
git add pelicanconf-fr.py
git add publishconf-en.py
git add publishconf-es.py
git add publishconf-fr.py
git add purge.bunny
git add puta2p.sh

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/pages
git add *.rst

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/content
git add binaries images sitepdfs

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/pages-media
git add *

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/pages-pdfs
git add placeholder.txt

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/site-only-pdfs
git add placeholder.txt

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/site-only
git add *.rst

# Commit your git additions

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/
git commit -m new-dummy-site

Generate this first revision of the site

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/
make html

# revise and continue maintaining as and when required

Once you are satisfied with the site generate a publishable version

This relies on the bunny.net storage zone and pull zone existing otherwise the deploy.bunny step will fail.

cd ${HOME}/repos/mypelican_static_sites/dummy.bernatchez.net/
make pubhtml

Metadata attributes in each article

2025-04-16T00:37:11+00:00

Pelican requires meta data like these

:lang: en
:date: 2025-04-16 00:37:11+00:00
:tags: metadata, article, pelican
:slug: articlemeta
:category: pelican
:authors: Pierre Bernatchez
:summary: Metadata in articles

Insert them below the initial heading of every article.

These ones should be identical in all translations of an article.

:date: 2025-04-16 00:37:11+00:00
:slug: sitehome
:authors: Nuno Yobidness.

These ones must be be translated into the different language versions of the article.

:lang: en
:tags: introduction
:category: pelican
:summary: Welcome to Site

These ones are optional.

Prevents the content from coming out under menus, pages, keywords and categories. It will be generated, but you will need a link somewhere to get to it.

use the same value in all languages.

:status: hidden

Overrides the default page footer copyright Value is language dependant.

:fcopyright: Copyright © 2026 Isaac Mejia—all rights reserved.

mypelican_static_sites git project

2025-04-16T00:37:11+00:00

Overview

This is a github project that uses a site generator called pelican to generate static websites.

At this writing this project maintains the content and generation for three seperate sites. Each site is rendered in 3 languages, english, french and spanish.

By convention we name each of these subdirectories using the domain name of the site. The scripts rely on this fact.

Currently Maintained Sites

www.bernatchez.net

Hosted in Bunny.net: www-bernatchez-net
www.ogopogo.biz

Hosted in Bunny.net: www-ogopogo-biz
blog.bernatchez.net

Hosted in Bunny.net: blog-bernatchez-net
docs.pelican.bernatchez.net

Hosted unpublished on local file system.

Web site generation

Generate a local version of a site so that you can browse and review it before publishing it.

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

Generate an online version of the site and publish it.

cd ./blog.bernatchez.net
# Make sure the deploy.bunny file actually runs an "nmx" command rather than just echoing it.
make pubhtml

# Manually Invoke the command printed as the last line by the above make
# This pushes everything out to CDN cache
npx --yes bunny-transfer@latest purge blog-bernatchez-net-zone

Warning

Once you have invoked "make pubhtml", your "local site" content will no longer be appropriate for local viewing. If you wish to browse both local and online versions interchangebly. You need to repeat the "make html" once you have published thereby leaving the local files configured for local viewing.

Web Site Maintenance

Scope

The git project is organized to have 2 scopes for site source
content.

*Global source scope*

   The .rst files contained in subdirectories of the main project directory.
   These files can be sourced by any of our websites.

*Local source scope*

   The .rst files contained within subdirectories under a given site subdirectory.
   These files can only be sourced by the given website.

A given site's "content" subdirectoy contains subdirectories whose
names match either global or local scope subdirectories. That
identifies what will be included in the site.

What directory names appear in the "content" directory determines
what is included in the generated site.

The make file handles populating such directories with with soft
links to the .rst source files in their corresponding local or
global scope directory.

Insofar as the repository is concerned you only "git add" .rst
files which are in global or local scope directories.  The
subdirectories under content/ will only contain "placeholder.txt"
within git to make sure their subdirectories are created upon
clone.

pdf source

All our sites also contain .pdf versions of their pages.  To
produce those pdf files, each source directory also contains two
executable script files: **article2pdf**, and **qarticle2pdf**.
The latter is just a less verbose version.  Whenever you modify or
add content in a source directory, remember to re-regenerate the
.pdf files accordingly.

Generally, you modify your content, and then invoke "qarticle2pdf"
to make sure your pdfs are up to date.

If you have created a mew source directory you can generate those two scripts
in it by invoking the command "genarticle2pdf -q" inside the new directdory.

github maintenance

When you clone the github project to a local directory, you end up
with a main directory which contains web site subdirectories, each
of those is an independant web site generation directory.

The project main directory contains various *Global source scope*
site subdirectories (E.G. ./examples, ./artwork, ./travel,
etc...). Each of these contain .rst files that can serve as source
for site content generation. All under git revision control.

This *Global source scope* content can optionally be used as source
for any of the web sites.

Each web site subdirectory can also contain its own subdirectories
containing site specific *Local source scope* .rst files
(E.G. ./blog.bernatchez.net/pages/) intended only for the given
site.

To add any one of these *local or global scope* content directories
to a given web site, you need to create a directory of the same
name under the given site's content subdirectory.  You must also
add a "placeholder.txt" file and put it under revision control
(e.g. git add placeholder.txt) to enssure that new directory will
be created upon use of "git clone".

For example we did this to add ./examples to the ./blog.bernatchez.net web site:

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

You also need to modify the project .gitignore file to avoid adding
the generated soft links under content/examples into the git
repository.  Those links are regenerated every make.

We added the lines below to .gitignore:

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

Repository

The original central copy of this project's repository is:

git@github.com:pierrebernatchez/mypelican_static_sites.git

Article Starting Point

2024-12-06T20:05:03+00:00

Sample RST content to start from and modify for your article.

Main Header for your article
#############################################

:lang: en
:category: a valid category
:date: 2025-10-11 20:03:36+00:00
:tags: article, template
:slug: unique-article-name
:authors: Pierre Bernatchez
:summary: One line Summary of your article

.. |copy| unicode:: 0xA9 .. copyright sign

.. |---| unicode:: U+02014 .. em dash
   :trim:

.. footer:: Copyright |copy| 2025 Pierre Bernatchez |---| all rights reserved.


Start here

Modify the main header to something suitable for your artricle.

Modify category to one appropriate for your article.

Modify date. You can use command line command "date -u --rfc-3339=seconds" to get a correctly formatted date string.

Modify tags to relevant keywords for your article.

Modify slug to be the unique name for your article. We use that as the basis for the file name of the .rst file. Like this slugname-en.rst, slugname-es.rst, slugname-fr.rst are the 3 language file names for the article with the slug: slugname.

Modify authors to your own name.

Modify summary to something appropriate to your article.

Modify the name in the footer line to yours also.

Write your article, using RST markup beginning at start here

Note that there there are two convenience python scripts that can generate something to start from for a new article.

Generate an article starting point with no image

newarticle -h

usage: newarticle [-h] [-a AUTHOR] [-l {en,fr,es,all}] [-d DUP] [-r]
                  articlename

Generate a skeleton article file

positional arguments:
  articlename           article name without the "-en.rst")

options:
  -h, --help            show this help message and exit
  -a AUTHOR, --author AUTHOR
                        Author for copyright and for authors (default "Pierre
                        Bernatchez)"
  -l {en,fr,es,all}, --lang {en,fr,es,all}
                        language of the new article (default: all)
  -d DUP, --dup DUP     Existing article name to duplicate category and tags
                        (default None)
  -r, --recipe          Treat this as a recipe. (Othewise generic)

Generate an article starting point with an image

newshot -h

Output

usage: newshot [-h] [-a AUTHOR] [-l {en,fr,es,all}] [-d DUP] [-j] [-r]
               articlename

Generate a skeleton article file which has a srcreenshot

positional arguments:
  articlename           article name without the "-en.rst")

options:
  -h, --help            show this help message and exit
  -a AUTHOR, --author AUTHOR
                        Author for copyright and for authors (default "Pierre
                        Bernatchez)"
  -l {en,fr,es,all}, --lang {en,fr,es,all}
                        language of the new article (default: all)
  -d DUP, --dup DUP     Existing article name to duplicate category and tags
                        (default None)
  -j, --jpg             Reference image as a .jpg rather than a .png a
                        (default: False)
  -r, --recipe          Treat this as a recipe. (Othewise generic)

Theme «Lightweight» for pelican

2024-12-06T20:02:44+00:00

Description

:Created on: 14 February 2011
:Technologies used: xHTML5, CSS 1-3, polices TTF
:Colors Used: Cold Tones (grey/blue)
:Extensive design: Yes
:Tested Under: Mozilla Firefox 4.0b10, Chromium 9.0.597.83, ELinks 0.12pre5
:Language: English
:Details: See Screenshot and source

This theme is derived From the french language lightweight theme. It has been altered so that the home page lists only a few of the most recent articles. It has been translated to english.

Screenshot

Pelican Web Site Generator Configuration

2024-12-02T17:30:00-05:00

Pelican is a static web site generator. It is the tool we are using to maintain our static sites.

This documet assumes we are using venvwrapper [1].

Install Pelican

Do it within our python virtual environment. We named our environment statsites.

Activate it, and install Pelican

venv statsites
pip install pelican

Themes

In each of our pelicanconf.py configurations we select a theme for the given site. To get a collection of themes to choose from, we cloned as follows:

git clone --recursive https://github.com/getpelican/pelican-themes ${HOME}/pelican-themes

Site Theme Note

In our own sites we have made a few adjustments to the lightweight theme to suit our purpose. We maintain this derived theme and our web content under our git version control repository. Our pelicanconf-en.py configuration file has this reference.

THEME = u"/home/ubuntu/allrepos/mystatic_sites/derived-themes/lightweight-single-home-en"

Your site's theme will be for you to choose and/or modify.

Initialize Skeletal Site File Sytem

Use 'pelican-quickstart' to generate initial static website content using pelican.

pelican-quickstart creates the a skeletal site generation file system beneath the current empty directory.

Afterwards you create .rst files in content/anyname directories as blog articles. Ccreate .rst files in content/pages as blog pages.

Compilation

Generate the web site files once we have all our .rst source files. For this we only need to use the Makefile. The following will compile and emit all the web site content under output/ using pelican.

make html

Your can review your results by invoking the output/index.html file.

[1]	We are using the package venvwrapper to simplify virtual environment management. That fact is assumed in this document. If you are not using it, you need to replace lines here such as: "venv statsites", with lines such as "source ${HOME}/.venv/statsites/bin/activate".

Project Source Organization

2024-12-02T17:30:00-05:00

At this writing we are maintaining pelican generated static websites, one for blog.bernatchez.net and one for www.ogopogo.biz.

We use our script "compile_rst" to add a few generated .rst files to the source site before using pelican to generate the site from source.

We can generate a list of links to the files in a subdirectory.

Accomplished like this in the Makefile.

$(COMPILE_RST) -p '*.pdf' -s sitepdfs -o pdfs_list -i

That would generate a link for each .pdf file in sitepdfs/ and emit the result to the file pdfs_list.rst

Such a file is intended to be included within one or more of our manually produced .rst pages with a line like:

.. include:: ../../pdfs_list.rst

That would include our generated link list in that page.

We can also generate music album like pages with links to the files in a compilation subdirectory.

Accomplished like this in the Makefile.

$(COMPILE_RST) -p '*.mp3' -s compilations -o album -a

This would generate - possibly - several album_N.rst files in the pages/ subdirectory, where N is a sequence number. You will get as many pages as there are albums referenced in the m3 files in the compilations directory.

Invocations of compile_rst must take place every time the make html target is requested.

For example, the bernatchez_staticweb Makefile contains this

html:

    $(COMPILE_RST) -p '*.mp3' -s compilations -o album -a
    $(COMPILE_RST) -p '*.tar.gz' -s tarballs -o tarballs_list -i
    $(COMPILE_RST) -p '*.pdf' -s sitepdfs -o pdfs_list -i
    $(PELICAN) $(INPUTDIR) -o $(OUTPUTDIR) -s $(CONFFILE) $(PELICANOPTS)

So that content/pages/album_N.rst files and tarballs_list.rst, pdfs_list.rst are all regenerated prior to invoking pelican to generate the site.

In short

Files tarballs/*.tar.gz , sitepfds/*.pdf, and compilations/*.mp3 as well as all the .rst files under the content subdirectory determine what goes into our website.

At this writing the content is only proof of concept data.

Pelican Theme Screenshots

2024-12-02T17:30:00-05:00

Decreasing order of preference

lightweight

THEME = "/home/ubuntu/pelican-themes/lightweight"

sneakyidea

THEME = "/home/ubuntu/pelican-themes/sneakyidea"

basic

THEME = "/home/ubuntu/pelican-themes/basic"

notmyidea-cms

THEME = "/home/ubuntu/pelican-themes/notmyidea-cms"

notebook

THEME = "/home/ubuntu/pelican-themes/notebook"

cebong

THEME = "/home/ubuntu/pelican-themes/cebong"

relapse

THEME = "/home/ubuntu/pelican-themes/relapse"

bold

THEME = "/home/ubuntu/pelican-themes/bold"

bootstrap2-dark

THEME = "/home/ubuntu/pelican-themes/bootstrap2-dark"

franticworld

THEME = "/home/ubuntu/pelican-themes/franticworld"

Theme Note

2024-12-02T17:30:00-05:00

Notes regarding selecting and tweaking pelican themes used with our sites.

To be able to use/tweak pelican themes for my pelican projects I cloned the full collection of pelican themes to my local machine.

git clone --recursive https://github.com/getpelican/pelican-themes /home/ubuntu/pelican-themes

I then replicated the tree to use as a basis for getting a diff to identify any changes that I made during the course of tweaking themes I use.

cp -r ${HOME}/pelican-themes ${HOME}/pelican-themes.orig
chmod -w --recursive ${HOME}/pelican-themes.orig  # To make my orig write protected for reliable diffs later.

Do this once in a while as we tweak themes we are using, so we can keep a record of our tweaks.

cd ${HOME}/pelican-themes
diff -Naru ../pelican-themes.orig . > ../pelican-themes.patch

Note:

-N --new-file treat absent files as empty

-a --text treat all files as text

-r --recursive recursively compare subdirectories

-u -U --unified[=NUM] Output NUM lines of unified context (default 3)

Pelican Themes

2024-11-18T20:41:00-05:00

sneakyidea

THEME = "/home/ubuntu/pelican-themes/sneakyidea"

lightweight

THEME = "/home/ubuntu/pelican-themes/lightweight"

basic

THEME = "/home/ubuntu/pelican-themes/basic"

notmyidea-cms

THEME = "/home/ubuntu/pelican-themes/notmyidea-cms"

bold

THEME = "/home/ubuntu/pelican-themes/bold"

Github Clone Note

2015-03-19T11:47:31-04:00

If you have just cloned the "mypelican_static_sites" repostitory, you need to take a few steps before generating the sites.

pre-requisites

Our builds for the sites maintained here rely on the "flitprojects" project that is also under our github account's revision control. That project relies on python virtual environments. So we are assuming that an adequate virtual environment is set up, and that we have done flit build, and flit install into it of the "flitprojects/articleware" package.

Newly cloned "mypelican_static_sites" setup steps

Install scripts to generate the pdf versions of all the articles. These scripts are genereated so they are not kept under version control. We use a bash script to identify the list of site subdirectories and generate our scripts within each of those.

allputs.sh
# this generates a pair of scripts in each subdirectory
# that contains article .rst files.

Once the scripts have been generated. We need to get all the .pdf files generated. We do that by going to any of the site subdirecgtories and using make to generate the .pdf files.

cd www.bernatchez.net
make pdfs

Generate your local versions of your sites so that you can double check that they are good to go.

cd www.bernatchez.net
make html
cd ..

cd blog.bernatchez.net
make html
cd ..

cd www.ogopogo.biz
make html
cd ..

cd docs.pelican.bernatchez.net
make html
cd ..

Generate the publishable versions of your sites and publish them.

cd www.bernatchez.net
make pubhtml
cd ..

cd blog.bernatchez.net
make pubhtml
cd ..

cd www.ogopogo.biz
make pubhtml
cd ..

# Only use the filesystem version of this one, so don't generate.
# We do not maintain the site with the bunny CDS.
cd docs.pelican.bernatchez.net site
echo 'We do not maintain the site "docs.pelican.bernatchez.net" with the bunny CDS.'
cd ..

Make with "pubhtml" yields online locations within many of the links inside the content. This is incompatible with the make "html" generated content whose links must all be file system relative. This means that the content on the local file system is no longer valid immediately after generating "pubhtml" content. So we have to re-run make "html" once we have published the content to revert the local content to what is should be.

cd www.bernatchez.net
make html
cd ..

cd blog.bernatchez.net
make html
cd ..

cd www.ogopogo.biz
make html
cd ..

Troubleshooting Site Generation

2015-03-19T11:47:31-04:00

I intend to keep adding to this note as further issues crop up and workarounds are discovered.

1- I found that when we use the same slug for different language versions of the same article.

pelican does a nice job of picking out the current default language's version for the site. When no version exists which matches the current default language, then pelican emits warnings and/or errors regarding the other language versions.

The work around is to always make sure you have all the language versions you are supporting, or just a single one. When that is the case it seems to behave adequately.

It seems sensible to translate attribute values too, other than slug of course.