oerforge.make
Hugo-style Markdown to HTML Static Site Generator (Python)
Overview
provides functions for building static HTML sites from Markdown using Jinja2 templates, asset management, navigation, and download button generation. It is inspired by Hugo and designed for clarity, maintainability, and extensibility.
Functions
copy_static_assets_to_build
Copy static assets (CSS, JS, images) from to . Overwrites files each time it is called.
get_available_downloads_for_page
Scan the published output directory for a page and return a list of available download formats.
Parameters
(str): Relative path to the HTML file (e.g., 'about/index.html').
(str, optional): Directory containing downloadable files.
Returns
: List of available downloads with label, filename, href, theme, and aria_label.
build_download_buttons_context
Build the download buttons context for a page.
Parameters
(str): Relative path to the HTML file.
(str, optional): Directory containing downloadable files.
Returns
: List of button dictionaries for the template.
slugify
Convert a title to a slug suitable for folder names.
Parameters
(str): Page or section title.
Returns
: Slugified string.
load_yaml_config
Load and parse the YAML config file.
Parameters
(str): Path to the YAML config file.
Returns
: Parsed configuration data.
ensure_output_dir
Ensure the output directory for the HTML file exists, mirroring structure.
Parameters
(str): Path to the Markdown file.
setup_template_env
Set up the Jinja2 template environment for rendering pages.
Returns
: Configured Jinja2 environment.
render_page
Render a page using Hugo-style templates.
Parameters
(dict): Context dictionary for the template.
(str): Name of the template file.
Returns
: Rendered HTML string.
generate_nav_menu
Generate top-level navigation menu items from the content table.
Parameters
(dict): Context dictionary, typically with .
Returns
: List of menu item dictionaries.
get_header_partial
Render the header partial using Jinja2.
Parameters
(dict): Context dictionary for the template.
Returns
: Rendered header HTML.
get_footer_partial
Render the footer partial using Jinja2.
Parameters
(dict): Context dictionary for the template.
Returns
: Rendered footer HTML.
convert_markdown_to_html
Convert Markdown to HTML using markdown-it-py, rewriting local image paths and adding accessibility roles.
Parameters
(str): Path to the Markdown file.
Returns
: Rendered HTML string.
convert_markdown_to_html_text
Convert Markdown text to HTML using markdown-it-py, rewriting local image paths and adding accessibility roles.
Parameters
(str): Markdown text.
Returns
: Rendered HTML string.
get_asset_path
Compute the relative asset path for CSS, JS, or images based on page depth.
Parameters
(str): Asset type ('css', 'js', 'images').
(str): Asset filename.
(str): Relative path to the page.
Returns
: Relative asset path.
add_asset_paths
Add asset paths (CSS, JS, logo) to the context for template rendering.
Parameters
(dict): Context dictionary.
(str): Relative path to the page.
Returns
: Updated context dictionary.
get_top_level_sections
Get all top-level sections from the database for section index generation.
Parameters
(str, optional): Path to the SQLite database.
Returns
: List of (section_title, output_dir) tuples.
build_section_indexes
Generate index.html files for all top-level sections using the section template.
build_all_markdown_files
Build all Markdown files using Hugo-style rendering, using the first # header as the title.
create_section_index_html
Generate section using the template.
Parameters
(str): Title of the section.
(str): Output directory for the section index.
(dict): Context dictionary for the template.
Usage Example
Requirements
Python 3.7+
Jinja2
markdown-it-py
mdit-py-plugins
PyYAML
SQLite3
See Also
Jinja2 Documentation
markdown-it-py Documentation
License
See in the project root.