all2md.utils.static_site

Static site generator utilities for Hugo, Jekyll, MkDocs, Zola, and Eleventy.

This module provides utilities for converting documents to static site generator formats (Hugo, Jekyll, MkDocs, Zola, Eleventy). It handles: - Frontmatter generation from document metadata - Site structure scaffolding - Asset management for static sites

Functions

  • generate_frontmatter: Convert Document metadata to frontmatter

  • create_site_scaffold: Create static site directory structure

  • process_document_for_static_site: Convert document with frontmatter and assets

class all2md.utils.static_site.StaticSiteGenerator

Bases: str, Enum

Supported static site generators.

HUGO = 'hugo'
JEKYLL = 'jekyll'
MKDOCS = 'mkdocs'
ZOLA = 'zola'
ELEVENTY = 'eleventy'
__new__(value)
class all2md.utils.static_site.FrontmatterFormat

Bases: str, Enum

Frontmatter serialization formats.

YAML = 'yaml'
TOML = 'toml'
__new__(value)
class all2md.utils.static_site.FrontmatterGenerator

Bases: object

Generate frontmatter for static site generators.

This class handles conversion of Document metadata to generator-specific frontmatter in YAML or TOML format.

Parameters:

Examples

Generate Hugo frontmatter:

>>> generator = FrontmatterGenerator(StaticSiteGenerator.HUGO)
>>> metadata = {"title": "My Post", "date": "2025-01-22", "tags": ["python", "coding"]}
>>> frontmatter = generator.generate(metadata)

Initialize frontmatter generator.

Parameters:

  • generator (StaticSiteGenerator) – Target static site generator

  • format (FrontmatterFormat, optional) – Frontmatter format. If None, uses TOML for Hugo and Zola, and YAML for Jekyll, MkDocs, and Eleventy.

__init__(generator: StaticSiteGenerator, format: FrontmatterFormat | None = None)

Initialize frontmatter generator.

Parameters:

  • generator (StaticSiteGenerator) – Target static site generator

  • format (FrontmatterFormat, optional) – Frontmatter format. If None, uses TOML for Hugo and Zola, and YAML for Jekyll, MkDocs, and Eleventy.

generate(metadata: Dict[str, Any]) → str

Generate frontmatter from document metadata.

Parameters:

metadata (dict) – Document metadata dictionary

Returns:

Formatted frontmatter with delimiters

Return type:

str

Examples

>>> generator = FrontmatterGenerator(StaticSiteGenerator.HUGO)
>>> metadata = {"title": "Test", "date": "2025-01-22"}
>>> print(generator.generate(metadata))
+++
title = "Test"
date = 2025-01-22
+++
class all2md.utils.static_site.SiteScaffolder

Bases: object

Create directory structure for static site generators.

This class handles creation of the basic directory structure and configuration files for Hugo, Jekyll, MkDocs, Zola, and Eleventy sites.

Parameters:

generator (StaticSiteGenerator) – Target static site generator

Initialize site scaffolder.

Parameters:

generator (StaticSiteGenerator) – Target generator

__init__(generator: StaticSiteGenerator)

Initialize site scaffolder.

Parameters:

generator (StaticSiteGenerator) – Target generator

scaffold(output_dir: Path) → None

Create site directory structure.

Parameters:

output_dir (Path) – Root directory for the site

class all2md.utils.static_site.ImageCollector

Bases: object

Utility to collect all Image nodes from a document AST.

This class walks the document AST and collects all Image nodes.

Variables:

images (list) – List of Image nodes found in the document

Initialize the image collector.

__init__() → None

Initialize the image collector.

images: List[Image]
collect(node: Node) → None

Collect images from a node and its children.

Parameters:

node (Node) – Node to collect images from

all2md.utils.static_site.copy_document_assets(doc: Document, output_dir: Path, generator: StaticSiteGenerator, source_file: Path | None = None) → Tuple[Document, List[str]]

Copy document assets to static site directory and update references.

This function walks the document AST, finds all images with file paths, copies them to the appropriate static directory, and updates the image URLs in the AST to reference the new locations.

Parameters:

  • doc (Document) – Document AST with image nodes

  • output_dir (Path) – Root output directory for the static site

  • generator (StaticSiteGenerator) – Target static site generator (Hugo, Jekyll, MkDocs, Zola, or Eleventy)

  • source_file (Path, optional) – Source file path (used to resolve relative image paths)

Returns:

Tuple of (modified_document, list_of_copied_assets) The document is modified in-place, but returned for convenience.

Return type:

tuple[Document, list of str]

Examples

Copy assets from a document:

>>> from all2md import to_ast
>>> doc = to_ast("document.pdf")
>>> modified_doc, assets = copy_document_assets(
...     doc, Path("./my-site"), StaticSiteGenerator.HUGO
... )
>>> print(f"Copied {len(assets)} assets")
all2md.utils.static_site.generate_output_filename(source_file: Path, metadata: Dict[str, Any], generator: StaticSiteGenerator, index: int = 1) → str

Generate output filename for a document.

Creates a filename based on the document title (if available), source filename, or index. For Jekyll posts, prepends the date in YYYY-MM-DD format.

Parameters:

  • source_file (Path) – Source document path

  • metadata (dict) – Document metadata (may contain title, date)

  • generator (StaticSiteGenerator) – Target generator

  • index (int, default 1) – Numeric index for fallback naming

Returns:

Generated output filename (without extension)

Return type:

str

Examples

Generate Hugo filename:

>>> from pathlib import Path
>>> metadata = {"title": "My Great Post"}
>>> generate_output_filename(
...     Path("doc.pdf"), metadata, StaticSiteGenerator.HUGO
... )
'my-great-post'

Generate Jekyll filename with date:

>>> metadata = {"title": "My Post", "date": "2025-01-22"}
>>> generate_output_filename(
...     Path("doc.pdf"), metadata, StaticSiteGenerator.JEKYLL
... )
'2025-01-22-my-post'