Stig-Ørjan Smelror
c470ac40c0
- 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.
46 lines
1.7 KiB
Markdown
46 lines
1.7 KiB
Markdown
# 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:
|
|
```bash
|
|
./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.).
|
|
|