feat: Docs: Remove dead links and amp up the guide

pixelbrackets · pixelbrackets · commit 8392d6681b4f · 2024-10-21T11:24:20.000+02:00
This project is still linked in many static site lists as one of the most popular PHP based generators and stared by many people. It's old and has it's quirks (see https://stitcher.io/blog/a-simple-approach-to-static-generation), but it's actually working. So a little upgrade to the docs - removing dead links, add sidenotes, explain some files - is probably okay. Furthermore, in view of the continuing popularity of the project despite the lack of updates, I believe it makes sense to explain the development status transparently and concisely: The project is in maintenance mode. That's it.
diff --git a/README.md b/README.md
@@ -1,16 +1,28 @@
-[![Build Status](https://scrutinizer-ci.com/g/brendt/stitcher/badges/build.png?b=master)](https://scrutinizer-ci.com/g/brendt/stitcher/build-status/master) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/brendt/stitcher/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/brendt/stitcher/?branch=master)
-
 # Stitcher
 
-High performance, static websites for PHP developers.
+[![Maintenance mode](https://img.shields.io/badge/maintenance_mode-%F0%9F%9A%A7-grey.svg?labelColor=orange)](https://github.com/agendav/agendav/#maintenance-mode)
 
-```bash
-composer create-project pageon/stitcher
-```
+**High performance, static websites for PHP developers.**
+
+![Screenshot](src/img/screenshot.png)
+
+Stitcher sites utilize a simple concept that allows PHP developers to quickly publish a structured website or blog.
+**Data entries** are mapped onto **templates** and “stitched” together via a **config file**.
+
+Data entries can be provided in many ways:
+JSON or YAML files, MarkDown files, images, SASS or CSS, JavaScript, folders and more.
 
-### Why Stitcher?
+Templates may use Twig or Smarty to output a desired HTML markup.
 
-Stitcher differs from many other static site generator in two areas. First of all: **performance is key**. Stitcher is built from its core for high performance websites. All tools available to you put performance on the first place. Secondly, it doesn't try to add extra syntax to existing formats. Stitcher provides a robust set of tools **for developers** to build with, and not a lot of hacks so everything fits in one file.
+And the config file: well, it's a small YAML.
+
+## Why Stitcher?
+
+Stitcher differs from many other static site generators in two areas.
+First of all: **performance is key**. Stitcher is built from its core for high performance websites.
+All tools available to you put performance on the first place.
+Secondly, it doesn't try to add extra syntax to existing formats. Stitcher provides a robust set of tools
+**for developers** to build with, and not a lot of hacks so everything fits in one file.
  
 Also important to note, included with Stitcher:
 
@@ -22,8 +34,22 @@ Also important to note, included with Stitcher:
 - Built-in SASS support
 - JavaScript and CSS minification
 - Built-in SEO and meta tag optimizations
+- CLI to run common actions
+
+## Setup
 
-A quick look at Stitcher:
+```bash
+composer create-project pageon/stitcher
+```
+
+For development purposes you may run the internal PHP server and point it to the `/dev` directory.
+You should see an introduction guide and example blog files.
+
+## Quick Guide
+
+A quick look at Stitcher.
+
+The site config defines template and data source files for different routes. This is a minimal blog setup:
 
 ```yaml
 # site.yml
@@ -43,6 +69,9 @@ A quick look at Stitcher:
             field: id
 ```
 
+Each blog post could come from different content sources, which are listed in data files.
+Metadata is stored here as well.
+
 ```yaml
 # data/blog.yml
 
@@ -61,6 +90,18 @@ foo_bar:
     image: foo_bar.jpg 
 ```
 
+One blog post, in this example it's just a MarkDown file.
+
+```markdown
+# data/blog/hello.md
+
+# Hello World
+
+This is a **MarkDown** file. That's it.
+```
+
+And finally, a template to render a single post:
+
 ```html
 <!-- blog.post.html --> 
 
@@ -79,21 +120,17 @@ foo_bar:
 {% endblock %}
 ```
 
+The [full documentation](src/data/guide.md) is shown when you run the project in a server.
 
-You can read more about it on [the Stitcher website](http://stitcher.pageon.be).
-
-### Upcoming features
+## Examples
 
-Stitcher is in alpha development, so new features are still being made. Here's a list of what's to come before a stable v1 release:
+This project is used, with some rather strong modifications, on [stitcher.io](https://stitcher.io),
+the source code for this blog is available at [github.com/brendt/stitcher.io](https://github.com/brendt/stitcher.io).
 
-- Plugin support
-- Theme support
+## Development
 
-Also, we're already thinking about the farther future:
+The core library is maintained in [github.com/pageon/stitcher-core](https://github.com/pageon/stitcher-core).
 
-- Localisation
-- URL generation
-- CLI Configuration and setup
-- site:deploy command
-- Frontend Filters
-- Form support with Lumen/Slim
+⌛ This project was created mainly for personal usage. It's in maintenance mode only.
+The development [faded out](https://stitcher.io/blog/a-simple-approach-to-static-generation) a while ago
+and the core will be replaced with a solution based on another framework eventually.
diff --git a/src/data/guide.md b/src/data/guide.md
@@ -1,17 +1,31 @@
+# Guide
+
+## Building a site with Stitcher
+
+Stitcher sites utilize a simple concept that allows PHP developers to quickly publish a structured website or blog.
+**Data entries** are mapped onto **templates** and “stitched” together via a **config file**.
+
+The goal is simple: create blazing fast websites. Stitcher will parse all your templates into static HTML pages, 
+will parse and minify CSS and JavaScript, will optimize images using ``srcset`` and provides useful developer tools
+to aid you in setting things up smoothly.
+
 ## Installation
 
-```sh
-composer create-project brendt/stitcher-site
+When you read this guide you probably have set up the project already. If not, run
+
+```bash
+composer create-project pageon/stitcher
 ```
 
-## Building a site with Stitcher
+For development purposes you may run the internal PHP server and point it to the `/dev` directory.
+
+```bash
+php -S localhost:80 -t dev/
+```
 
-Stitcher sites can be built by anyone with basic HTML knowledge: **data entries** are mapped onto **templates** which are accessible via **a URL**.
-These two components (entries and templates) are mapped - *stitched* - together via a **config file**. Data entries can be provided in many ways:
-JSON or YAML files, MarkDown files, images, SASS or CSS, JavaScript, folders and more.
+See »Host setup« to find out how to set up different hosts for development and production.
 
-The goal is simple: create blazing fast websites. Stitcher will parse all your templates into static HTML pages, will parse and minify CSS and JavaScript,
- will optimize images using ``srcset`` and provides useful developer tools to aid you in setting things up smoothly.
+## File setup
 
 ### site.yml
 
@@ -48,15 +62,15 @@ The ``site.yml`` file, located in the ``src/site`` directory is used to stitch t
 ```
 
 The ``template`` key is required and provides a path to the required template for this page.
- The ``data`` key isn't required. It takes a collection of variable names (these will be accessible in the template as variables).
- Each variable will need to be loaded. You can either provide a path to a data file (loaded from ``src/data`` by default),
- or you can provide a collection with a `src` and `id` key. This approach will generate detail pages from a collection of data entries.
+The ``data`` key isn't required. It takes a collection of variable names (these will be accessible in the template as variables).
+Each variable will need to be loaded. You can either provide a path to a data file (loaded from ``src/data`` by default),
+or you can provide a collection with a `src` and `id` key. This approach will generate detail pages from a collection of data entries.
 
 ### Data entries
 
 Data entries can be provided in many formats: JSON, YAML, MarkDown, image, folder, ... Examples can be found after running the `site:install` command.
- A data file can either contain data of a single entry, or contain a collection of multiple entries. In the second case, when using JSON or YAML files,
- An extra root key `entries` is required.
+A data file can either contain data of a single entry, or contain a collection of multiple entries. In the second case, when using JSON or YAML files,
+An extra root key `entries` is required.
 
 ```yaml
 entries:
@@ -79,8 +93,7 @@ See the `src/data` folder files for a more thorough reference.
 
 ### Templates
 
-At this moment, Stitcher only supports Smarty as a template engine. Support for more engines will be added in the future.
- In a template, all functionality of the engine is available, and all variables provided in `site.yml` are available.
+In a template, all functionality of the engine is available, and all variables provided in `site.yml` are available.
 
 ```html
 {extends 'index.tpl'}
@@ -98,7 +111,12 @@ At this moment, Stitcher only supports Smarty as a template engine. Support for
 {/block}
 ```
 
-### Helpers
+### Config
+
+The `config.yml` file provides some configuration options, to set directory paths, image rendering config, meta config and minification options.
+See the config file for more information.
+
+## Helpers
 
 Stitcher provides some helper functions in aid of creating fast websites.
 
@@ -128,30 +146,23 @@ Stitcher provides some helper functions in aid of creating fast websites.
 </html>
 ```
 
-### Config
+## Commands
 
-The `config.yml` file provides some configuration options, to set directory paths, image rendering config, meta config and minification options.
- See the config file for more information.
+Stitcher offers a command line script to run some static site actions.
 
-### Commands
+Run `./stitcher` to see the list of available commands and options. Some of them are:
 
 - `site:install`: Copy a base install example.
 - `site:generate [url]`: Generate the whole site, or a specific URL from `sites.yml`.
 - `site:clean [--force]`: Remove all the generated files.
 - `router:list`: List all available URLs from `sites.yml`.
 - `router:dispatch url`: Debug a specified URL.
 
-### Developer controller
-
-The developer controller can be used to generate a single URL on-the-fly. Thus enabling a developer to make changes to data entries, configs or templates; and see these changes in real-time, without the need of manually generating the website again.
+## Host setup
 
-It's obvious that this approach takes a bit more rendering time, so web pages will be slower.
+Stitcher requires at least one virtual host, two if you'd want to use the development mode.
 
-### Host setup
-
-Stitcher requires at least one virtual host, two if you'd want to use the developers controller.
-
-**production**
+**Production**
 
 ```xml
 <VirtualHost *:80>
@@ -167,7 +178,7 @@ Stitcher requires at least one virtual host, two if you'd want to use the develo
 </VirtualHost>
 ```
 
-**development**
+**Development**
 
 ```xml
 <VirtualHost *:80>
@@ -183,9 +194,8 @@ Stitcher requires at least one virtual host, two if you'd want to use the develo
 </VirtualHost>
 ```
 
-Don't forget to add a local host in ``/ets/hosts``.
+The development mode can be used to generate a single URL on-the-fly.
 
-```
-127.0.0.1 stitcher.local
-127.0.0.1 dev.stitcher.local
-```
+Thus enabling developers to make changes to data entries, configs or templates
+and see these changes in real-time, without the need of manually generating the website again.
+It's obvious that this approach takes a bit more rendering time, so web pages will be slower.
diff --git a/src/img/screenshot.png b/src/img/screenshot.png
diff --git a/src/template/home.tpl b/src/template/home.tpl
@@ -12,13 +12,13 @@
             Welcome to Stitcher
         </h2>
         <h3>
-            a tool to create <em>blazing</em> fast websites.
+            <em>High performance, static websites for PHP developers.</em>
         </h3>
 
         <div class="vwrapper">
-            <a class="button"  href="http://stitcher.pageon.be/guide/setting-up" target="_blank">Getting started</a>
+            <a class="button" href="/guide" target="_blank">Getting started</a>
             <em class="button-link">or</em>
-            <a class="button" href="http://stitcher.pageon.be/guide" target="_blank">Read the full guide</a>
+            <a class="button" href="/examples" target="_blank">Example blog</a>
         </div>
     </div>
 {/block}
diff --git a/src/template/index.tpl b/src/template/index.tpl
@@ -1,7 +1,7 @@
 <html>
     <head>
         {block 'head'}
-            <title>Stitcher 1.0</title>
+            <title>Stitcher</title>
             {meta}
             {css src="main.scss" inline=true}
         {/block}
@@ -12,7 +12,8 @@
                 <header>
                     <nav class="wrapper">
                         <a href="/" class="stitcher">Stitcher</a>
-                        <a href="http://stitcher.pageon.be/guide/setting-up" target="_blank">Guide</a>
+                        <a href="/guide">Guide</a>
+                        <a href="/examples">Example blog</a>
                     </nav>
                 </header>
             {/block}
