Implements several improvements to the qsgen3 site generator: - **Filename Sanitization**: Introduces robust sanitization for output HTML filenames, converting to lowercase, replacing special characters with hyphens, and ensuring clean names. - **Blog Post URL Structure**: Blog posts from content/posts/ are now generated with a blog/YYYY/MM/DD/ URL structure if a valid date is present in frontmatter. Defaults to blog/filename.html if no valid date. - **Improved Title Fallback**: Uses the original filename (before sanitization) as a fallback title if not specified in frontmatter. - **Enhanced Pandoc Error Handling**: Better logging for Pandoc execution and explicit check of its exit code, allowing the script to continue on single file errors. - **Sitemap Integration**: Adds successfully generated pages to sitemap URL list. - **Non-fatal Sitemap Generation**: Sitemap generation failures are now logged as warnings and do not halt the script. Also, unignores the /scripts/ directory in .gitignore to include migration scripts in the repository.
qsgen3 - A Minimal Markdown Static Site Generator
This is a refactored version of qsgen, focusing on simplicity, Markdown with YAML frontmatter, and a Zsh-based build process.
Project Goals
- Remove QSTags and switch to Markdown + YAML frontmatter.
- Simplify codebase by removing multilingual and theme support.
- Refactor templating with uniform variables (e.g.,
{{ content }}
,{{ title }}
). - Ensure future-proofing by avoiding complex dependencies (like AWK for long string manipulation) for core tasks.
- Provide a solid initial setup that works out of the box with a sample post, index, and layout.
- Include a converter script in
scripts/convert-qstags-to-md.sh
for legacy content.
Structure
bin/qsgen3
: The main Zsh build script.site.conf
: Site configuration (INI format).content/
: Source Markdown files.content/posts/
: Blog posts.content/pages/
: Static pages.
layouts/
: HTML templates.layouts/base.html
: Base template for all pages.layouts/post.html
: Template for individual blog posts.layouts/page.html
: Template for static pages.
static/
: Static assets (CSS, images, etc.) copied as-is to the output.output/
: The generated website.scripts/
: Utility scripts (e.g., content converter).
Usage
- Configure your site in
site.conf
. - Add Markdown content to the
content/
directory. - Customize templates in
layouts/
. - Run the build script:
./bin/qsgen3
- Your static site will be generated in the
output/
directory.
Dependencies
- Zsh
- A Markdown processor (e.g., Pandoc, CommonMark, or a Zsh-native solution if feasible for basic needs).
- Standard Unix utilities (grep, sed, find, etc.).
Languages
Shell
72.2%
Python
14.2%
HTML
9%
CSS
4.6%