kekePower/qsgen2
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
qsgen2/THEME-HOWTO.md
Stig-Ørjan Smelror 8ce4580ebe 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

5.2 KiB
Raw Blame History

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
  2. Template Files
  3. Template Variables
  4. Creating a New Theme
  5. Best Practices
  6. 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:

    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:

    theme = "your-theme-name"

  5. Build your site to see the changes:

    ./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)

<!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)

<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.