Lepagito

Getting started

2023-02-14T00:00:00+01:00

Lepagito is a lovely pelican theme.

Observe it first in action on the lepagito web site. Also, it is used by both the Pirogh author's blog, the Greuze-Cottave blog for painters and designers and the galleria pelican plugin documentation.

You're interested? Fascinated? Let's start! First, download and install the theme:

git clone https://gricad-gitlab.univ-grenoble-alpes.fr/internet/lepagito

For navigation and searches, this theme includes the optional neighbors, search and sitemap pelican plugins:

sudo apt install pelican python3-pip python3.11-venv python3-full python-is-python3
python -m venv ~/mypy
source ~/mypy/bin/activate
pip install pelican-neighbors
pip install pelican-search
pip install pelican-sitemap
pip install pelican-theme-config

The first apt command is specific to GNU/Linux Debian systems and should be adapted to your environment. The neighbors optional plugin allows a convenient navigation between articles. The search plugin provides a self-hosted search capability to your site. Optionally, if you wish to customize the theme colors:

pip install colorspacious Pillow colormath

Also, the optional galleria plugin, for photo galleries:

git clone https://gricad-gitlab.univ-grenoble-alpes.fr/internet/galleria

The search pelican plugin depends itself upon stork, that should also be installed. For instance, for GNU/Linux Debian systems, just enter:

wget https://files.stork-search.net/releases/v1.6.0/stork-ubuntu-22-04
chmod a+x stork-ubuntu-22-04
sudo mv -i stork-ubuntu-22-04 /usr/local/bin/stork

If you are in trouble when installing stork on your computer, don't worry: you could just edit the pelicanconf.py file and remove both this optional plugin together with the SEARCH_MODE variable:

PLUGINS = ['neighbors', 'sitemap', 'galleria']
#SEARCH_MODE = 'output'

The sitemap optional plugin generates a sitemap.xml file to facilitate the indexing of your site by search engines. Finally, the galleria optional plugin facilitates the management of image galleries.

The documentation of this theme is itself a pelican blog using the present theme, so the source files of the documentation present a practical example on how to use pelican together with this theme. You could now check your computer environment: produce and read the documentation:

cd doc
pelican content
firefox output/index.html &

Next, if you already have a pelican blog, you just have to edit your pelicanconf.py file an change your theme as:

THEME = '/my-full-path-to/lepagito'

Finally, just enter as usual:

pelican content
firefox output/index.html &

The logo

2023-02-13T00:00:00+01:00

The logo at the top of each page is sill the heat, which is specific to the Lepagito theme. Your blog should have its own logo, since the Lepagito logo is copyrighted (see License). To do that, copy first logos from Lepagito to your environment, exactly as:

mkdir content/theme
cp -a ~/pelican-themes/lepagito/static/img theme

In the content/theme/img directory, the files are:

logo.png
favicon-16x16.png
favicon-32x32.png
favicon.ico
apple-touch-icon.png
mstile-150x150.png
site.webmanifest

entry_foooter.png
browserconfig.xml

The first six files are different implementations of the same logo and should be modified. The seventh file should also be modified. The eigth file is the blue pencil article footer: it could be changed or left as is, as you prefer. The last file could be left as is.

Finally, edit again your pelicanconf.py file as:

STATIC_PATHS = ['images', 'theme']

and run again pelican: your logo has been changed.

The file pelicanconf.py

2023-01-14T00:00:00+01:00

Here is a complete example of the pelicanconf.py file, as used for the present documentation of the theme. It starts by setting some standard pelican variables, as usual. Then, come the theme's and the optional plugins.

# =============================
# 1. standard pelican variables
# =============================
SITEURL      = 'http://lepagito.artliba.org'
SITENAME     = 'Lepagito'
AUTHOR       = 'I. Lepage and P. Hesse'
SITESUBTITLE = 'A lovely pelican theme'
TIMEZONE     = 'Europe/Paris'
DEFAULT_LANG = 'en'
LOCALE       = 'C'

PATH         = 'content'
STATIC_PATHS = []

OUTPUT_PATH  = 'output'
#DELETE_OUTPUT_DIRECTORY = True # before site generation

DISPLAY_CATEGORIES_ON_MENU = False # choose a custom top menu here
MENUITEMS = (
  ('All',        'index.html'),
  ('Quickstart', 'quickstart.html'),
  ('Goodies',    'goodies.html'),
  ('Options',    'options.html'),
  ('#Tags',      'tags.html'),
)
DEFAULT_PAGINATION =   6; # article summaries per page
SUMMARY_MAX_LENGTH = 100; # counted in words

RELATIVE_URLS                    = True
SLUGIFY_SOURCE                   = 'basename' 
ARTICLE_URL   = ARTICLE_SAVE_AS  = '{slug}.html'
CATEGORY_URL  = CATEGORY_SAVE_AS = '{slug}.html'
TAG_URL       = TAG_SAVE_AS      = '{slug}.html'
AUTHOR_URL    = AUTHOR_SAVE_AS   = '{slug}.html'
ARCHIVES_SAVE_AS                 = 'archives.html'
YEAR_ARCHIVE_SAVE_AS             = 'archive_{date:%Y}.html'
MONTH_ARCHIVE_SAVE_AS            = 'archive_{date:%Y}_{date:%m}.html'
# =============================
# 2. Lepagito theme
# =============================
THEME = '/home/hesse/dvt-perso/lepagito'
FOOTERMENUITEMS = (
  ('About',    'about.html'),
  ('License',  'license.html'),
)
TAGS_BY_GROUPS = (
  ('Pelican', ('tag-group', 'navigation', 'plugin', 'pelicanconf.py')),
)
#FOOTERMENUFEED    = False; # default is True
#ARCHIVES_CALENDAR = False; # default is True
LEPAGITO_NAVIGATION_SWAP = True
LEPAGITO_COLOR = { 'cold': 0, 'file': 'color.css' } # the default value
# internationalization (i18n): here are the default values
I18N_CATEGORIES  = 'Categories'
I18N_CATEGORY    = 'Category'
I18N_TAGS        = '#Tags'
I18N_TOP         = 'Top'
I18N_PAGE        = 'Page'
I18N_READ_MORE   = 'Read more'
I18N_ARCHIVES    = 'Archives'
I18N_FEED_ALL_ATOM = 'Feed'
I18N_NEWEST      = 'Newest'
I18N_OLDEST      = 'Oldest'
I18N_FIRST       = 'First'
I18N_LAST        = 'Last'
I18N_BACK_TO     = 'Back to'
I18N_OTHERS      = 'Others'
I18N_PREV        = 'Prev'
I18N_NEXT        = 'Next'
# =============================
# 3. plugins, optionals
# =============================
PLUGIN_PATHS  = ['/home/hesse/dvt-perso/galleria/pelican/plugins', 
                 '/home/hesse/dvt-perso/theme-config/pelican/plugins',
                 '/home/hesse/pelican-plugins/search/pelican/plugins']
PLUGINS = ['search', 'sitemap', 'galleria', 'neighbors', 'theme_config']
# ------------------
# 3.1. search plugin
# ------------------
LEPAGITO_HAVE_SEARCH_MENU = ('search' in PLUGINS) # activate search menu
# -------------------
# 3.2. sitemap plugin
# -------------------
SITEMAP = {
    'format': 'xml',
    'priorities': {
        'articles': 1.0,
        'pages':    0.5,
        'indexes':  0.5
    },
    'changefreqs': {
        'articles': 'weekly',
        'pages':    'monthly',
        'indexes':  'monthly'
    }
}
# --------------------
# 3.3. galleria plugin
# --------------------
##THEME_TEMPLATES_OVERRIDES      = ['/home/hesse/dvt-perso/galleria/template']
GALLERIA_LIBRARY_PATH          = ['/home/hesse/dvt-perso/lepagito/doc/content']
LEPAGITO_GALLERY_CSS_FILE      = 'galleria.css'
# for lepagito templates:
GALLERIA_PROCESS_DIR           = 'galleria'
GALLERIA_RESIZE_JOBS           = 10
GALLERIA_VERBOSE               = True
GALLERIA_PROCESS = {
    'image-icon': {
        'type': 'image',
        'ops': ['50x50', '+profile "*"'],
    },
    'image-large': {
        'type': 'image',
        'ops': ['1200x900', '+profile "*"'],
    },
    # https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images
    'responsive-small': {
        'type': 'responsive-image',
        'sizes': (
            '(min-width: 768px) 650px, '
            '(min-width: 1200px) 800px, '
            '100vw'
        ),
        'srcset': [
            ('600w', ['600x450', '+profile "*"']),
            ('800w', ['800x600', '+profile "*"']),
        ],
        'default': '800w',
    },
    # https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture
   'picture-tag': {
       'type': 'picture',
       'sources': [
           {
               'name': 'default',
               'media': '(min-height: 640px)',
               'srcset': [
                   ( '640w', [ '640x480',  '+profile "*"']),
                   ('1024w', ['1024x683',  '+profile "*"']),
                   ('1600w', ['1600x1200', '+profile "*"']),
               ],
               'sizes': '100vw',
           },
           {
               'name': 'source-1',
               'srcset': [
                   ('1x', ['600x450']),
                   ('2x', ['800x600']),
               ]
           },
       ],
       'default': ('default', '640w'),
   },
}
GALLERIA_DEFAULT_CLASS         = 'responsive-small'
GALLERIA_SINGLE_CLASS          = 'image-large'
GALLERIA_ICON_CLASS            = 'image-icon'
GALLERIA_DEFAULT_MAX_HEIGHT    = '600px'

Remark in the first that all URLs are chosen as relative here:

RELATIVE_URLS = True
ARTICLE_URL   = ARTICLE_SAVE_AS  = '{slug}.html'
CATEGORY_URL  = CATEGORY_SAVE_AS = '{slug}.html'

Also, all output files (articles, categories, tags, ...) are written in the same "output/" directory, without any hierarchy. This setting is convenient, since it allows to develop and fully test the blog off-line before to upload it on its final destination: relative URLs, such as in the MENUITEMS, work both in off-line and in-line modes.

The second part of the configuration file contains the specific settings of the Lepagito theme: these settings are be described in the sections of the Goodies category. Finally, the third part of the pelicanconf.py file sets the optional plugins: see the Options category.

Groups of tags

2022-05-14T00:00:00+02:00

In many cases, the tag list becomes very long and contains heterogeneous tags. It should be better to group them: this feature is implemented in the Lepagito theme. For instance, in the pelicanconf.py file:

TAGS_BY_GROUPS = (
  ('Color',  ('blue', 'red', 'yellow')),
  ('State',  ('solid', 'liquid', 'gas')),
  ('Firtname', ('Isabelle', 'Pierre', 'Paul', 'Jacques')),)

If a tag appears in an article but has any defined group, it will appear in the 'Others' group.

Archives and calendar

2022-04-14T00:00:00+02:00

The Archives, available at the footer menu, starts with a calendar, that provides a concise view. Years and months are both links to periodic archives. In the pelicanconf.py file, the two following variables should be defined, for instance as:

YEAR_ARCHIVE_SAVE_AS  = 'archive_{date:%Y}.html'
MONTH_ARCHIVE_SAVE_AS = 'archive_{date:%Y}_{date:%m}.html'

The calendar view do not refer to any pelican plugin: this is an original functionality of the Lepagito theme. If you don't want the calendar to appear on the archives page, you could either not define at least one of these variable, or set:

ARCHIVES_CALENDAR = False

By default, this variable is True.

Footer menus

2022-03-14T00:00:00+01:00

This theme provides an optional horizontal menu located at the bottom if each page: the footer menu. It could be useful for contact and license entries:

FOOTERMENUITEMS = (
  ('About',    'about.html'),
  ('Contact',  'contact.html'),
  ('Links',    'links.html'),
  ('License',  'license.html'),
)

A second bottom horizontal menu presents the Archives and feeds. This menu is active by default and could be removed with:

FOOTERMENUFEED = False

Finally, a third bottom horizontal menu could optionally defined by the SOCIAL standard variable of the pelican environment. This variable is not used in the pelicanconf.py file of the present documentation. As for the MENUITEMS and FOOTERMENUITEMS variables, it consists of a list of tuples (title, url). Note that this menu points to pages such as about.html, and there is a corresponding about.rst source file that looks like:

About
------
:date: 2023-02-14
:status: hidden

Yes, we have writen this amazing blog!

Observe that such a file is not a blog article: it has the status hidden and do not appear in the navigation of articles.

Internationalization (I18N)

2022-02-14T00:00:00+01:00

All labels introduced by the present theme are modifiable. The present pelicanconf.py provides its complete list together with the default English values:

I18N_CATEGORY  = 'Category'
I18N_TAGS      = '#Tags'
I18N_TOP       = 'Top'
I18N_PAGE      = 'Page'
I18N_READ_MORE = 'Read more'
I18N_ARCHIVES  = 'Archives'
I18N_FEED_ALL_ATOM = 'Feed'
I18N_NEWEST    = 'Newest'
I18N_OLDEST    = 'Oldest'
I18N_FIRST     = 'First'
I18N_LAST      = 'Last'
I18N_BACK_TO   = 'Back to'
I18N_OTHERS    = 'Others'

Article navigation

2021-05-14T00:00:00+02:00

The navigation between two successive pagination of article summaries is presented at the bottom: it provides both Oldest/Newest pages and also Fist/Last, for efficiency. When reading articles, the navigation between previous and next articles is presented both at the top and the bottom. This navigation feature is implemented thanks to the pelican neighbors plugin.

By default, the oldest pages and article navigation links appear on the right, and newest on the left. The LEPAGITO_NAVIGATION_SWAP variable in the pelicanconf.py file allows to swap from left to write this navigation. This feature is useful when the chronology of a blog is not important, as in the present documentation of the lepagito theme: the newest article means only the first article to read.

Self-hosted search

2021-04-14T00:00:00+02:00

The search function appears at the right of the top menu bar. Rather than give up control and privacy to third-party search engine corporations, this function adds elegant and self-hosted search capability to your site. Last but not least, searches are really fast. The search function is implemented thanks to the pelican search plugin. The search engine is activated by the following line in the pelicanconf.py file:

SEARCH_MODE = 'output'

Note that the search function requires that the blog is installed: it do not work in the off-line mode. If you do not need searches on your site, e.g. your tags are sufficients, just remove the previous line from the pelicanconf.py and the search function will disappear from the top menu bar.

If you are in trouble when installing stork, that is necessary for running the pelican search plugin, you could just remove both this plugin and previous line from the pelicanconf.py:

PLUGINS = ['neighbors']
#SEARCH_MODE = 'output'

Sitemap

2021-03-14T00:00:00+01:00

The sitemap plugin generates a sitemap.xml file to facilitate the indexing of your site by search engines. There is nothing to configure, it works as a black-box.

Photo galleries

2021-02-14T00:00:00+01:00

Last but not the least, the galleria plugin allows to easily manage galleries of images. Especially, it nicely manages the automatic generation of thumbnails from images, as shown in the following gallery of watercolors due to Pirogh:

When you click on a thumbnail of a picture, a full resolution version of this picture is displayed. Also, try to resize the browser window and observe the responsive display of the gallery: the gallery is automatically readjusted and this is especially useful when displaying on mobile phones. Finally the thumbnail's image resolution itself is also responsive, in the sense that it takes into account the physical resolution of our window and screen resolution. See the source file of this documentation for a complete example and also the documentation of the galleria plugin for more.

To associate an image with an article, i.e. as an icon, add the metadata field. For restructured text .rst files, it writes:

:image: myimage.jpg

to the header of an article. Associated images improve navigation: icons are displayed together with article titles when browsing pages and Archives.

Custom colors

2021-01-14T00:00:00+01:00

All colors of the lepagito theme are customizable. The default color file is color.css and an alternate file could be specicied by using the LEPAGITO_COLOR_CSS_FILE variable in the pelicanconf.py, such as:

LEPAGITO_COLOR_CSS_FILE  = 'mycustomcolor.css'

Modifying by hand the color.css file is not obvious: for convenience, a python script mk_custom_color_css.py is provided in the static/css directory. It admits three arguments: the two first are the rotation angles for the hue of the warm and cold colors, and the third argument is the optional basename for the css output file. For zero rotation, enter the command:

python mk_custom_color_css.py 0 0 mycustomcolor

It will regenerate exactly the default color theme but in the file mycustomcolor.css. It also provides mycustomcolor.pig, which is the color set, suitable for the palette visualization software. This default color theme corresponds to a palette composed to two groups of colors, the warm magenta and cold blue groups:

The second image represent the color palette in the CIECAM Jab coordinate system, in the (a,b) plane: observe the two groups of colors. The present graph is obtained thanks to the palette visualization software.

Now, let us rotate the cold blue group, until reaching the yellow position on the palette:

python mk_custom_color_css.py 0 195 mycustomcolor
cd ../../doc
pelican content
firefox output/index.html &

We then obtain:

Let us now rotate the same group until it reaches the magenta position:

python mk_custom_color_css.py 0 120 mycustomcolor

The two groups are now superposed and we obtain a camaïeu:

Finally, the first warm group is also rotated until it reaches the blue position:

python mk_custom_color_css.py 240 120 mycustomcolor

The two initial groups are now swapped: