alteza 0.7.6

Super-flexible Static Site Generator

Alteza

Alteza is a static site generator driven by PyPage. Examples of other static site generators can be found here.

The differentiator with Alteza is that the site author (if familiar with Python) will have a lot more fine-grained control over the output, than what (as far as I'm aware) any of the existing options offer.

The learning curve is also shorter with Alteza. I've tried to follow part of xmonad's philosophy of keeping things small and simple. Alteza doesn't try to do a lot of things; instead it simply offers the core crucial functionality that is common to most static site generators.

Alteza also imposes very little required structure or a particular "way of doing things" on your website (other than requiring unique names). You retain the freedom to organize your website as you wish. (The name Alteza comes from a word that may be translated to illustriousness in Español.)

A key design aspect of Alteza is writing little scripts and executing such code to generate your website. Your static site can contain arbitrary Python that is executed at the time of site generation. PyPage, in particular, makes it seamless to include actual Python code inside page templates. (This of course means that you must run Alteza with trusted code, or in an isolated container.)

Installation

You can install Alteza easily with pip:

pip install alteza

Try running alteza -h to see the command-line options available.

User Guide

1. The directory structure is generally mirrored in the generated site.

2. By default, nothing is copied/published to the generated site.

   • A file must explicitly indicate using a public: true variable/field that it is to be published.
     • Therefore, directories with no public files do not exist in the generated site.
   • Files reachable from marked-as-public files will also be publicly accessible.
     • Here, reachability is discovered when a provided link function is used to link to other files.

3. All file and directory names, except for index page files, at all depth levels must be unique. This is to simplify use of the link(name) function. With unique file and directory names, one can simply link to a file or directory with just its name, without needing to disambiguate a non-unique name with its path. Note: Directories can only be linked to if the directory contains an index page.

4. There are two kinds of files: static asset files, and PyPage (i.e. dynamic template or content) files. PyPage files get processed by the PyPage template engine.

5. Static asset files are not read by Alteza. They are selectively either symlinked or copied to the output directory (you can choose which, with a command-line argument). Here, selectively means that they are exposed in the output directory only if they are linked to from a PyPage file using a special Alteza-provided link(name) function.

6. PyPage files are determined based on their file name extension. They are of two kinds:

   1. Markdown files (i.e. files ending with .md).
   2. Any file with a .py before its actual extension (i.e. any file with a .py before the last . in its file name). These are Non-Markdown Pypage files.

7. There is an inherited "environment"/env (this is just a collection of Python variables) that is injected into the lexical scope of every PyPage file, before it is processed/executed by PyPage. This env is a little different for each PyPage invocation--a copy of the inherited is env is created for each PyPage file. More on env in a later point below.

8. Non-Markdown Pypage files are simply processed with PyPage as-is (and there is no template application step for non-Markdown PyPage files). The .py part is removed from their name, and the output/result is copied to the generated site.

9. Markdown files:

   1. Markdown files are first processed with PyPage, with a copy of the inherited env.

   2. After this, the Markdown file is converted to HTML using the Python-Markdown library.

   3. Third, they have their "front matter" (if any) extracted using the Python-Markdown's library Meta-Data extension/feature.

      1. The first line with a --- in the Markdown file ends the front matter section.
      2. The front matter is processed by Alteza as YAML using the PyYAML.

   4. The fields from the YAML front matter the fields are injected into the env/environment.

   5. The HTML is injected into a content variable in env, and this env is passed to a template specified in configuration, for a second round of processing by PyPage. (Note: PyPage here is invoked on the template.)

      1. Templates are HTML files processed by PyPage. The PyPage-processed Markdown HTML output is passed to the template as the content variable. The template itself is then executed by PyPage.

      2. The template should use this content value via PyPage (with {{ content }}) in order to inject the content into itself.

      3. The template is defined using a template variable declared in a __config__.py file. (More on configuration files in a later point below.)

      4. The template's value must be the entire contents of a template PyPage-HTML file. A convenience function readfile is provided for this. So you can write something like template = readfile('some_template.html') in a config file.

      5. Templates may be overriden in descendant __config__.py files. Or, may be overridden in the Markdown file itself using a PyPage multiline code tag (not an inline code tag).

   6. Markdown files result in a directory with the base name (i.e. without the .md extension), with an index.html file containing the Markdown's output.

10. The Environment (env) and Configuration (__config__.py, etc.):

    1. Note: Python code in both .md and other .py.* files are run using Python's built-in exec (and eval) functions, and when they're run, we passed in a dictionary for their globals argument. We call that dict the environment, or env.

    2. Configuration is done through file(s) called __config__.py.

       1. First, we recursively go through all directories top-down.

       2. At each directory (descending downward), we execute an __config__.py file, if one is present. After execution, we absorb any variables in it that do not start with a _ into the env dict.

       • This behavior cna be used to override values. For example a top-level directory can define a default_template, which can then be overriden by inner directories.

    3. The deepest .md/.py.* files get executed first. After it executes, we check if a env contains a field public that is set as True. If it does, we mark that file for publication. Other than recording the value of public after each dynamic file is executed, any modification to env made by a dynamic file are discarded (and not absorbed, unlike with __config__.py).

       • I would not recommend using __config__.py to set public as True, as that would make the entire directory and all its descendants public (unless that behavior is exactly what is desired). Reachability with link (described below) is, in my opinion, a better way to make only reachable content publicly exposed.

11. The Name Registry and the link function.

    1. The name of every file in the input content is stored in a "name registry" of sorts that's used by link.

       1. Currently, names, without their file extension, have to be unique across input content. This might change in the future.

       2. The Name Registry will error out if it encounters any non-unique names. (I understand this is a significant limitation, so I might support marking this simply opt-in behavior with a --unique flag in the future.)

    2. Any non-dynamic content file that has been link-ed to is marked for publication (i.e. copying or symlinking).

    3. A Python function named link is injected into the top level env.

       1. This function can be used to get relative links to any other file. link will automatically determine and return the relative path to a file.

          • For example, one can do <a href="{{link('some-other-blog-post')}}">, and the generated site will have a relative link to it (i.e. to its directory if a Markdown file, and to the file itself otherwise).

       2. Reachability of files is determined using this function, and unreachable files will be treated as non-public (and thus not exist in the generated site).

    4. The extension must be omitted for dynamic PyPage files; specifically, the .md for Markdown, and the .py* for any file with .py before its extension.

       • i.e., e.g. one must write link('magic-turtle') for the file magic-turtle.md, and link('pygments-styles.css') for the file pygments-styles.py.css.
       • Directions with index files should just be referred to by the directory name. For example, the index page about-me/hobbies/index.md (or about-me/hobbies/index.py.html) should just be linked to with a link('hobbies').

Usage, Testing & Development

Running

If you've installed Alteza with pip, you can just run alteza, e.g.:

alteza -h

If you're working on Alteza itself, then run the alteza module itself, from the project directory directly, e.g. python3 -m alteza -h.

Command-line Arguments

The -h argument above will print the list of available arguments:

usage: __main__.py [--copy_assets] [--trailing_slash] [--content CONTENT] [--output OUTPUT] [-h]

options:
  --copy_assets         (bool, default=False) Copy assets instead of symlinking to them
  --trailing_slash      (bool, default=False) Include a trailing slash in links to markdown pages
  --content CONTENT
                        (str, default=test_content) Directory to read the input content from.
  --output OUTPUT
                        (str, default=test_output) Directory to send the output. WARNING: This will be deleted first.
  -h, --help            show this help message and exit

As might be obvious above, you set the content to your content directory. The output directory will be deleted entirely, before being written to.

To test against test_content (and generate output to test_output), run it like this:

python -m alteza --content test_content --output test_output

Code Style

I'm using black. To re-format the code, just run: black alteza. Fwiw, I've configured my IDE (PyCharm) to always auto-format with black.

Type Checking

To ensure better code quality, Alteza is type-checked with five different type checking systems: Mypy, Meta's Pyre, Microsoft's Pyright, Google's Pytype, and Pyflakes; as well as linted with Pylint.

To run some type checks:

mypy alteza  # should have zero errors
pyflakes alteza  # should have zero errors
pyre check  # should have zero errors as well
pyright alteza  # should have zero errors also
pytype alteza  # should have zero errors too

Or, all at once with: mypy alteza ; pyflakes alteza ; pyre check ; pyright alteza ; pytype alteza. Pytype is pretty slow, so feel free to omit it.

Linting

Linting policy is very strict. Pylint must issue a perfect 10/10 score, otherwise the Pylint CI check will fail.

To test whether lints are passing, simply run:

pylint -j 0 alteza

To run it along with all the type checks (excluding pytype), just run: mypy alteza ; pyre check ; pyright alteza ; pyflakes alteza ; pylint -j 0 alteza. I run this often.

Of course, when it makes sense, lints should be suppressed next to the relevant line, in code. Also, unlike typical Python code, the naming convention generally-followed in this codebase is camelCase. Pylint checks for names have mostly been disabled.

Dependencies

To install dependencies for development, run:

python3 -m pip install -r requirements.txt
python3 -m pip install -r requirements-dev.txt

To use a virtual environment (after creating one with python3 -m venv venv):

source venv/bin/activate
# ... install requirements ...
# ... do some development ...
deactive # end the venv

---

License

This project is licensed under the AGPL v3, but I'm reserving the right to re-license it under a license with fewer restrictions, e.g. the Apache License 2.0, and any PRs constitute consent to re-license as such.