kekePower/qsgen3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
qsgen3/README.md
Stig-Ørjan Smelror c470ac40c0 feat: Implement robust theme system and document architecture 
- Implement flexible theme switching via site.conf (site_theme, site_theme_css_file).
- Ensure correct copying of theme static assets, with theme assets overriding root assets.
- Resolve CSS linking issues by checking file existence after static copy and using correct paths for Pandoc.
- Refactor path construction to prevent duplication when using absolute/relative output paths.
- Create comprehensive how-it-works.md detailing system architecture, theme creation, and overall workflow.
- Clarify design philosophy: qsgen3 remains design-agnostic, only linking main theme CSS automatically.
2025-05-31 00:00:21 +02:00

1.7 KiB
Raw Blame History

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

  1. Configure your site in site.conf.
  2. Add Markdown content to the content/ directory.
  3. Customize templates in layouts/.
  4. Run the build script: 
    ./bin/qsgen3
  5. 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.).