build.py documentation

August 24, 2025

Static Site Generator Documentation

(generated by coding assistants)

This document outlines how to use the build.py script to generate your static website. It covers the directory structure, command-line arguments, and the variables available for use in your HTML templates.

Directory Structure

Your project should follow a specific structure for the build script to work correctly. The root of your project contains configuration files and the main templates, while the src directory holds all your content.

/my-blog-project/
├── build.py                # The build script
├── sections.ini            # Configuration for site sections
├── header.md               # Main header content, used in all pages
├── footer.md               # Main footer content, used in all pages
├── main_index.html         # Template for the site's homepage
├── keyword-page-template.html  # Template for individual keyword pages
├── keyword-index-template.html # Template for the main keywords list page
├── robots.txt              # Tells search engines how to crawl your site
└── src/
└── blog/               # An example section source directory
├── posts/
│   ├── first-post.md
│   └── another-post.md
├── images/
│   └── post-image.jpg
├── post-template.html
└── index-template.html

Note: The robots.txt file should be in the root of your project directory. The build script will copy it to the root of the final dist directory during the build process.

How to Run the Script

You execute the build script from your terminal. It accepts several command-line arguments to control its behavior.

Command-Line Arguments

--base-url [URL] (Required): Sets the full root URL for your website (e.g., https://www.yourdomain.com). This is essential for generating a correct sitemap.xml.
--directory [PATH] (Optional): Specifies the project’s root directory. If omitted, it defaults to the directory where the script is located.
--debug [0 or 1] (Optional): Enables or disables debug logging. Set to 1 to see detailed output of the build process. Defaults to 0.

Example Usage

python build.py --base-url [https://www.mycoolsite.com](https://www.mycoolsite.com) --debug 1

Template Variables

You can use placeholder variables inside your .html template files. The script will replace these with the appropriate content during the build process.

Variable	Available In	Description
{links_header} main_index.html, post-template.html, index-template.html, keyword-page-template.html, keyword-index-template.html	The HTML content generated from header.md.
{footer}	main_index.html, post-template.html, index-template.html, keyword-page-template.html, keyword-index-template.html	The HTML content generated from footer.md.
{title}	post-template.html	The title of an individual post, from its front matter.
{date}	post-template.html	The formatted date of an individual post.
{content}	post-template.html	The main body of an individual post, converted from Markdown to HTML.
{posts}	index-template.html	A list of HTML snippets for all the posts in a section.
{keyword}	keyword-page-template.html	The name of the specific keyword for that page.
{post_links}	keyword-page-template.html	An HTML list of all posts tagged with that specific keyword.
{keyword_list}	keyword-index-template.html	An HTML list of all keywords found across the site.
{current_year}	footer.md	The current four-digit year. Useful for copyright notices.
{dynamic_nav_links}	header.md	Placeholder for the navigation links generated from sections.ini.

Front Matter Fields

The script recognizes the following fields in the YAML front matter of your .md post files:

title: (Required) The title of the post.

date: (Required) The publication date in YYYY-MM-DD format. Posts with a future date will not be published until that date is reached.

published: (Required) Set to true for the post to be included in the build.

url_slug: (Optional) A custom, clean URL slug (e.g., my-custom-url). If omitted, a slug is generated from the title.

last_modified_on: (Optional) The date the post was last updated, in YYYY-MM-DD format. Used for the sitemap.xml.

keywords: (Optional) A comma-separated list of keywords for the post.

Reply via email