docs: add THEME-HOWTO.md and update README

- Added comprehensive theme creation guide - Updated README with link to theme documentation - Improved documentation structure
2025-05-18 19:13:01 +02:00
parent 8bfb51550a
commit 8ce4580ebe
2 changed files with 195 additions and 1 deletions
--- a/README.md
+++ b/README.md
@ -11,7 +11,7 @@ Quick Site Generator 2 is a powerful static website generator written in Zsh, in
 - 🚀 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
+- 🎨 Themeable with custom templates (see [THEME-HOWTO.md](THEME-HOWTO.md))
 - 📱 Responsive design ready
 - 🔍 SEO friendly
 - 🔄 Automatic rebuild on file changes
--- a/THEME-HOWTO.md
+++ b/THEME-HOWTO.md
@ -0,0 +1,194 @@
+# Creating Themes for Quick Site Generator 2
+
+This guide explains how to create and customize themes for Quick Site Generator 2 (qsgen2). The theming system is designed to be simple yet flexible, allowing you to create beautiful, responsive websites with minimal effort.
+
+## Table of Contents
+
+1. [Theme Structure](#theme-structure)
+2. [Template Files](#template-files)
+   - [pages.tpl](#pagestpl)
+   - [blogs.tpl](#blogstpl)
+   - [blog_index.tpl](#blog_indextpl)
+   - [blog_list.tpl](#blog_listtpl)
+3. [Template Variables](#template-variables)
+4. [Creating a New Theme](#creating-a-new-theme)
+5. [Best Practices](#best-practices)
+6. [Example Theme](#example-theme)
+
+## Theme Structure
+
+A qsgen2 theme consists of the following files:
+
+```
+theme-name/
+├── pages.tpl         # Template for regular pages
+├── blogs.tpl         # Template for blog posts
+├── blog_index.tpl    # Template for blog index page
+├── blog_list.tpl     # Template for blog post listings
+└── css/              # Stylesheets and assets
+    ├── style.css     # Main stylesheet
+    └── webfont.js    # Web font loader (optional)
+```
+
+## Template Files
+
+### pages.tpl
+
+This template is used for regular static pages. It should include the basic HTML structure, head section, and placeholders for dynamic content.
+
+Key placeholders:
+- `#sitename` - Site name from configuration
+- `#pagetitle` - Title of the current page
+- `#tagline` - Site tagline from configuration
+- `BODY` - Main content area
+
+### blogs.tpl
+
+This template is used for individual blog posts. It includes placeholders for blog-specific content.
+
+Key placeholders:
+- `BLOGTITLE` - Title of the blog post
+- `CALADAY` - Day of the month (numeric)
+- `CALNDAY` - Day of the week (name)
+- `CALMONTH` - Month name
+- `CALYEAR` - Year
+- `INGRESS` - Blog post excerpt/intro
+- `BODY` - Main blog post content
+
+### blog_index.tpl
+
+This template is used for the blog index/archive page that lists all blog posts.
+
+Key placeholders:
+- `#sitename` - Site name from configuration
+- `#tagline` - Site tagline from configuration
+- `BODY` - Contains the list of blog posts (generated from blog_list.tpl)
+
+### blog_list.tpl
+
+This template defines how individual blog posts are displayed in the blog index.
+
+Key placeholders:
+- `BLOGURL` - URL of the blog post
+- `BLOGTITLE` - Title of the blog post
+- `INGRESS` - Blog post excerpt/intro
+- `BLOGDATE` - Formatted date of the blog post
+
+## Template Variables
+
+These variables can be used in any template:
+
+- `#sitename` - Site name from configuration
+- `#tagline` - Site tagline from configuration
+- `#pagetitle` - Current page title
+- `#siteurl` - Base URL of the site
+- `#currentyear` - Current year (for copyright notices)
+
+## Creating a New Theme
+
+1. **Create a new directory** in the `themes` folder with your theme name.
+
+2. **Copy the template files** from the `minimal` theme as a starting point:
+   ```bash
+   cp -r themes/minimal/* themes/your-theme-name/
+   ```
+
+3. **Customize the templates**:
+   - Edit the HTML structure in the `.tpl` files
+   - Update the CSS in the `css` directory
+   - Replace placeholder images with your own
+
+4. **Test your theme** by setting it in your `site.conf`:
+   ```ini
+   theme = "your-theme-name"
+   ```
+
+5. **Build your site** to see the changes:
+   ```bash
+   ./qsgen2 build
+   ```
+
+## Best Practices
+
+1. **Responsive Design**
+   - Use responsive CSS frameworks or media queries
+   - Test on different screen sizes
+
+2. **Performance**
+   - Minify CSS and JavaScript
+   - Optimize images
+   - Use web fonts sparingly
+
+3. **Accessibility**
+   - Use semantic HTML5 elements
+   - Include alt text for images
+   - Ensure sufficient color contrast
+
+4. **Browser Compatibility**
+   - Test in multiple browsers
+   - Use vendor prefixes for CSS properties
+
+## Example Theme
+
+Here's a minimal example of a theme structure:
+
+```
+my-theme/
+├── pages.tpl
+├── blogs.tpl
+├── blog_index.tpl
+├── blog_list.tpl
+└── css/
+    └── style.css
+```
+
+### pages.tpl (example)
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>#sitename - #pagetitle</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link href="/css/style.css" rel="stylesheet">
+</head>
+<body>
+    <header>
+        <h1>#sitename</h1>
+        <p>#tagline</p>
+        <nav>
+            <a href="/">Home</a>
+            <a href="/blog/">Blog</a>
+        </nav>
+    </header>
+    
+    <main>
+        BODY
+    </main>
+    
+    <footer>
+        <p>&copy; #currentyear #sitename. All rights reserved.</p>
+    </footer>
+</body>
+</html>
+```
+
+### blog_list.tpl (example)
+```html
+<article class="blog-post">
+    <h2><a href="BLOGURL">BLOGTITLE</a></h2>
+    <div class="post-meta">
+        <time datetime="BLOGDATE">BLOGDATE</time>
+    </div>
+    <div class="post-excerpt">
+        INGRESS
+        <a href="BLOGURL" class="read-more">Read more →</a>
+    </div>
+</article>
+```
+
+## Conclusion
+
+Creating themes for qsgen2 is straightforward once you understand the template system. Start with the minimal theme as a base, and customize it to match your design. Remember to test your theme thoroughly and follow web development best practices for the best results.
+
+For more advanced theming options, refer to the official documentation or check out the source code of existing themes.