Site Developer Documentation

.siteignore files

A .siteignore is a file that indicate which path must not be collected to build the site. It can be fond at root but also in any directory.

It's file format is as follow:

• each line defines a "path expression" which resolves to multiple paths to ignore.

• a line can be empty

• path expression follow the python glob syntax

• path expression MUST be relative to the .siteignore file directory

• path expression may resolve to non-existing paths

.siteignore files are cumulative, this means that their paths are made absolute then grouped together and its this list which is used to ignore paths.

Example:

.siteignore
   **/.*.html
   *.txt
index.html
somestuff.txt
blog/
   .siteignore
      **/*.cpp
   index.html
   .template.html
   snippet.cpp
   resource.txt

In the above we have an expression at root that will ignore all html files that starts with a dot, the ** is a glob pattern which express recursion, meaning that blog/.template.html will be ignored. We will also ignore somestuff.txt but NOT resource.txt.

We then ignore blog/snippet.cpp.

shelf feature

TBD

build process

This is how the source file structure is parsed the site final file structure:

• collect all file paths in the source directory and ignore some paths using the .siteignore files.

• read and convert rst file as pages

• collect shelves

• render pages with their template and write to disk

• write shelves pages to disk

• copy static resources

See lxmsite._build for the code implementation.

writing rst content

See https://docutils.sourceforge.io/docs/user/rst/quickref.html.

page metadata

This are the fields that are understood as page metadata:

Some extra fields may be used depending on the context:

blog context:

name	description
category	(optional) which type of content is the page
cover	(optional) path to an image to display on top of the blog post.
cover-alt	(optional) the alt text for the cover image.

resources context:

name	description
category	(optional) which type of content is the page

A field is specified under the page title as :field-name: value. Example:

my page
=======

:description: this is quite a long summary that would be
   cool to wrap on 2 lines.

See lxmsite._page for the code implementation.

rst directives

In extent to the builtin rst directives ( https://docutils.sourceforge.io/docs/ref/rst/directives.html ), we provides additional directives, or edit the existing ones.

Here is a quick directive's glossary as reminder:

.. directivename:: argument1 argument2
    :option1:
    :option2:

    content

.. code:: languageName
    :option1: optionValue

    your code
    in multiple lines

.. admonition:: 🍕 About pizza
    :class: warning

    Pineapple do belongs on them.

.. highlight::
    :class: tip

    Look ma', no hands !

url-preview

This is a customd directive which allow you to share links as "static embeds", meaning they have the box with rich content that is prettier than just a link, but you actually have to write all the rich content yourself instead of having fetch using javascript.

It required one mandatory argument which is the url to "prettify".

The directive have 4 options:

• title: title to use for the preview

• image: url to an image file (relative or absolute).

• svg: relative url to a local svg file (relative to the page directory).

• color: the css color of the svg.

• svg-size: 1 or 2 number indicating the size of the svg. ex: '64' will set the svg to 64x64 px

The content of the directive will be used as description.

Example:

.. url-preview:: https://liamcollod.xyz
    :title: Website - Liam Collod
    :image: ../.static/images/cover-social.jpg

    Check my website & blog. VFX, imaging and software development.

Website - Liam Collod

https://liamcollod.xyz

Check my website & blog. VFX, imaging and software development.

.. image-grid::

    path/to/image1.jpg
    path/to/image2.jpg

    path/to/image3.jpg some caption that will be displayed under
    path/to/image4.jpg the caption can span
        multiple lines if it's too long.
    path/to/image5.jpg

.. image-gallery::
    :left: image1
    :right: label1, image2, label2
    :left-width: 35
    :right-width: 65

    .. image-frame:: image1 label1 photo1.jpg
        :metadata:
            date: 2024-11 early morning
            location: France - Lyon - Parc de la Tete d’Or
            film: 35mm Kodak Gold 200
            lens: Minolta MD 35mm

        some of the text descrption of the image
        that can span multiple lines

    .. image-frame:: image2 label2 photo2.jpg.meta
        :metadata:
            author: Liam

        -- {caption} -- (shot on {camera})

photo-cat.png > photo-cat.png.meta

camera: Lumix S5IIX
description: here is some text that
    will be spanning multiple lines
date: Monday

script system

The jinja syntax is not enough and you wish some part of the template was procedurally generated ? You can use the script include system to run an arbitrary python script that generates html (or actually anything).

To create a script, create a standard python file next to the template (can actually be stored anywhere but you need to specify its path relative to the template it is used in). Inside, you only need to declare one mandatory function:

def generate(template_renderer: lxmsite.TemplateRenderer) -> str:
    # your implementation here

The function when executed will return the text that need to be included in the template. The only argument template_renderer is a copy of the instance that is responsible of rendering the template that the script was called from. It allows in theory to recursively render another jinja template from the script or use its attributes for whatever you might need.

To use a script inside a template you use the include_script_output variable that is actually a function to call with the script path (relative to the template):

<div>
    {{ include_script_output("script_name.py") }}
</div>

cross-referencing

How to link to other html pages or static content ?

First, reminder that all relative urls are relative to the page they are on. This mean that if you want to link to a resources based on its site root location, like .static/icon/icon.svg you will need to make it relative to the page instead. This is easily done using the custom jinja filter mkpagerel.

Example:

<img src="{{ ".static/icons/icon.svg"|mkpagerel }}">

If you need the opposite you can also use mksiterel to make an page-relative url; relative to the site root instead.

And if you ever need an absolute url you can use mksiteabs that will prepend the site url but only on publish.

Then when linking pages or content, you must link a file, never a directory. While once published work/myproject/ might resolve fine by the server, locally it will not and you will need to link work/myproject/index.html instead. However just because this make links uglier you can use prettylink that will shorten the links on publish; best of both worlds !