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.

site.conf.example

@@ -1,26 +1,26 @@
-; Place this file in your project directory
+# Example Site Configuration for qsgen3
+# Copy this file to 'site.conf' in your project root and customize it.
 
-[site]
-; This is the name of your site
-name = "The Site Name"
-; This is the tagline
-tagline = "The Site Tagline"
-; This is the URL of your site
-url = "https://www.example.com"
-; This is where your HTML files go
-root = /path/to/www/dir
-; The theme of your site
-theme = theme_name
-; sitemap or not: true or false
-sitemap = true
-; Do you want the blog to appear on the front page
-; true = yes and false = no
-blog = true
+# --- Site Metadata ---
+site_name="My Example Site"
+site_tagline="An example site generated by qsgen3"
+site_url="http://localhost:8000" # Or your actual production URL
+site_theme="default" # Specifies the theme to use (e.g., default, dark)
 
-[project]
-; This is where you work before you generate the output
-root = /path/to/working/project
-; Languages: en_US, en_UK, es_ES, nb_NO, fr_FR
-lang = en_US
-; Use QStags (native) or Markdown (markdown)
-generator = native
+# --- Paths (relative to project root) ---
+paths_content_dir="content"
+paths_output_dir="output"
+paths_layouts_dir="layouts"
+paths_static_dir="static"
+
+# --- Build Options ---
+# Generate an RSS feed (true/false)
+build_options_generate_rss=true
+
+# Generate a sitemap.xml (true/false)
+# Note: sitemap generation is not fully implemented in qsgen3 yet,
+# but the configuration option is reserved.
+build_options_generate_sitemap=true
+
+# Process draft posts/pages (true/false)
+build_options_process_drafts=false