CLI Reference

An opinionated static site generator using the `lamya` library

 [-h] [-ff FROM_FILE] [-n NAME] [-url URL] [-st SUBTITLE] [-al AUTHOR_LINK] [-l LANGUAGE]
 [-uau] [-pp POSTS_PER_PAGE] [-pdk PUBLISH_DATE_KEY] [-rdf READ_DATE_FORMAT]
 [-ddf DISPLAY_DATE_FORMAT] [-sd SITE_DIRECTORY] [-cd CONTENT_DIRECTORY]
 [-thd THEME_DIRECTORY] [-td TEMPLATES_DIRECTORY] [-std STATIC_DIRECTORY]
 [-bd BUILD_DIRECTORY] [-hn HOME_NAME_IN_NAVIGATION] [-ecn] [-ean]
 [-en EXCLUDE_FROM_NAVIGATION [EXCLUDE_FROM_NAVIGATION ...]] [-cn CUSTOM_NAVIGATION]
 [-law LOCALLY_AGGREGATE_WHITELIST [LOCALLY_AGGREGATE_WHITELIST ...]]
 [-lab LOCALLY_AGGREGATE_BLACKLIST [LOCALLY_AGGREGATE_BLACKLIST ...]]
 [-gaw GLOBALLY_AGGREGATE_WHITELIST [GLOBALLY_AGGREGATE_WHITELIST ...]]
 [-gab GLOBALLY_AGGREGATE_BLACKLIST [GLOBALLY_AGGREGATE_BLACKLIST ...]] [-bc] [-ac]
 [-cpn CATEGORIES_PAGE_NAME] [-gc] [-un UNCATEGORIZED_NAME] [-abm] [-aby]
 [-apn ARCHIVE_PAGE_NAME] [-ga] [-damp] [-dayp] [-amf ARCHIVE_MONTH_FORMAT]
 [-ayf ARCHIVE_YEAR_FORMAT]

optional arguments

  • -h, --help - show this help message and exit

  • -ff FROM_FILE, --from_file FROM_FILE - read the arguments from a python file, e.g. python -m lamya -ff config.py. If supplied, all extra command line arguments will be treated as overrides for the config file. (default: None)

  • -n NAME, --name NAME - the name of the website. Defaults to current directory name. (default: None)

  • -url URL, --url URL (default: None)

  • -st SUBTITLE, --subtitle SUBTITLE - the subtitle of the website, usually a short sentence. Defaults to ‘’. (default: None)

  • -al AUTHOR_LINK, --author_link AUTHOR_LINK - author link to be used as a fallback for page/post front matter author_link key, when specifying the author using the <link rel=``’author’`` ..> tag. Defaults to the ‘’. (default: )

  • -l LANGUAGE, --language LANGUAGE - the language of the website as required by the HTML lang attribute. Default is 'en'. (default: en)

  • -uau, --use_absolute_urls - whether or not to use absolute URLs. It is only recommended to use this flag if you``’d like to access the website directly from the filesystem using the ‘``file://’ scheme, rather than serving it. (default: False)

  • -pp POSTS_PER_PAGE, --posts_per_page POSTS_PER_PAGE - number of posts on per page (pagination). If set to -1 no pagination will be applied. (default: -1)

  • -pdk PUBLISH_DATE_KEY, --publish_date_key PUBLISH_DATE_KEY - the key used to specify the 'publish_date' in the front matter. Defaults to 'publish_date'. (default: publish_date)

  • -rdf READ_DATE_FORMAT, --read_date_format READ_DATE_FORMAT - the expected date format for reading the 'publish_date' key in the front matter. Default is %%d-%%m-%%Y %%H:%%M. (default: %d-%m-%Y %H:%M)

  • -ddf DISPLAY_DATE_FORMAT, --display_date_format DISPLAY_DATE_FORMAT - the format to display the publish date in. Default is %%B %%-d, %%Y. (default: %B %-d, %Y)

Paths

  • -sd SITE_DIRECTORY, --site_directory SITE_DIRECTORY - the path to the site directory. Defaults to the current directory. (default: .)

  • -cd CONTENT_DIRECTORY, --content_directory CONTENT_DIRECTORY - the path to the content directory of the site. Defaults to `{site_directory}/content`. (default: None)

  • -thd THEME_DIRECTORY, --theme_directory THEME_DIRECTORY - the path to the directory of the theme. Defaults to `{site_directory}/theme`. (default: None)

  • -td TEMPLATES_DIRECTORY, --templates_directory TEMPLATES_DIRECTORY - the path to the a directory, containing optional overrides of the theme’s templates. Defaults to `{site_directory}/templates`. (default: None)

  • -std STATIC_DIRECTORY, --static_directory STATIC_DIRECTORY - the path to a directory, containing static files that will directly be copied over to the build directory. Defaults to `{site_directory}/static`. (default: None)

  • -bd BUILD_DIRECTORY, --build_directory BUILD_DIRECTORY - the directory to build the site in. Defaults to `{site_directory}/build`. (default: None)

Aggregation

By default, if any folders in the `content_directory` don’t have a defined `index` page, will have an automated one created, which will be an aggregate of all the posts inside of it (local aggregation). Additionally, if there’s no top-level `index` page defined, it will be an aggregate of all the posts in the website (global aggregation). The following options control how both those aggregators work.

  • -law LOCALLY_AGGREGATE_WHITELIST, --locally_aggregate_whitelist LOCALLY_AGGREGATE_WHITELIST - specifies the folder paths or names to aggregate. If nothing is provided it defaults to aggregating everything.

  • -lab LOCALLY_AGGREGATE_BLACKLIST, --locally_aggregate_blacklist LOCALLY_AGGREGATE_BLACKLIST - specifies the folder paths or names to NOT aggregate. If nothing is provided it defaults to nothing. NOTE: only the whitelist or the blacklist being set is supported, but not both.

  • -gaw GLOBALLY_AGGREGATE_WHITELIST, --globally_aggregate_whitelist GLOBALLY_AGGREGATE_WHITELIST - specifies the folder paths or names to aggregate into the home page. If nothing is provided it defaults to aggregating everything.

  • -gab GLOBALLY_AGGREGATE_BLACKLIST, --globally_aggregate_blacklist GLOBALLY_AGGREGATE_BLACKLIST - specifies the folder paths or names to NOT aggregate into the home page. If nothing is provided it defaults to nothing. NOTE: only the whitelist or the blacklist being set is supported, but not both.

Category pages

Building an aggregation of posts per category defined in their front matter.

  • -bc, --build_categories - whether or not to build category pages, based on the 'category' key of their 'front_matter'. Defaults to False. (default: False)

  • -ac, --do_not_allow_uncategorized - whether to error if there are uncategorized posts. Defaults to False (not erroring out). (default: False)

  • -cpn CATEGORIES_PAGE_NAME, --categories_page_name CATEGORIES_PAGE_NAME - the name of the categories page, which will have a list of all categories and their posts. If left empty, no such page will be created. Default is ‘’. (default: )

  • -gc, --group_categories - whether to group category pages under a folder. The folder name will be 'categories' if nothing is specified in categories_page_name (default: False)

  • -un UNCATEGORIZED_NAME, --uncategorized_name UNCATEGORIZED_NAME - the name for the page containing all posts which don``’t have a category key in their front matter. Default is ‘``Uncategorized’. (default: Uncategorized)

Archive pages

Building an aggregation of posts based on the date they were posted

  • -abm, --build_archive_by_month - whether to build an archive by month. Defaults to False. (default: False)

  • -aby, --build_archive_by_year - whether to build an archive by year. Defaults to False. (default: False)

  • -apn ARCHIVE_PAGE_NAME, --archive_page_name ARCHIVE_PAGE_NAME - the name of the archive page, which will have a list of all posts by their month and/or year of publishing. If empty, no such page will be created. Default is ‘’. (default: )

  • -ga, --group_archive - whether to group archive pages under a folder. The folder name will be 'archive' if nothing is specified in archive_page_name (default: False)

  • -damp, --display_archive_by_month_in_list_page - whether to display the monthly archive in the archive list page. Default is False. (default: False)

  • -dayp, --display_archive_by_year_in_list_page - whether to display the yearly archive in the archive list page. Default is False. (default: False)

  • -amf ARCHIVE_MONTH_FORMAT, --archive_month_format ARCHIVE_MONTH_FORMAT - the datetime fomatting to be used for the archive by month. Default is '%%B, %%Y', e.g. 'April, 2022'. (default: %B, %Y)

  • -ayf ARCHIVE_YEAR_FORMAT, --archive_year_format ARCHIVE_YEAR_FORMAT - the datetime fomatting to be used for the archive by year. Default is '%%Y', e.g. '2022'. (default: %Y)

Theme options

Theme may require different options, such as ‘dark’ or ‘light mode, including a sidebar or not, social media profile links, etc. Since they may be anything the theme developer is responsible for outlining what arguments may be set.

In order for them to be parsed correctly the following 3 rules must be considered:

  1. flags with no values start with -th_ or --theme_option_, e.g. -th_sidebar.

  2. we support key-value pairs with up to three values per key. Simple theme args must start with -th1_ or --theme1_option, e.g. -th1_dark_mode or --theme_option1_dark_mode. Arguments that accept tuples with 2 values should be prefixed with -th2_ or --theme_option2 and the same goes for arguments that accept tuples with 3 values.

  3. Setting the same argument twice using -th1_{arg} will overwrite the previous value. so if a list of values is required use -thl1_{arg},``-thl2_{arg}``,etc.

NOTE: we only support up to 3 values per key.

Here are the accepted arguments for the default theme:

  • th_breadcrumbs - whether to display breadcrumbs or not. Default is off.

  • th_sidebar - whether to build a sidebar or not. Default is off.

  • th_sidebar_in_home_only - whether to build the sidebar only on the home page. Default is off.

  • th_sidebar_image_in_home_only - whether to have the sidebar image only on the home page. Default is off.

  • th_sidebar_social_in_home_only - whether to have the sidebar social icons only on the home page. Default is off.

  • th_sidebar_description_in_home_only - whether to have the sidebar description only on the home page. Default is off.

  • th1_sidebar_image - an image for the top of the sidebar, e.g.

    -th1_sidebar_image "/img/sidebar.png"

  • th1_sidebar_image_alt - the alt text for the sidebar image

  • th1_sidebar_description - a bit of descriptive text in the sidebar

  • thl{2/3}_social_links - a list of (name, url, optional img) tuples, e.g.

    -thl3_social_links github "https://github.com/lamya" "/img/github.svg" -thl2_social_links twitter "https://twitter.com/lamya",

    which will produce an icon for github and the text ‘twitter’ for the twitter link.

  • thl{2/3}_links - a list of (name, url, optional nice name) tuples, e.g.

    -thl3_links "my knitting blog" "https://knittingforfunandprofit.com" knittingforfunandprofit.com -thl2_links "favourite knitting pattern" "https://knittingforfunandprofit.com/the-three-crocheters"

  • th_sidebar_archive_nav - whether to include an archive navigation in the sidebar

  • th_display_archive_by_month_in_sidebar - whether to include monthly links from the archive in the sidebar. Default is True.

  • th_display_archive_by_year_in_sidebar - whether to include yearly links from the archive in the sidebar. Default is False.

  • th1_copyright_year - to be displayed in the footer

  • thl1_extra_css - a number of stylesheets to load after the theme’s ones

  • thl1_extra_js - a number of javascript files to load after the theme’s ones