Configuration
LSSG uses a modular architecture where different modules handle specific rendering and processing tasks. Configure them via TOML comments at the start of markdown files.
Resource Discovery
LSSG automatically discovers and copies resources (CSS, JavaScript, images, fonts, etc.) to your build output directory.
How It Works
- Automatic Detection: LSSG scans your markdown files and HTML for resource references
- Recursive Copy: Resources are copied from your source directory to the corresponding location in the build directory
- Relative Path Preservation: The directory structure is maintained, ensuring links remain functional
- Supported Resources: CSS, JavaScript, images (JPG, PNG, SVG, GIF, WebP), fonts, videos, and other static assets
Resource Locations
Resources can be:
- Referenced directly in markdown:
 - Imported in CSS files:
@import url('fonts/custom.css'); - Linked in HTML:
<script src="./script.js"></script> - Used as custom elements:
<carousel></carousel>
All discovered resources are automatically included in the build output without manual configuration.
Default Module
Core rendering for markdown and HTML structure. Required for all pages.
Page Options
| Option | Type | Default | Description |
|---|---|---|---|
root | Boolean | false | Disable parent inheritance |
title | String | First H1 | Page title for browser tab and SEO |
language | String | "en" | HTML language attribute |
section_links | Boolean | true | Show link icons on h2 headers on hover |
meta | Object | {} | Custom meta tags (key-value pairs) |
head | Array[String] | [] | Custom HTML elements for <head> |
Navigation Options
| Option | Type | Default | Description |
|---|---|---|---|
nav.kind | String | "breadcrumbs" | Navigation type: "breadcrumbs", "sidemenu", or "none" |
nav.include_root | Boolean | false | Include root page in side menu (only applies to sidemenu) |
nav.name_map | Object | {} | Custom display names for pages (key: page name, value: display name) |
Navigation Types:
breadcrumbs: Shows path from root to current page (e.g.,/parent/child/current)sidemenu: Displays hierarchical page structure with nested pages (max depth: 3)none: Disables navigation completely
Footer Options
| Option | Type | Default | Description |
|---|---|---|---|
footer.items | Array[String] | [] | Footer HTML elements or text |
footer.custom | String | - | Custom footer HTML (replaces default) |
footer.watermark | Boolean | true | Show "Generated by Lssg" |
Inheritance: Child pages inherit parent options. Child values override parent values. Use root = true to disable inheritance.
Blog Module
Blogging capabilities with posts, indexing, and RSS feeds.
Blog Root Options ([blog.root])
For the main blog index page:
| Option | Type | Default | Description |
|---|---|---|---|
use_fs_dates | Boolean | false | Use filesystem dates instead of manual dates |
rss.enabled | Boolean | false | Enable RSS feed generation |
rss.path | String | "feed.xml" | RSS feed output filename |
rss.title | String | "Feed" | RSS feed title |
rss.description | String | "My feed" | RSS feed description |
rss.host | String | - | Base URL (required for RSS) |
rss.language | String | - | RSS language code |
rss.last_build_date_enabled | Boolean | true | Use most recent post date as build date |
Blog Post Options ([blog.post])
For individual blog posts:
| Option | Type | Default | Description |
|---|---|---|---|
render | Boolean | true | Enable blog-specific rendering |
created_on | String | - | Publication date (ISO or YYYY-MM-DD) |
modified_on | String | - | Last modification date (ISO or YYYY-MM-DD) |
tags | Array[String] | [] | Post tags/categories |
summary | String | - | Post summary/excerpt |
Media Module
Automatic optimization for images and videos.
Image Options ([media])
| Option | Type | Default | Description |
|---|---|---|---|
optimize_images | Boolean | true | Enable image optimization |
image_quality | Integer (1-100) | 85 | JPEG/PNG compression quality |
convert_to_webp | Boolean | true | Convert images to WebP format |
webp_quality | Integer (1-100) | 95 | WebP quality (≥95 is lossless) |
max_width | Integer | 1920 | Maximum image width in pixels |
max_height | Integer | 1080 | Maximum image height in pixels |
resize_threshold_bytes | Integer | 1000000 | Min file size (bytes) to trigger resize |
Video Options ([media])
| Option | Type | Default | Description |
|---|---|---|---|
optimize_videos | Boolean | true | Enable video optimization |
use_ffmpeg | Boolean | true | Use FFmpeg (must be installed) |
video_crf | Integer (0-51) | 25 | Video quality (lower = better, 18-28 recommended) |
External Module
Import complete HTML sites from remote ZIP archives.
| Option | Type | Default | Description |
|---|---|---|---|
href | String (URL) | - | URL to ZIP file containing HTML site |
Downloads and integrates ZIP contents: HTML pages, CSS stylesheets, and resources while preserving folder structure.
Configuration Example
<!--
title = "My Blog Post"
language = "en"
section_links = true
[meta]
description = "A great post about Rust"
author = "Your Name"
[nav]
kind = "sidemenu"
include_root = true
name_map = { home = "Home Page", blog = "Blog Posts" }
[blog.post]
created_on = "2025-01-03"
tags = ["rust", "tutorial"]
summary = "Learn about static site generators"
[media]
optimize_images = true
image_quality = 85
convert_to_webp = true
[footer]
items = ['<a href="/about">About</a>', '<a href="/contact">Contact</a>']
watermark = true
-->
# Page Content