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

docs: Rewrite README with compelling storytelling approach

Browse Source 
Transform the README from a technical feature list into an engaging narrative that:

- Opens with a relatable problem story that developers/bloggers recognize
- Positions qsgen3 as the solution born from shared frustration
- Uses conversational storytelling tone throughout
- Organizes benefits as a narrative journey
- Clearly identifies target audiences with personas
- Provides actionable getting-started steps
- Ends with a compelling call to action

The new README focuses on why qsgen3 exists and what problems it solves, making it much more compelling for potential users while remaining informative and honest.
This commit is contained in:
Stig-Ørjan Smelror 2025-05-31 01:22:37 +02:00
parent 4b95426256
commit 5266559f26
1 changed files with 122 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
README.md
View File

@ -1,45 +1,132 @@
# qsgen3 - A Minimal Markdown Static Site Generator
# qsgen3 - A Static Site Generator Born from Frustration
This is a refactored version of qsgen, focusing on simplicity, Markdown with YAML frontmatter, and a Zsh-based build process.
## The Problem We All Know Too Well
## Project Goals
You've been there. You want to start a blog, build a portfolio, or create documentation. You research static site generators and find yourself drowning in choices, each promising to be "the one." You pick one, spend hours configuring it, wrestling with themes that almost work, and fighting build systems that break when you breathe on them wrong.
- Remove QSTags and switch to Markdown + YAML frontmatter.
- Simplify codebase by removing multilingual and theme support.
- Refactor templating with uniform variables (e.g., `{{ content }}`, `{{ title }}`).
- Ensure future-proofing by avoiding complex dependencies (like AWK for long string manipulation) for core tasks.
- Provide a solid initial setup that works out of the box with a sample post, index, and layout.
- Include a converter script in `scripts/convert-qstags-to-md.sh` for legacy content.
Three months later, you're spending more time maintaining your site generator than writing content.
## Structure
**There had to be a better way.**
- `bin/qsgen3`: The main Zsh build script.
- `site.conf`: Site configuration (INI format).
- `content/`: Source Markdown files.
- `content/posts/`: Blog posts.
- `content/pages/`: Static pages.
- `layouts/`: HTML templates.
- `layouts/base.html`: Base template for all pages.
- `layouts/post.html`: Template for individual blog posts.
- `layouts/page.html`: Template for static pages.
- `static/`: Static assets (CSS, images, etc.) copied as-is to the output.
- `output/`: The generated website.
- `scripts/`: Utility scripts (e.g., content converter).
## The Story Behind qsgen3
## Usage
qsgen3 was born from a simple realization: most static site generators have forgotten their primary job—turning your words into websites. Instead, they've become complex platforms that impose their opinions on everything from your CSS framework to your folder structure.
1. Configure your site in `site.conf`.
2. Add Markdown content to the `content/` directory.
3. Customize templates in `layouts/`.
4. Run the build script:
```bash
./bin/qsgen3
```
5. Your static site will be generated in the `output/` directory.
We asked ourselves: *What if a static site generator just... generated static sites?*
## Dependencies
What if it didn't care whether you prefer Bootstrap or write your own CSS? What if it didn't force you to learn a new templating language or adopt someone else's idea of how a blog should work? What if it was fast, reliable, and got out of your way?
- Zsh
- A Markdown processor (e.g., Pandoc, CommonMark, or a Zsh-native solution if feasible for basic needs).
- Standard Unix utilities (grep, sed, find, etc.).
That's qsgen3.
## How qsgen3 is Different
### It Respects Your Choices
Unlike generators that come with strong opinions about design, qsgen3 is **completely design-agnostic**. It doesn't ship with CSS frameworks, doesn't impose HTML structures, and doesn't make assumptions about how your site should look. Your content, your design, your rules.
### It Values Your Time
Built in Zsh with minimal dependencies, qsgen3 builds sites in seconds, not minutes. No waiting for Ruby gems to compile, no Node.js dependency hell, no Python virtual environments to manage. Just Pandoc, standard Unix tools, and your content.
### It Speaks Standard Languages
Your content is written in **pure Markdown with YAML frontmatter**—the same format used by GitHub, GitLab, and most modern documentation systems. No proprietary tags to learn, no custom syntax to remember. Your content works everywhere, not just with qsgen3.
### It Grows With You
Start with the included minimal theme, then customize it however you want. Themes are just HTML templates and CSS files—no complex build systems or framework lock-in. When you outgrow a theme, you can switch or build your own without rewriting a single blog post.
## What You Actually Get
When you use qsgen3, you get a tool that handles the boring stuff so you can focus on what matters—your content.
**For Your Writing:**
- Clean Markdown processing with full Pandoc power
- Automatic RSS feeds that just work
- SEO-friendly sitemaps
- Smart permalinks for blog posts (`/blog/2024/01/15/my-post/`)
- Draft support for work-in-progress content
**For Your Workflow:**
- Git-friendly (no generated files cluttering your repo)
- One command builds everything: `./bin/qsgen3`
- Migration tools for converting legacy content
- Static asset handling that preserves your file organization
**For Your Peace of Mind:**
- Minimal dependencies that won't break
- Standard formats that will outlive any framework
- Complete control over your site's appearance and behavior
- No vendor lock-in—your content is always portable
## Who This is For
**You're a blogger** who wants to write, not wrestle with technology. You need something that handles the technical details while giving you complete creative control.
**You're a developer** who appreciates tools that do one thing well. You want the power of Pandoc without the complexity of enterprise-grade site generators.
**You're migrating** from WordPress, Jekyll, Hugo, or a custom solution. You're tired of fighting your tools and want something that just works.
**You value simplicity** over features. You'd rather have a tool that does the essentials perfectly than one that does everything poorly.
## Getting Started is Actually Simple
Unlike other generators that require extensive setup, qsgen3 works out of the box:
```bash
# Get qsgen3
git clone https://git.kekepower.com/kekePower/qsgen3.git
cd qsgen3
# Configure your site
cp site.conf.example site.conf
# Edit site.conf with your details
# Write your first post
echo "---
title: Hello World
date: 2024-01-15
---
# My First Post
Welcome to my new site!" > content/posts/hello-world.md
# Build your site
./bin/qsgen3
# Deploy anywhere
rsync -av output/ user@yourserver:/var/www/yoursite/
```
That's it. No package managers, no build tools, no configuration files to debug.
## The Technical Details (For Those Who Care)
**Structure:**
```
qsgen3/
├── bin/qsgen3 # The build script (one file, ~500 lines)
├── site.conf # Your site configuration
├── content/ # Your Markdown content
├── layouts/ # HTML templates (yours to customize)
├── themes/ # Optional themes (just templates + CSS)
├── static/ # Your assets (copied as-is)
├── output/ # Generated site
└── scripts/ # Migration utilities
```
**Dependencies:**
- Zsh (already on your system)
- Pandoc (for Markdown processing)
- Standard Unix tools (grep, sed, find)
No Ruby. No Node.js. No Python virtual environments. No dependency management nightmares.
## The Philosophy
We believe your static site generator should be like a good editor—powerful when you need it, invisible when you don't. It should turn your words into websites without imposing its personality on your content.
qsgen3 doesn't try to be everything to everyone. It's a focused tool for people who want to publish content on the web without fighting their tools.
**Your content deserves better than being locked into someone else's vision of how the web should work.**
## Ready to Take Back Control?
If you're tired of complex site generators that do everything except what you actually need, qsgen3 might be exactly what you're looking for.
**[Get started with qsgen3](https://git.kekepower.com/kekePower/qsgen3)** and see what it feels like to have a site generator that actually gets out of your way.