kekePower/qsgen3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive theme documentation and improve migration script

Browse Source 
- Add THEMES-HOWTO.md: Complete guide for creating and customizing themes
- Remove theme sections from how-it-works.md to avoid duplication
- Update migration script to place all blog posts in single directory
- Streamline documentation structure for better organization
This commit is contained in:
Stig-Ørjan Smelror
2025-05-31 03:00:50 +02:00
parent f72fe18873
commit 81ffa53d70
4 changed files with 971 additions and 765 deletions
Download Patch File Download Diff File Expand all files Collapse all files

610
how-it-works.md
View File

@ -5,16 +5,14 @@
1. [Philosophy and Design Principles](#philosophy-and-design-principles)
2. [Project Structure](#project-structure)
3. [Configuration System](#configuration-system)
4. [Theme System](#theme-system)
5. [Creating New Themes](#creating-new-themes)
6. [Content Processing Pipeline](#content-processing-pipeline)
7. [Static File Handling](#static-file-handling)
8. [Template System](#template-system)
9. [Output Generation](#output-generation)
10. [Command Line Interface](#command-line-interface)
11. [Dependencies and Requirements](#dependencies-and-requirements)
12. [Detailed Workflow](#detailed-workflow)
13. [Troubleshooting and Debugging](#troubleshooting-and-debugging)
4. [Content Processing Pipeline](#content-processing-pipeline)
5. [Static File Handling](#static-file-handling)
6. [Template System](#template-system)
7. [Output Generation](#output-generation)
8. [Command Line Interface](#command-line-interface)
9. [Dependencies and Requirements](#dependencies-and-requirements)
10. [Detailed Workflow](#detailed-workflow)
11. [Troubleshooting and Debugging](#troubleshooting-and-debugging)
## Philosophy and Design Principles
@ -54,11 +52,7 @@ project-root/
├── static/ # Static assets (CSS, images, etc.)
│ ├── css/
│ └── images/
├── themes/ # Theme directory
│ └── theme-name/ # Individual theme
│ ├── layouts/ # Theme-specific templates (optional)
│ └── css/ # Alternative theme asset location
└── output/ # Generated site (created by qsgen3)
├── output/ # Generated site (created by qsgen3)
├── index.html
├── rss.xml
├── posts/
@ -77,10 +71,6 @@ site_name="My Awesome Site"
site_tagline="A brief description of my site"
site_url="http://localhost:8000"
# Theme Configuration
site_theme="minimal"
site_theme_css_file="css/style.css"
# Directory Paths
paths_content_dir="content"
paths_output_dir="output"
@ -103,535 +93,11 @@ build_options_process_drafts=false
### Key Configuration Variables
- **`site_theme`**: Name of the active theme (directory name in `themes/`)
- **`site_theme_css_file`**: Path to main CSS file relative to theme's static assets
- **`site_name`**: Name of the site
- **`site_url`**: Base URL for the site (used in RSS and absolute links)
- **`paths_*`**: Directory paths (can be relative or absolute)
- **`build_options_*`**: Boolean flags for optional features
## Theme System
### Theme Architecture
Themes in qsgen3 provide two main components:
1. **Templates**: Pandoc HTML templates for different page types
2. **Static Assets**: CSS, JavaScript, images, and other resources
### Theme Directory Structure
```
themes/theme-name/
├── layouts/ # Optional: Override default templates
│ ├── index.html # Homepage template
│ ├── post.html # Post template
│ └── rss.xml # RSS template
├── static/ # Preferred: Standard static assets location
│ ├── css/
│ └── js/
└── css/ # Alternative: Direct CSS location
└── style.css
```
### Theme Resolution Logic
1. **Theme Selection**: Based on `site_theme` in `site.conf`
2. **Layout Override**: If `themes/theme-name/layouts/` exists, it overrides `paths_layouts_dir`
3. **Static Asset Source**:
- First checks for `themes/theme-name/static/`
- Falls back to `themes/theme-name/` (for themes with assets at root level)
4. **CSS File Location**: Determined by `site_theme_css_file` relative to theme's static source
### Theme Switching
Switching themes is accomplished by:
1. Changing `site_theme` in `site.conf`
2. Updating `site_theme_css_file` to match the new theme's CSS structure
3. Running qsgen3 to regenerate the site
## Creating New Themes
### Theme Development Overview
Creating a new theme for qsgen3 involves designing templates and static assets that work together to provide a cohesive visual and functional experience. Themes can range from minimal CSS-only styling to complex designs with custom layouts and interactive elements.
### Step-by-Step Theme Creation
#### 1. Create Theme Directory Structure
Start by creating a new directory in the `themes/` folder:
```bash
mkdir -p themes/my-theme
cd themes/my-theme
```
Choose one of these organizational approaches:
**Option A: Standard Structure (Recommended)**
```
themes/my-theme/
├── layouts/ # Custom templates (optional)
│ ├── index.html # Homepage template
│ ├── post.html # Blog post template
│ └── rss.xml # RSS feed template
└── static/ # Static assets
├── css/
│ └── style.css # Main stylesheet
└── js/ # JavaScript files (optional)
```
**Option B: CSS-Only Structure**
```
themes/my-theme/
└── css/
└── style.css # Main stylesheet only
```
#### 2. Create the Main Stylesheet
Create your theme's primary CSS file. This is the only asset that qsgen3 will automatically link:
```css
/* themes/my-theme/static/css/style.css */
/* Reset and base styles */
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
line-height: 1.6;
color: #333;
background-color: #fff;
}
/* Header styles */
header {
background: #2c3e50;
color: white;
padding: 1rem 0;
margin-bottom: 2rem;
}
header h1 {
max-width: 800px;
margin: 0 auto;
padding: 0 1rem;
}
/* Main content */
main {
max-width: 800px;
margin: 0 auto;
padding: 0 1rem;
}
/* Post styles */
article {
margin-bottom: 3rem;
padding-bottom: 2rem;
border-bottom: 1px solid #eee;
}
article h1, article h2 {
color: #2c3e50;
margin-bottom: 0.5rem;
}
article .meta {
color: #666;
font-size: 0.9rem;
margin-bottom: 1rem;
}
/* Navigation and links */
nav ul {
list-style: none;
display: flex;
gap: 1rem;
}
nav a {
color: #3498db;
text-decoration: none;
}
nav a:hover {
text-decoration: underline;
}
/* Responsive design */
@media (max-width: 768px) {
main {
padding: 0 0.5rem;
}
nav ul {
flex-direction: column;
gap: 0.5rem;
}
}
```
#### 3. Create Custom Templates (Optional)
If you want to override the default templates, create custom Pandoc templates:
**Homepage Template (`layouts/index.html`)**
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>$site_name$</title>
$if(css)$<link rel="stylesheet" href="$css$">$endif$
</head>
<body>
<header>
<h1>$site_name$</h1>
$if(site_tagline)$<p>$site_tagline$</p>$endif$
</header>
<main>
<section class="posts">
<h2>Recent Posts</h2>
$if(posts)$
<ul class="post-list">
$for(posts)$
<li class="post-item">
<h3><a href="$it.post_url$">$it.post_title$</a></h3>
<div class="meta">
$if(it.post_date)$<time>$it.post_date$</time>$endif$
$if(it.post_author)$ by $it.post_author$$endif$
</div>
$if(it.post_description)$<p>$it.post_description$</p>$endif$
</li>
$endfor$
</ul>
$else$
<p>No posts available.</p>
$endif$
</section>
</main>
<footer>
<p>&copy; 2024 $site_name$. Generated with qsgen3.</p>
</footer>
</body>
</html>
```
**Post Template (`layouts/post.html`)**
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>$title$ - $site_name$</title>
$if(css)$<link rel="stylesheet" href="$css$">$endif$
$if(description)$<meta name="description" content="$description$">$endif$
</head>
<body>
<header>
<h1><a href="/">$site_name$</a></h1>
$if(site_tagline)$<p>$site_tagline$</p>$endif$
</header>
<main>
<article>
<header class="post-header">
<h1>$title$</h1>
<div class="meta">
$if(date)$<time datetime="$date$">$date$</time>$endif$
$if(author)$ by <span class="author">$author$</span>$endif$
</div>
</header>
<div class="post-content">
$body$
</div>
</article>
<nav class="post-nav">
<a href="/">&larr; Back to Home</a>
</nav>
</main>
<footer>
<p>&copy; 2024 $site_name$. Generated with qsgen3.</p>
</footer>
</body>
</html>
```
#### 4. Add JavaScript (Optional)
If your theme requires JavaScript functionality, add it to the static assets:
```javascript
// themes/my-theme/static/js/theme.js
document.addEventListener('DOMContentLoaded', function() {
// Add smooth scrolling
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
anchor.addEventListener('click', function (e) {
e.preventDefault();
const target = document.querySelector(this.getAttribute('href'));
if (target) {
target.scrollIntoView({
behavior: 'smooth'
});
}
});
});
// Add copy code button functionality
document.querySelectorAll('pre code').forEach(block => {
const button = document.createElement('button');
button.textContent = 'Copy';
button.className = 'copy-button';
button.addEventListener('click', () => {
navigator.clipboard.writeText(block.textContent);
button.textContent = 'Copied!';
setTimeout(() => button.textContent = 'Copy', 2000);
});
block.parentNode.appendChild(button);
});
});
```
**Important**: Remember that qsgen3 will not automatically include JavaScript files. You must add `<script>` tags to your templates:
```html
<!-- Add to your template's <head> or before </body> -->
<script src="/static/js/theme.js"></script>
```
#### 5. Configure Theme Usage
Update your `site.conf` to use the new theme:
```bash
# Theme Configuration
site_theme="my-theme"
site_theme_css_file="css/style.css" # Path relative to theme's static source
```
For CSS-only themes using the alternative structure:
```bash
site_theme="my-theme"
site_theme_css_file="style.css" # Direct path if CSS is at theme root
```
#### 6. Test Your Theme
Generate your site to test the theme:
```bash
./bin/qsgen3
```
Check the output:
- Verify CSS is applied correctly
- Test responsive design on different screen sizes
- Validate HTML structure
- Check that all assets are copied correctly
### Theme Development Best Practices
#### CSS Guidelines
1. **Use Relative Units**: Prefer `rem`, `em`, and percentages over fixed pixels
2. **Mobile-First Design**: Start with mobile styles, then add desktop enhancements
3. **Semantic Selectors**: Use class names that describe content, not appearance
4. **CSS Custom Properties**: Use CSS variables for consistent theming
```css
:root {
--primary-color: #2c3e50;
--secondary-color: #3498db;
--text-color: #333;
--background-color: #fff;
--border-color: #eee;
--font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}
body {
color: var(--text-color);
background-color: var(--background-color);
font-family: var(--font-family);
}
```
#### Template Guidelines
1. **Conditional Content**: Use Pandoc's conditional syntax for optional elements
2. **Semantic HTML**: Use appropriate HTML5 semantic elements
3. **Accessibility**: Include proper ARIA labels and alt text
4. **Meta Tags**: Include essential meta tags for SEO and social sharing
```html
<!-- Good conditional usage -->
$if(description)$<meta name="description" content="$description$">$endif$
$if(author)$<meta name="author" content="$author$">$endif$
<!-- Semantic structure -->
<main role="main">
<article>
<header>
<h1>$title$</h1>
</header>
<div class="content">
$body$
</div>
</article>
</main>
```
#### Asset Organization
1. **Logical Structure**: Group related assets in appropriate directories
2. **Naming Conventions**: Use consistent, descriptive file names
3. **Optimization**: Optimize images and minimize CSS/JS when possible
4. **Dependencies**: Document any external dependencies clearly
### Advanced Theme Features
#### Dark Mode Support
Add CSS custom properties and media queries for dark mode:
```css
:root {
--bg-color: #fff;
--text-color: #333;
--border-color: #eee;
}
@media (prefers-color-scheme: dark) {
:root {
--bg-color: #1a1a1a;
--text-color: #e0e0e0;
--border-color: #333;
}
}
body {
background-color: var(--bg-color);
color: var(--text-color);
transition: background-color 0.3s ease, color 0.3s ease;
}
```
#### Print Styles
Include print-specific styles:
```css
@media print {
header, footer, nav {
display: none;
}
body {
font-size: 12pt;
line-height: 1.4;
}
a[href]:after {
content: " (" attr(href) ")";
}
}
```
#### Custom Fonts
If using custom fonts, include them properly:
```css
/* Load fonts */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap');
/* Or use local fonts */
@font-face {
font-family: 'CustomFont';
src: url('/static/fonts/custom-font.woff2') format('woff2'),
url('/static/fonts/custom-font.woff') format('woff');
font-display: swap;
}
```
### Theme Distribution
#### Documentation
Create a `README.md` for your theme:
```markdown
# My Theme
A clean, minimal theme for qsgen3.
## Features
- Responsive design
- Dark mode support
- Clean typography
- Fast loading
## Installation
1. Copy theme to `themes/my-theme/`
2. Update `site.conf`:
```
site_theme="my-theme"
site_theme_css_file="css/style.css"
```
3. Run `./bin/qsgen3`
## Customization
- Edit CSS custom properties in `style.css`
- Modify templates in `layouts/` directory
- Add custom JavaScript in `static/js/`
## Browser Support
- Modern browsers (Chrome 90+, Firefox 88+, Safari 14+)
- Graceful degradation for older browsers
```
#### Version Control
If sharing your theme:
1. Use semantic versioning
2. Tag releases appropriately
3. Include a changelog
4. Provide example configurations
### Troubleshooting Theme Development
#### Common Issues
1. **CSS Not Loading**: Check `site_theme_css_file` path matches actual file location
2. **Templates Not Found**: Ensure template files are in `layouts/` directory
3. **Assets Missing**: Verify static files are in correct directory structure
4. **JavaScript Errors**: Remember to include `<script>` tags in templates
#### Testing Checklist
- [ ] CSS loads correctly on all page types
- [ ] Templates render without Pandoc errors
- [ ] Responsive design works on mobile devices
- [ ] All static assets are accessible
- [ ] JavaScript functionality works (if applicable)
- [ ] Print styles are appropriate
- [ ] Accessibility standards are met
- [ ] Performance is acceptable
## Content Processing Pipeline
### Markdown Processing
@ -740,7 +206,8 @@ output/
│ └── post-name.html
├── static/ # All static assets
│ ├── css/ # Stylesheets
│ └── js/ # JavaScript (if provided by theme)
│ ├── js/ # JavaScript (if provided by theme)
│ └── images/ # Images and media
└── css/ # Legacy: Index-specific CSS location
└── theme.css # Copy of main theme CSS for index page
```
@ -845,23 +312,7 @@ Check Dependencies
└── Exit with error if dependencies missing
```
### 4. Theme Processing
```
Process Theme Configuration
├── Read site_theme from configuration
├── Determine theme base path: themes/$site_theme
├── Check for theme layouts directory
│ ├── If exists: Override paths_layouts_dir
│ └── If not: Use default layouts
├── Determine theme static source
│ ├── Check themes/$site_theme/static/
│ ├── Fallback to themes/$site_theme/
│ └── Set QSG_CONFIG[theme_static_source_dir]
└── Log theme processing decisions
```
### 5. Output Preparation
### 4. Output Preparation
```
Prepare Output Directory
@ -874,7 +325,8 @@ Prepare Output Directory
│ ├── Recreate clean output directory
│ ├── Restore preserved files maintaining directory structure
│ └── Clean up temporary backup directory
│ └── Remove entire output directory
├── If no preserve file:
│ ├── Remove entire output directory
│ └── Create fresh output directory
└── Log preservation and cleaning operations
```
@ -911,7 +363,7 @@ downloads/*
- Flexible pattern matching for various preservation needs
- Backward compatible (no preserve file = complete cleaning)
### 6. Static File Processing
### 5. Static File Processing
```
Copy Static Files
@ -924,7 +376,7 @@ Copy Static Files
└── Log copy operations and results
```
### 7. CSS Path Determination
### 6. CSS Path Determination
```
Determine CSS Linking
@ -935,7 +387,7 @@ Determine CSS Linking
└── Log CSS path decisions and warnings
```
### 8. Content Processing
### 7. Content Processing
```
Process Markdown Content
@ -949,7 +401,7 @@ Process Markdown Content
└── Collect metadata for index and RSS generation
```
### 9. Index Generation
### 8. Index Generation
```
Generate Index Page
@ -961,7 +413,7 @@ Generate Index Page
└── Clean up temporary files
```
### 10. RSS Generation
### 9. RSS Generation
```
Generate RSS Feed
@ -973,7 +425,7 @@ Generate RSS Feed
└── Clean up temporary files
```
### 11. Finalization
### 10. Finalization
```
Complete Generation
@ -999,19 +451,7 @@ Complete Generation
- Check theme directory structure
- Enable debug logging to trace CSS path resolution
#### 2. Theme Not Found
**Symptoms**: Warning about theme directory not found
**Causes**:
- Typo in `site_theme` configuration
- Theme directory doesn't exist
- Incorrect theme directory structure
**Solutions**:
- Verify theme name spelling in site.conf
- Check themes/ directory exists and contains named theme
- Ensure theme directory has expected structure
#### 3. Template Errors
#### 2. Template Errors
**Symptoms**: Pandoc errors during HTML generation
**Causes**:
- Missing required templates
@ -1023,7 +463,7 @@ Complete Generation
- Check Pandoc template syntax
- Review template variable usage
#### 4. Static File Copy Issues
#### 3. Static File Copy Issues
**Symptoms**: Assets missing from output directory
**Causes**:
- Permission issues
@ -1035,7 +475,7 @@ Complete Generation
- Verify available disk space
- Review path configurations for absolute vs. relative paths
#### 5. File Preservation Issues
#### 4. File Preservation Issues
**Symptoms**: Expected files not preserved during cleaning, or preservation not working
**Causes**:
- Incorrect patterns in `.qsgen3_preserve` file
@ -1086,5 +526,3 @@ Ensure site.conf follows the correct format:
- Comments start with `#`
---
*This document reflects the current implementation of qsgen3 and its design philosophy of remaining completely design-agnostic while providing flexible theme and content management capabilities.*