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
parent c14e943f2b
commit c470ac40c0
34 changed files with 5058 additions and 82 deletions
--- a/README.md
+++ b/README.md
@ -1,70 +1,45 @@
-<img src="qsg2-square.png" width="150" align="left">
+# qsgen3 - A Minimal Markdown Static Site Generator

-# Quick Site Generator 2
+This is a refactored version of qsgen, focusing on simplicity, Markdown with YAML frontmatter, and a Zsh-based build process.

-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+## Project Goals

-Quick Site Generator 2 is a powerful static website generator written in Zsh, inspired by [Nikola](https://github.com/getnikola/nikola). It's designed to be fast, flexible, and easy to use, with support for both custom QSTags and standard Markdown syntax.
+- 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.

-## Features
+## Structure

- 🚀 Blazing fast static site generation
- 📝 Supports both QSTags and Markdown content
- 🌍 Multi-language support (en_US, en_UK, es_ES, fr_FR, nb_NO)
- 🎨 Themeable with custom templates (see [THEME-HOWTO.md](THEME-HOWTO.md))
- 📱 Responsive design ready
- 🔍 SEO friendly
- 🔄 Automatic rebuild on file changes
+- `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).

-## Quick Start
+## Usage

-1. **Installation**
+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
-   git clone https://github.com/kekePower/qsgen2.git
-   cd qsgen2
-   chmod +x qsgen2
+   ./bin/qsgen3
   ```
+5. Your static site will be generated in the `output/` directory.

-2. **Create a new site**
-   ```bash
-   ./qsgen2 new my-site
-   cd my-site
-   ```
+## Dependencies

-3. **Build and serve**
-   ```bash
-   ./qsgen2 build
-   ./qsgen2 serve
-   ```
+- 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.).

-For detailed documentation, see the [HOWTO.md](HOWTO.md) guide.
-
-## Recent Changes
-
- Added Norwegian (nb_NO) language support
- Improved internationalization (i18n) system
- Cleaned up temporary and backup files
- Updated documentation
- Added comprehensive HOWTO guide
-
-## Requirements
-
- Zsh 5.8 or later
- Pandoc (for Markdown support)
- Basic Unix tools (sed, grep, etc.)
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Contributing
-
-Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) before submitting pull requests.
-
-## Support
-
-For support, please [open an issue](https://github.com/kekePower/qsgen2/issues) on GitHub.
-
---
-
-*Created with ❤️ by kekePower*