API Reference

The full reference to lamya’s API.

lamya.content_tree

The lamya.content_tree module provides a naive tree data structure implementation, specifically designed to serve as a base for generating static sites. The lamya.site_generator module utilises this to provide a static site generator, but users are also encouraged to write their own build scripts directly using the lamya.content_tree module.

class lamya.content_tree.ContentTree(name, user_data=None)

A tree implementation specific to parsing, modifying and generating the content for a static website.

This is the abstract base class.

Parameters

  • name – the name of the node

  • user_data – a convenience object for storing custom user data

  • parent – a handle to the parent node

  • ancestors – a list of all the ancestors starting from the direct parent

  • path – a pathlib.Path object containing the path to this node starting from the root

  • href – a pathlib.Path object containing the path to this node, corresponding to what’s deemed the correct way referencing the path as a URL

Constructor

Parameters

  • name – the name of the node

  • user_data – a convenience object for storing custom user data

property parent

Get the parent of the node.

parent_to(new_parent)

Parent this node to the new_parent.

Parameters

new_parent – the new parent to parent this node to

property ancestors

Get a list of ancestors, starting with the direct parent.

property path

Get the path of this node relative to the root.

property href

Returns the path of this node relative to the root, but only if this node is not an index_page to another node, in which case it returns the path of that node instead.

This corresponds to the fact that in the context of static websites the index.html page of a folder is in a path like {..}/folder/index.html and not {..}/folder/folder/index.html.

pprint(level=0)

Returns a pretty string displaying information about this node.

Parameters

level – the indentation level, so we support nesting

static from_directory(directory, accepted_file_types=None, post_create_callback=None)

Builds a ContentTree structure by walking a directory.

Parameters

  • directory – the directory to walk, which would usually be the content folder of a static website

  • accepted_file_types – a list of accepted file extensions. Defaults to markdown files only

  • post_create_callback – a function to be called after each node of the content tree is created. Defaults to None

class lamya.content_tree.Folder(name, user_data=None)

This class represents a subtree, or in the context of a static website a group/folder with pages or groups/folders underneath it.

You can think of it as the blog folder which is the parent to all the blog posts in a hypothetical personal website.

Parameters

  • children – a list of all the direct children of this node

  • index_page – the index_page node of this folder. If we follow the example of a blog folder, the index page is most likely a list of all the blog posts

Constructor

Parameters

  • name – the name of the node

  • user_data – a convenience object for storing custom user data

property children

Returns a list of all the direct children of this node.

add_child(child)

Adds a child to this node and unparents it from its previous parent.

Parameters

child – the child to be parented to this node

property index_page

The index page of this folder

property path

Get the path of this node relative to the root.

pprint(level=0)

Returns a pretty string displaying information about this node.

Parameters

level – the indentation level, so we support nesting

get(path)

Gets a descendant of this node by a path.

Parameters

path – a path, relative to this node, to the desired descendant

Raises

LookupError – if the path does not exist under this node

apply_func(func, include_index_pages=True, recursive=True)

Applies a function to all nodes in this subtree.

Parameters

  • func – the function to be applied

  • include_index_pages – whether to apply the function to index pages Default is True

  • recursive – whether to apply the function to all descendants or just the direct children. Default is True (all descendants)

to_groups(grouping_func, include_index_pages=True, recursive=True, filter_func=<function Folder.<lambda>>)

Sorts the descendants of this subtree into one or more groups, based on the return value of a grouping function.

Parameters

  • grouping_func – the function to group nodes by. It accepts a node and should return a string specifying the group to put the node in

  • include_index_pages – whether to apply the function to index pages. Default is True

  • recursive – whether to apply the function to all descendants or just the direct children. Default is True (all descendants)

  • filter_func – optional function to use as a filter

flat(include_index_pages=True)

Returns a one dimensional list of all descendants.

Parameters

include_index_pages – whether to apply the function to index pages. Default is True

leaves(include_index_pages=True)

Returns all the leaf nodes (pages or posts) in this subtree.

Parameters

include_index_pages – whether to apply the function to index pages. Default is True

filter(func, include_index_pages=True, recursive=True)

Returns a copy of this subtree with nodes filtered by the func arg.

Parameters

  • func – the filter function

  • include_index_pages – whether to apply the function to index pages. Default is True

  • recursive – whether to apply the function to all descendants or just the direct children. Default is True (all descendants)

filter_in_place(func, include_index_pages=True, recursive=True)

Filters nodes in this subtree by the func arg.

Parameters

  • func – the filter function

  • include_index_pages – whether to apply the function to index pages. Default is True

  • recursive – whether to apply the function to all descendants or just the direct children. Default is True (all descendants)

group(name, entities)

Groups the specified entities into a new folder inside of this folder.

Parameters

  • name – name of the new folder

  • entities – a list of ContentTree entities to group under the new parent

Raises

GroupError – if the list of entities is empty

as_dict(map_leaf=<function Folder.<lambda>>, map_folder=<function Folder.<lambda>>)

Returns a dict representing this subtree, with leaves and folders optionally remapped by mapping functions.

Parameters

  • map_leaf – the function to remap leaf nodes with

  • map_folder – the function to remap folder nodes with

class lamya.content_tree.Root(user_data=None)

The root of a content tree structure. The only difference with a regular folder is that the name is hardcoded to “/”.

Constructor

Parameters

user_data – a convenience object for storing custom user data

class lamya.content_tree.AbstractPageOrPost(name, source_path=None, source=None, user_data=None)

This is the base leaf node of the content tree, which in the context of a static website represents a post or a page.

Parameters

  • source_path – path to an optional corresponding source path

  • source – the source for this page or post. Either the source or the source_path need to be set on anything except for Aggregated[Groups]Pages, if the source is ever going to be requested, otherwise an error will be raised.

  • front_matter – if the front matter has been parsed this is a dict containing the front matter evaluated from the source

  • raw_content – this is the raw content of the source, meaning not yet processed by any markup processor

  • content – this is the markup processed content

Constructor

Parameters

  • name – name of this node

  • source_path – an optional path to a source file

  • source – optional source of this node

  • user_data – a convenience object for storing custom user data

property source_path

Returns the path to the source of this node

property source

Gets the source of this node. If the source has been directly set or read from the source_path then that’s returned. Otherwise, an attempt is made to read the source from the source_path and if that fails a PageOrPostWithoutSourceError is raised.

Raises

PageOrPostWithoutSourceError – if no source can be identified

render_path(build_path)

Get the path of this node relative to the root and append it to the build_path argument and adding index.html at the end.

Parameters

build_path – a pathlib.Path object specifying the path to append the current path of the node to

is_index_page()

Returns whether or not this page or post is the index page of its parent

property front_matter

If the front matter has already been parsed, returns a dict containing it, otherwise returns None and prints a warning.

property raw_content

If the content has been parsed, returns it raw as taken from the source, otherwise returns None and prints a warning

property content

If the content has been parsed, returns it processed by the markup processor, otherwise returns None and prints a warning.

parse_front_matter_and_content(front_matter_and_content_split_func=<function split_front_matter>)

Takes the source and splits its front matter from its content, storing them in self._front_matter and self._raw_content respectively.

Parameters

front_matter_and_content_split_func – the function to use for splitting the front matter from the content. By default uses the lamya.content_processing.split_front_matter() function.

process_content(markup_processor_func=None)

Processes the raw_content using the markup_processor_func.

Parameters

markup_processor_func – the function to process the raw_content with in order to produce the final content. By default it attempts to use the markdown.markdown function if markdown is available.

class lamya.content_tree.PageOrPost(name, source_path=None, source=None, user_data=None)

Giving a more explicit name to the class used for specific pages and posts.

Constructor

Parameters

  • name – name of this node

  • source_path – an optional path to a source file

  • source – optional source of this node

  • user_data – a convenience object for storing custom user data

class lamya.content_tree.CustomIndexPage(parent, source_path=None, source=None, user_data=None)

The class used for index pages that have been read from an index file, rather than procedurally generated.

Constructor

Parameters

  • parent – the parent this page is the index of

  • source_path – an optional path to a source file

  • source – optional source of this node

  • user_data – a convenience object for storing custom user data

class lamya.content_tree.ProceduralPage(name, source_path=None, source=None, user_data=None)

The base class for procedurally generated content tree pages.

Parameters

source – the difference with the AbstractPageOrPost.source property is that on ProceduralPage`s it is not required to have a `source or source_path defined, while one of them is required for an AbstractPageOrPost.

Constructor

Parameters

  • name – name of this node

  • source_path – an optional path to a source file

  • source – optional source of this node

  • user_data – a convenience object for storing custom user data

property source

Gets the source of this node. If the source has been directly set or read from the source_path then that’s returned. Otherwise, an attempt is made to read the source from the source_path and if that fails a PageOrPostWithoutSourceError is raised.

Raises

PageOrPostWithoutSourceError – if no source can be identified

class lamya.content_tree.AggregatedGroupsPage(name, aggregated_grouped_posts, source_path=None, source=None, user_data=None)

A procedurally generated page containing groups of posts, a great example of which is categories and archives.

Constructor

Parameters

  • name – name of this node

  • aggregated_grouped_posts – a dict with the group names for keys and the corresponding lists of posts as the values

  • source_path – an optional path to a source file

  • source – optional source of this node

  • user_data – a convenience object for storing custom user data

pprint(level=0)

Returns a pretty string displaying information about this node.

Parameters

level – the indentation level, so we support nesting

class lamya.content_tree.AggregatedPage(name, aggregated_posts, source_path=None, source=None, user_data=None)

A procedurally generated page containing a list of posts.

Constructor

Parameters

  • name – name of this node

  • aggregated_posts – a list of posts

  • source_path – an optional path to a source file

  • source – optional source of this node

  • user_data – a convenience object for storing custom user data

pprint(level=0)

Returns a pretty string displaying information about this node.

Parameters

level – the indentation level, so we support nesting

paginate(num_posts_per_page, post_create_callback=<function AggregatedPage.<lambda>>)

Splits this page into multiple pages.

Parameters

  • num_posts_per_page – number of posts per page

  • post_create_callback – a function to call on each generated page, after its creation

class lamya.content_tree.PaginatedAggregatedPage(name, aggregated_posts, pagination, source_path=None, source=None, user_data=None)

A paginated version of the AggregatedPage containing only a subset of all the posts belonging to the AggregatedPage this page was derived from.

Constructor

Parameters

  • name – name of this node

  • aggregated_posts – a list of posts

  • pagination – the Pagination object managing this page

  • source_path – an optional path to a source file

  • source – optional source of this node

pprint(level=0)

Returns a pretty string displaying information about this node.

Parameters

level – the indentation level, so we support nesting

paginate(*args)

Attempting to paginated a PaginatedPage will raise a PaginationError

Raises

PaginationError –

property path

Gets the path of this page.

This is slightly different since we have 2 extra rules: - if the index page of the parent is one of the pages belonging to the same pagination object this page does, then we return {parent_path}/page%%i ” - if there’s only one page we return an unpaginated path

class lamya.content_tree.Pagination(page_number, max_page_number, first_page, last_page, prev_page=None, next_page=None)

A data struct containing all the information for a paginated aggregated page.

We need an object like this, as the paginated pages are separate pages which don’t store references to each other.

Parameters

  • page_number – the page number corresponding to the page this pagination instance belongs to

  • max_page_number – the last page number

  • first_page – a reference to the first page in the pagination

  • last_page – a reference to the last page in the pagination

  • prev_page – a reference to the prev page in the pagination

  • next_page – a reference to the next page in the pagination

as_navigation_dict()

Returns a representation of this pagination object as a dictionary containing all the information necessary to correctly display a navigation structure inside an html template.

exception lamya.content_tree.LeafChildError

An error specifiyng attempted access to the child/subtree of a leaf node

exception lamya.content_tree.PageOrPostWithoutSourceError

An error specifiyng attempted access to the source code of a node which has none specified neither with a source_path nor directly set.

exception lamya.content_tree.PaginationError

An error when attempting to paginate an AggregatedPage, which can be triggered due to either not having any posts to paginate OR attempting to paginate an already paginated page.

exception lamya.content_tree.GroupError

An error raised when attempting to group an empty list of items into a subtree.

lamya.content_tree.warning(*args)

A utility function for displaying warnings.

The *args are directly passed into a print statement.

lamya.content_processing

This module provides a few utility functions for processing content and front matter.

lamya.content_processing.split_front_matter(source, front_matter_delimiter='+')

Splits and evaluates the front matter from the content’s source.

This function assumes the front matter is actual python code, which gets exec-ed to give us a dictionary of values.

Parameters

  • source – the input raw source

  • front_matter_delimiter – the delimiting character used for separating front matter from the rest of the content. The front matter should be surrounded by lines containing only delimiter characters.

lamya.content_processing.get_excerpt(content, remove_html_tags=True, excerpt_start_tag='<!--excerpt-start-->', excerpt_end_tag='<!--excerpt-end-->', fallback_num_characters=250, suffix='')

Extracts an excerpt from the provided content.

The excerpt can be extracted either from excerpt tags if they exist in the content or by just taking the first ~150 characters of clean text, where clean means without any html tags.

Parameters

  • content – the content to grab the excerpt from. Can either be processed or raw markup

  • remove_html_tags – whether or not to try removing html tags from the excerpt

  • excerpt_start_tag – an optional piece of string that can be use for specifying the beginning of the excerpt

  • excerpt_end_tag – an optional piece of string that can be use for specifying the ending of the excerpt

  • fallback_num_characters – if no delimiting tags were specified, take everything up to the first space after fallback_num_characters as the excerpt

  • suffix – optional suffix to add at the end of the excerpt. For when something like … is appropriate

lamya.content_processing.remove_html(x)

Uses regex to remove html tags.

Parameters

x – the string to try to rid of html

lamya.config

This module provides a base Config class defining the default parameters for running a static site generation process, which can be subclassed to overwrite only the properties you would like.

class lamya.config.Config

The base Config class defining the default argument values for a static site generation process.

You will most likely want to overwrite this class to change at least a few of the arguments.

NOTE: The arguments here are the same as those when running from the CLI, as this Config is meant to be used to run the whole site generation process, rather than just the initialization of the lamya.site_generator.SiteGenerator class.

Parameters

  • name – name of the site

  • url – url of the site

  • subtitle – optional subtitle of the site, generally used as a short description or motto

  • author_link – a URL to be placed in the link rel=author html tag

  • language – the language to be placed in the html lang property

  • use_absolute_urls – whether or not to use full absolute URLs instead of the default relative ones

  • posts_per_page – how many posts to have per page. Defaults to -1, which means no pagination.

  • publish_date_key – the key in the front matter to read the publish date from

  • read_date_format – the datetime format to expect the publish date in

  • display_date_format – the datetime format to display the publish date in

  • site_directory – the path to the site folder. If none of the following paths - content, theme, etc. are provided they will be folders inside this directory by default.

  • content_directory – the path to the top folder containing the site content

  • theme_directory – the path to the theme folder

  • static_directory – the path to a folder containing static files to be directly copied over to the build_directory

  • templates_directory – the path to a folder with render templates

  • build_directory – the path to a folder where to generate the website

  • home_name_in_navigation – the name under which the home page should appear in the navigation

  • exclude_categories_from_navigation – whether or not to exclude the category pages from the navigation if they exist

  • exclude_archive_from_navigation – whether or not to exclude any archive pages from the navigation if they exist

  • exclude_from_navigation – other lamya.content_tree entities to exclude from the navigation specified either by name or path, from the navigation if they exist

  • exclude_from_navigation – other lamya.content_tree entities to exclude from the navigation specified either by name or path

  • custom_navigation – a custom dict-like object specifying the navigation

  • locally_aggregate_whitelist – a list of folders that should have their children aggregated into their index pages. NOTE: only the whitelist OR the blacklist can be specified at a time, but not both.

  • locally_aggregate_blacklisk – a list of folders that should NOT have their children aggregated into their index pages. NOTE: only the whitelist OR the blacklist can be specified at a time, but not both.

  • globally_aggregate_whitelist – a list of pages or posts to aggregate into the home page. NOTE: only the whitelist OR the blacklist can be specified at a time, but not both.

  • globally_aggregate_blacklist – a list of pages or posts to NOT aggregate into the home page. NOTE: only the whitelist OR the blacklist can be specified at a time, but not both.

  • build_categories – whether to build category pages

  • do_not_allow_uncategorized – whether to error out if build_categories is True and there are posts without categories

  • categories_page_name – the name of the page containing all the posts grouped by their categories. If not provided, no such page will be generated.

  • group_categories – whether to group the category pages into a folder rather than generating them directly under the root

  • uncategorized_name – the name used to display uncategorized posts

  • build_archive_by_month – whether to build a monthly archive

  • build_archive_by_yearly – whether to build a yearly archive

  • archive_page_name – the name of the page containing all the posts grouped by their publish dates. If not provided, no such page will be generated.

  • group_archive – whether to group the archive pages into a folder rather than generating them directly under the root

  • display_by_month_in_list_page – whether to include the monthly archive in the archive_page_name page

  • display_by_year_in_list_page – whether to include the yearly archive in the archive_page_name page

  • archive_month_format – the datetime representation to group the the posts by month by

  • archive_year_format – the datetime representation to group the the posts by year by

  • theme_options – a dict-like object containing specific to the theme arguments

lamya.site_generator

The lamya.site_generator module provides a static site generator, that can be ran either from the CLI by running lamya as a module or by importing the lamya.site_generator.SiteGenerator class and using it in your own scripts.

The static site generator utilises the lamya.content_tree tree implementation to parse existing content and render it using a template engine (Jinja2 by default), while optionally aggregating content into list pages, categories and an archive.

class lamya.site_generator.Callbacks

A struct for specifying callbacks to be run at potential various stages of the static site generation process.

NOTE: At the moment it only contains a callback for immediately after lamya.content_tree.ContentTree node being created, but I’d like to have an easy way of adding more callbacks in the future.

static post_content_tree_entity_create(site_generator, entity)

Ran on every single lamya.content_tree.ContentTree instance created in the context of the site generator.

Parameters
class lamya.site_generator.RenderablePage(page_or_post)

This struct is what will be passed to the template engine, so all the properties are seralized into directly usable information.

Parameters

  • name – the name of the page or post, as taken directly from the name of the file it corresponds to if it hasn’t been overwritten

  • title – falls back to the name with underscores replaced with spaces and capital letters at the beginning of the words if a title wasn’t provided in the front matter

  • content – the processed markup ready for rendering

  • href – the relative URL of this page or post

  • site_url – the URL of the website

  • aggregated_posts – the list of posts if this is an aggregated page

  • aggregated_grouped_posts – the dict of groups and posts if this is an aggregated_grouped_post

  • pagination – the pagination dict if this is a paginated page

  • publish_date – the publish date as read from the front matter or if one wasn’t supplied, the last modified time of the source file

  • user_data – any custom user data that has been supplied

  • front_matter – the evaluated front matter

  • is_post – whether ot not this page represents a post or a page NOTE: the heuristic for defining this is really naive by default, but the is_page_func function can be specified on the SiteGenerator class

  • absolute_canonical_href – the canonical url for this page or post

  • breadcrumbs – the breadcrumbs navigation dict

Constructor

Parameters

page_or_post – the page or post to create a render struct for

class lamya.site_generator.SiteInfo(site_generator)

This struct represents all the site information to be passed to the template engine.

Parameters

  • name – the name of the site

  • url – the url of the site

  • subtitle – the subtitle of the site, generally used as a short description or motto

  • navigation – the navigation dict

  • lang – the language to specify in the html lang property

  • theme_options – a dict with the specified theme options

  • internal_data – similar to the user data of pages, but specified by the site generator

  • archive_nav – if an archive has been generated, this will be a navigation dict to all of the archive pages

  • category_nav – if categories have been generated, this will be a navigation dict to all of the category pages

  • display_date_format – the python datetime format to display the publish dates in

  • author_link – a link to an author page, to be used in the meta author tag

Constructor

Parameters

site_generator – the SiteGenerator object

class lamya.site_generator.SiteGenerator(name, url, subtitle='', content_directory=PosixPath('content'), theme_directory=None, static_directory=PosixPath('static'), templates_directory=PosixPath('templates'), build_directory=PosixPath('build'), locally_aggregate_whitelist=None, locally_aggregate_blacklist=None, globally_aggregate_whitelist=None, globally_aggregate_blacklist=None, num_posts_per_page=-1, is_page_func=<function SiteGenerator.<lambda>>, front_matter_delimiter='+', callbacks=<lamya.site_generator.Callbacks object>, lang='en', front_matter_publish_date_key='publish_date', read_date_format='%d-%m-%Y %H:%M', display_date_format='%B %-d, %Y', author_link='', theme_options=None, use_absolute_urls=False)

This class is responsible for generating a static website by aggregating, grouping and rendering existing content.

Parameters

  • name – name of the site

  • url – url of the site

  • subtitle – the subtitle of the site, generally used as a short description or motto

  • content_directory – the path to the top folder containing the site content

  • theme_directory – the path to the theme folder

  • static_directory – the path to a folder containing static files to be directly copied over into the built website

  • templates_directory – the path to a folder with templates that will overwrite the theme’s ones

  • build_directory – the path to a folder where to generate the website

  • locally_aggregate_whitelist – a list of folders that should have their content aggregated into an index page

  • locally_aggregate_blacklist – a list of folders that should NOT have their content aggregated into an index page

  • globally_aggregate_whitelist – a list of pages or posts to aggregate into the home page

  • globally_aggregate_blacklist – a list of pages or posts to NOT aggregate into the home page

  • num_posts_per_page – how many posts to have per page

  • is_page_func – a function that returns True if a piece of content is meant to be treated as a static page rather than as a post

  • front_matter_delimiter – we expect the front matter in the raw content of each page/post to be surrounded by lines containing only this character

  • callbacks – a Callbacks struct for running functions at specific times. NOTE: at the moment we only run after generating any lamya.content_tree node

  • lang – the language to put in the html lang property

  • front_matter_publish_date_key – the name of the publish date key in the front matter

  • read_date_format – the datetime format to expect the publish date in the front matter to be in

  • display_date_format – the datetime format to display the publish date in

  • author_link – a URL to be placed in the link rel=author html tag

  • theme_options – a dict of theme options

  • use_absolute_urls – whether or not to use full absolute URLs instead of the default relative ones

  • content_tree – the lamya.content_tree.Root node that contains the content of the static site

  • internal_data – a dict containing extra information about the site generation process

Constructor

Parameters

  • name – name of the site

  • url – url of the site

  • subtitle – optional subtitle of the site, generally used as a short description or motto

  • content_directory – the path to the top folder containing the site content. Defaults to a folder called content in the current directory. This folder is required to exist.

  • theme_directory – the path to the theme folder. This folder is required to exist. If None is specified, then the default theme will be used. None by default.

  • static_directory – the path to a folder containing static files to be directly copied over into the built website. Defaults to a folder called static in the current directory. This folder is not required to exist.

  • templates_directory – the path to a folder with templates that will overwrite the theme’s ones. Defaults to a folder called templates in the current directory. This folder is not required to exist.

  • build_directory – the path to a folder where to generate the website. Defaults to a folder called build in the current directory. The parent of this folder is required to exist.

  • locally_aggregate_whitelist – a list of folders that should have their content aggregated into an index page. Defaults to []. Either the whitelist or the blacklist can be specified, but not both.

  • locally_aggregate_blacklist – a list of folders that should NOT have their content aggregated into an index page. Defaults to []. Either the whitelist or the blacklist can be specified, but not both.

  • globally_aggregate_whitelist – a list of pages or posts to aggregate into the home page. Defaults to []. Either the whitelist or the blacklist can be specified, but not both.

  • globally_aggregate_blacklist – a list of pages or posts to NOT aggregate into the home page. Defaults to []. Either the whitelist or the blacklist can be specified, but not both.

  • num_posts_per_page – how many posts to have per page. Defaults to -1, which means infinitely many posts, i.e. no pagination.

  • is_page_func – a function that returns True if a piece of content is meant to be treated as a static page rather than as a post. Defaults to a function checking if the content’s parent is the root.

  • front_matter_delimiter – we expect the front matter in the raw content of each page/post to be surrounded by lines containing only this character. Defaults to ‘+’.

  • callbacks – a Callbacks struct for running functions at specific times. Defaults to the Callbacks struct defined in this module.

  • lang – the language to put in the html lang property. Defaults to ‘en’.

  • front_matter_publish_date_key – the name of the publish date key in the front matter. Defaults to publish_date.

  • read_date_format – the datetime format to expect the publish date in the front matter to be in. Defaults to %d-%m-%Y %H:%M.

  • display_date_format – the datetime format to display the publish date in. Defaults to %B %-d, %Y.

  • author_link – a URL to be placed in the link rel=author html tag. Defaults to “”.

  • theme_options – a dict of theme options. Defaults to {}.

  • use_absolute_urls – whether or not to use full absolute URLs instead of the default relative ones.

initialize_renderer()

This method initializes the template engine which will render the site.

By default we use jinja2, but overwriting this function and the render fundtion, should allow other template engines to be used.

initialize_markup_processor()

This method initializes the function which we will use to process the markup into html.

By default we use markdown, but overwriting this, should allow other markup processors to be used.

static run_from_config(config, render=True)

Use a lamya.config.Config object to configure the whole generation process, which is all contained in this one function.

Notably, the only reason to use this instead of providing a file with all the parameters to the –from_file argument of the CLI, is to have some other optional custom steps between building the site and rendering it.

Parameters

  • config – the lamya.config.Config object, containing all the arguments

  • render – whether or not to render the website at the end of the function or leave that to the user, so other changes can be made before that happens

Returns

the built SiteGenerator object

process_content_tree()

This method goes through all of the content, read from the content directory and ensures we have all the data we require for them.

At the moment it only tries to read a publish_date for each page.

aggregate_posts()

This method uses the aggregation arguments passed to the constructor to aggregate posts into index pages.

build_category_pages(parent=None, category_accessor=<function SiteGenerator.<lambda>>, allow_uncategorized=True, uncategorized_name='Uncategorized', leaves_filter=<function SiteGenerator.<lambda>>, category_list_page_name='categories', group=True)

This method reads categories from the content’s front matter and groups them into category pages.

Parameters

  • parent – the lamya.content_tree parent node to put the category pages in. If None the root will be used.

  • category_accessor – a function defining how to query the category for each page or post node. By default it attempts to read it from the category key in the front matter.

  • allow_uncategorized – whether or not to allow some pages or posts to be uncategorized or to error out if such pages or posts are found

  • uncategorized_name – the name of the category to use for posts that do not have a category

  • leaves_filter – an optional function to be used for filtering the leaves that should be processed

  • category_list_page_name – the name to give to the page, containing all categories and their posts. If it is falsy, no such page will be generated.

  • group – whether or not to group all category pages under a categories folder

build_archive(by_month_format='%B, %Y', by_year_format='%Y')

This method builds the archive struct, with all the posts in their correct groups.

Parameters

  • by_month_format – the datetime format to use for grouping and sorting posts by month

  • by_year_format – the datetime format to use for grouping and sorting posts by year

Returns

the built Archive struct

build_archive_pages(parent=None, by_month=True, by_year=False, archive_list_page_name='archive', group=True, display_by_month_in_list_page=True, display_by_year_in_list_page=True)

This method takes the previously built Archive struct and generates the archive pages.

Parameters

  • parent – the lamya.content_tree parent node to put the archive pages in

  • by_month – whether or not to write pages for the monthly archive

  • by_year – whether or not to write pages for the yearly archive

  • archive_list_page_name – the name to give to the page, containing all archive groups and their posts. If false, no such page will be generated.

  • group – whether or not to group all archive pages under an archives folder

  • display_by_month_in_list_page – whether to include the monthly archive in the list page

  • display_by_year_in_list_page – whether to include the yearly archive in the list page

posts()

Returns all leaves that DO NOT pass the is_page_func test.

build_navigation(filter_func=None, extra_filter_func=None, exclude_categories=False, exclude_archive=False)

Builds a navigation structure.

Parameters

  • filter_func –

    a function to filter out pages from the navigation. If None a default function will be used, which boils down to adding pages to the navigation if any of the following are true:

    • the node passes the is_page_func or it is a

      lamya.content_tree.Folder

    • the node is an index_page

    • the node is a category page and categories are not excluded

    • the node is an archive page and the archive is not excluded

    AND BOTH of the following are true:

    • this node is not the home page

    • if this node is part of a pagination, it is the first page, otherwise

      assume True

  • extra_filter_func – a second filtering function, so if a bit of extra filtering is required on top of the default function it can easily be provided

  • exclude_categories – whether or not to exclude any category pages from the navigation

  • exclude_archive – whether or not to exclude any archive pages from the navigation

render(to_renderable_page=<class 'lamya.site_generator.RenderablePage'>, to_site_info=<class 'lamya.site_generator.SiteInfo'>, markup_processor_func=None, template_accessor_func=<function SiteGenerator.<lambda>>, **kwargs)

This method renders the site into the build folder.

Parameters

  • to_renderable_page – a function that converts an AbstractPageOrPost into a struct containing the information necessary for rendering that page or post. That struct is then passed to the template engine. Default is RenderablePage.

  • to_site_info – a function that converts the SiteGenerator into a struct containing the information necessary for the template. Default is SiteInfo.

  • markup_processor_func – an optional markup processing function. If None the markup_processor_func property of the class will be used. Default is None.

  • template_accessor_func – a function specifying how to choose a template for each leaf node. Defaults to checking if there’s a ‘template’ argument in the front matter and if not uses ‘default.html’.

  • kwargs – any other optional information to pass to the template engine

class lamya.site_generator.Jinja2Renderer(template_directories)

A thin wrapper around the jinja2 environment to provide a framework for using different renderers.

Parameters

environment – the jinja2 environment

Constructor

Parameters

template_directories – a number of paths to look for templates in

render(template, **render_data)

Renders the given template, with the passed in render date.

Parameters

  • template – the template to use for rendering

  • render_data – any data to be passed to the template engine

class lamya.site_generator.Categories(posts_by_category, pages_by_category, list_page, folder, uncategorized_name)

A struct grouping all the relevant categories information.

Parameters

  • posts_by_category – a dict containing all the posts belonging to specific categories

  • pages_by_category – a dict mapping a category name to the category page

  • list_page – the optional page containing all categories and their posts that may have been built

  • folder – an optional folder if the categories have been grouped

  • uncategorized_name – the name of the uncategorized category

Constructor

Parameters

  • posts_by_category – a dict containing all the posts belonging to specific categories

  • pages_by_category – a dict mapping a category name to the category page

  • list_page – the optional page containing all categories and their posts that may have been built

  • folder – an optional folder if the categories have been grouped

  • uncategorized_name – the name of the uncategorized category

property all_pages

This method returns all category pages, except for the list page.

as_navigation_dict()

This method maps the categories structure into a simple dict, so it can be accessed in the template engine.

class lamya.site_generator.Archive(posts_by_month, posts_by_year)

A struct grouping all of the relevant archives information.

Parameters

  • posts_by_month – the posts grouped into a mapping by month

  • posts_by_year – the posts grouped into a mapping by year

  • pages_by_month – the pages grouped into a mapping by month

  • pages_by_year – the pages grouped into a mapping by year

  • list_page – the optional page containing all archives and their posts

Constructor

Parameters

  • posts_by_month – the posts grouped into a mapping by month

  • posts_by_year – the posts grouped into a mapping by year

  • pages_by_month – the pages grouped into a mapping by month

  • pages_by_year – the pages grouped into a mapping by year

  • list_page – the optional page containing all archives and their posts

property all_pages

This property returns all pages by month and year.

as_navigation_dict()

This method returns a simple dict containing all the archive posts and pages information, so it can be easily accessed in the template engine.

exception lamya.site_generator.AggregateError

Raised when attempting to use both a whitelist and a blacklist for specifying content to be aggregated.

exception lamya.site_generator.UncategorizedNotAllowedError

Raised when a category is required, but none has been specified.

exception lamya.site_generator.ArchivePagesError

Raised when an attempt is made to create the archive pages, before the content has been created or when there’s nothing to archive.