Lepagito - Quickstart

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.