From 8ce4580ebee63f7f67e4e47b2b7bf0d6a21c294f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stig-=C3=98rjan=20Smelror?= Date: Sun, 18 May 2025 19:13:01 +0200 Subject: [PATCH] docs: add THEME-HOWTO.md and update README - Added comprehensive theme creation guide - Updated README with link to theme documentation - Improved documentation structure --- README.md | 2 +- THEME-HOWTO.md | 194 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 195 insertions(+), 1 deletion(-) create mode 100644 THEME-HOWTO.md diff --git a/README.md b/README.md index 8c8020a..cddb738 100644 --- 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 diff --git a/THEME-HOWTO.md b/THEME-HOWTO.md new file mode 100644 index 0000000..02050c0 --- /dev/null +++ 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 + + + + + #sitename - #pagetitle + + + + +
+

#sitename

+

#tagline

+ +
+ +
+ BODY +
+ + + + +``` + +### blog_list.tpl (example) +```html +
+

BLOGTITLE

+
+ +
+
+ INGRESS + Read more → +
+
+``` + +## 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.