StaticJinjaPlus

StaticJinjaPlus is a tool to build static sites using Jinja.

Content

• How to install
• Building sites
  • Watching for changes
  • Specifying templates or build paths
  • Using assets
  • Using context
  • Шаблоны extends и include
• Example templates

How to install

Python should already be installed. This project requires Python3.7 or newer.

Clone the repo / download code.

Using virtual environment virtualenv/venv is recommended for project isolation.

Install requirements:

pip install -r requirements.txt

To check that everything installed correctly try running the script with --help flag:

python main.py --help

Output:

usage: main.py [-h] [-w] [--srcpath SRCPATH] [--outpath OUTPATH]

Render HTML pages from Jinja2 templates

options:
  -h, --help         show this help message and exit
  -w, --watch        Render the site, and re-render on changes to <srcpath>
  --srcpath SRCPATH  The directory to look in for templates (defaults to './templates)'
  --outpath OUTPATH  The directory to place rendered files in (defaults to './build')

Now you're all ready to build your static sites!

Building sites

Note: see Example templates section for an example with sample templates. Rename the /templates_example folder to /templates to run test templates.

To render html pages from templates, run:

python main.py

This will look in ./templates for templates (files whose name does not start with . or _) and build them to ./build.

You'll see a message about each template in the output:

Rendering index.html...

Watching for changes

To watch for changes in the templates and recompile build files if changes happen, use -w or --watch argument.

python main.py -w

Rendering index.html...
Watching '/home/mrdave/Python Projects/StaticJinjaPlus/templates' for changes...
Press Ctrl+C to stop.

Specifying templates or build paths

To change the source and/or output paths use optional arguments:

• --srcpath - the directory to look in for templates (defaults to ./templates)
• --outpath - the directory to place rendered files in (defaults to .)

Example:

python main.py --srcpath other_template_folder --outpath ./built/site

Rendering index.html...

Using assets

To use assets such as .css and .js files with your templates, place them in assets folder inside source path (so ./templates/assets by default). In this case StaticJinjaPlus will copy the assets to output folder keeping the same relative paths.

Building log will also include "rendering" the assets:

python main.py

Rendering assets/style.css...
Rendering index.html...

Using context

It is possible to pass context for use in your templates by setting environmental variables named as you use them in the templates with the "SJP_" prefix.

As an example, if your template includes thing variable, pass the SJP_THING env variable before building.

<!-- html template -->
<div class="container">
    <h1>Welcome to our website!</h1>
    <p>This is the homepage content. Replace it with your own.</p>
    <p>The thing from context is {{ thing }}</p>
</div>

export SJP_THING="my_thing"
python main.py

Шаблоны extends и include

• Вызов extends используется когда шаблоны должны иметь одинаковую базовую структуру, одну и ту же разбивку по блокам, но с разным содержимым для этих блоков. Это позволяет сформировать единообразный стиль сайта, когда веб-страницы имеют одни и те же структурные элементы - меню, хедер, футер, сайдбары и так далее.

Пример кода:

<!-- index.html file -->

{% extends '_base.html' %}

• Вызов include добавляет в нужное место кусок шаблона. Название подключаемого шаблона передается в качестве параметра.

Пример вызова include для файла _card.html из index.html. Имя файла _card.html имеет префикс «_» что объявляет его вспомогательным (подключаемым). При изменении вспомогательного файла рендерятся все файлы в которых есть к нему обращения. В данной конструкции передадим еще две переменные page и number.

<!-- index.html file -->

{% with page="Домашняя", number=1 %}
  {% include "_card.html" %}
{% endwith %}

Пример кода с переменными page и number.

<!-- _card.html file -->

<p>Вывод текста из файла _card.html методом include. Страница {{page}} Номер {{number}} </p>

Example templates

The repository has example templates to see how StaticJinjaPlus works.

Run the following command and see your results in ./build:

python main.py --srcpath example/templates

build
├── about.html
├── assets
│  └── style.css
├── faq.html
└── index.html

Example render of index.html