split readme into separate files in doc, nicer doc view

splitbrain · splitbrain · commit 2531bb009c1b · 2025-03-23T18:15:04.000+01:00
diff --git a/README.md b/README.md
@@ -1,163 +1,36 @@
-# Meh...
+# Meh... another comment system
 
+## Features
 
-A simple comment system for your static (or non-static) site.
+## Overview
 
+## Devel Quick Start
 
-## Quick Start
+You can use this to get a development environment up and running quickly. This is not suitable for production use. But should answer all your questions about how Meh works.
 
     cd backend
     composer install
     cd ../frontend
     npm install
     npm run build
     cd ..
+    cp .env.example .env
+    $EDITOR .env
     ./meh migrate
-    ./meh config site_url https://myblog.example.com
-    ./meh config admin_password supersecret
+    php -s localhost:8000 -t public
 
-Point your Apache to the `public` directory and you're good to go.
+You can then use `http://localhost:8000/` as the base URL for all components.
 
-## Command Line Tool
+## Server
 
-Meh comes with a command line tool that helps you manage your comment system. The `meh` command provides utilities for database management, configuration, and importing comments from other platforms.
 
-To see available commands:
+* [Command Line Tool](doc/cli.md)
+* [Database Setup and Upgrade](doc/migrate.md) 
+* [Configuration](doc/config.md)
+* [Mastodon Integration](doc/mastodon.md)
 
-    ./meh
 
-All commands support the `--site` (or `-s`) parameter to specify which site to operate on. This is useful if you're managing multiple sites with the same Meh installation.
-
-    ./meh --site myblog config
-
-If not specified, the default site name "meh" will be used. Site names have to be lowercase and can only contain letters, numbers, and underscores. Each site corresponds to a separate SQLite database.
-
-## Database Migration
-
-The `migrate` command is essential for setting up and maintaining your Meh installation:
-
-```
-./meh migrate
-```
-
-This command:
-
-1. Creates a new SQLite database for your site if it doesn't exist yet
-2. Applies any pending database schema migrations to keep your database structure up-to-date
-3. Generates a secure JWT secret if one doesn't exist
-
-You should run this command:
-- When first setting up Meh
-- After updating to a new version of Meh
-- When creating a new site in a multi-site setup (with the `--site` parameter)
-
-For multi-site setups, specify the site name:
-
-```
-./meh --site blog2 migrate
-```
-
-It is important to run this command for each of your sites when upgrading to a new version of Meh.
-
-## Configuration
-
-Meh uses a layered configuration system that allows for flexible setup across multiple sites:
-
-1. **Default Values**: Every configuration option has a sensible default value.
-
-2. **Environment Variables**: Defaults can be overridden by environment variables prefixed with `MEH_` (e.g., the `site_url` config can be set via the `MEH_SITE_URL` env var).
-
-3. **`.env` File**: For convenience, you can place environment variables in a `.env` file in the project root. The project contains a `.env.example` file that you can copy and modify.
-
-4. **Database Storage**: Site-specific configurations can stored in each site's database and take precedence over environment variables.
-
-### Configuration Hierarchy
-
-When Meh looks for a configuration value, it checks these sources in order:
-
-1. Default values (lowest priority)
-2. Environment variables / `.env` file
-3. Database values (highest priority)
-
-### Managing Configuration
-
-Use the `meh config` command to view or modify database configuration values:
-
-```
-# View all configuration values and their sources
-./meh config
-
-# View a specific configuration value
-./meh config site_url
-
-# Set a configuration value in the database
-./meh config site_url https://example.com
-
-# Remove a database configuration (revert to environment or default)
-./meh config site_url ""
-```
-
-For multi-site setups, use the `--site` parameter:
-
-```
-./meh --site blog1 config site_url https://blog1.example.com
-./meh --site blog2 config site_url https://blog2.example.com
-```
- 
-Configs set up via Environment always apply to all sites, while configs set up via the database are site-specific.
-
-## Mastodon Integration
-
-Meh includes built-in support for integrating with Mastodon, allowing you to import replies to your Mastodon posts as comments on your site.
-
-### Configuration
-
-To set up Mastodon integration:
-
-1. Configure your Mastodon account in your site settings:
-
-```
-./meh config mastodon_account "@yourusername@instance.social"
-```
-
-2. If you're using GoToSocial, even read access requires an API token. The easiest way to get one is to use the [Access Token Generator for Mastodon API](https://takahashim.github.io/mastodon-access-token/). You only need the `read` scope.
-
-```
-./meh config mastodon_token "your-api-token"
-```
-
-3. Set up a cron job to periodically fetch new posts and replies:
-
-```
-# Run every hour to check for new Mastodon posts and replies
-0 * * * * /path/to/meh mastodon
-```
-
-For multi-site setups you need to set up a `mastodon_account` config and cron job for each site. But you can have all sites use the same account.
-
-### How It Works
-
-The Mastodon integration:
-
-1. Fetches posts from your configured Mastodon account
-2. Identifies posts that link to your site
-3. Tracks these posts in the database
-4. Periodically checks for replies to these posts
-5. Imports replies as comments on the corresponding blog post
-
-This creates a seamless bridge between discussions on your blog and on the Fediverse.
-
-### Manual Import
-
-You can manually trigger the Mastodon import process at any time:
-
-```
-./meh mastodon
-```
-
-This is useful for testing or for an initial import of existing conversations.
-
-## Components
+## Client (your blog)
 
 * [meh-form](./frontend/src/components/meh-form/readme.md)
 * [meh-comments](./frontend/src/components/meh-comments/readme.md)
diff --git a/backend/src/FileController.php b/backend/src/FileController.php
@@ -6,16 +6,19 @@ class FileController
 {
     const DIST_PATH = __DIR__ . '/../../frontend/dist/meh';
     const COMPONENTS_PATH = __DIR__ . '/../../frontend/src/components';
+    const DOC_PATH = __DIR__ . '/../../doc';
     const README = __DIR__ . '/../../README.md';
 
     public function home()
     {
         header('Content-Type: text/html; charset=utf-8');
-        echo '<html lang="en"><head><title>Meh</title></head><body>';
+        echo '<html lang="en"><head><title>Meh</title>';
+        echo '<link rel="stylesheet" href="https://unpkg.com/chota@latest">';
+        echo '</head><body><div class="container">';
         echo '<h1>Welcome to Meh</h1>';
         echo '<p>It\'s a comment system.</p>';
         echo '<p>Check out the <a href="/doc/index">documentation</a>.</p>';
-        echo '</body></html>';
+        echo '</div></body></html>';
     }
 
     /**
@@ -27,12 +30,12 @@ public function home()
      */
     public function dist($file): void
     {
-        // everything else should be already handle by the router match type
-        if(str_contains($file, '..') || str_starts_with($file, '.')) {
+        // everything else should be already handled by the router match type
+        if (str_contains($file, '..') || str_starts_with($file, '.')) {
             throw new HttpException('Invalid file path', 400);
         }
 
-        if(!file_exists(self::DIST_PATH . '/' . $file)) {
+        if (!file_exists(self::DIST_PATH . '/' . $file)) {
             throw new HttpException('File not found', 404);
         }
 
@@ -55,26 +58,30 @@ public function i18n($file): void
 
     public function doc($file): void
     {
-        // everything else should be already handle by the router match type
-        if(str_contains((string) $file, '..') || str_starts_with((string) $file, '.')) {
+        // everything else should be already handled by the router match type
+        if (str_contains((string)$file, '..') || str_starts_with((string)$file, '.')) {
             throw new HttpException('Invalid file path', 400);
         }
 
-        if($file === 'index') {
+        if ($file === 'index') {
             $mdfile = self::README;
+        } elseif (file_exists(self::DOC_PATH . '/' . $file . '.md')) {
+            $mdfile = self::DOC_PATH . '/' . $file . '.md';
         } else {
             $mdfile = self::COMPONENTS_PATH . '/' . $file . '/readme.md';
         }
 
-        if(!file_exists($mdfile)) {
+        if (!file_exists($mdfile)) {
             throw new HttpException('File not found', 404);
         }
 
         $html = \Parsedown::instance()->text(file_get_contents($mdfile));
 
         header('Content-Type: text/html; charset=utf-8');
-        echo '<html lang="en"><head><title>' . $file . '</title></head><body>';
+        echo '<html lang="en"><head><title>' . $file . '</title>';
+        echo '<link rel="stylesheet" href="https://unpkg.com/chota@latest">';
+        echo '</head><body><div class="container">';
         echo $html;
-        echo '</body></html>';
+        echo '</div></body></html>';
     }
 }
diff --git a/doc/cli.md b/doc/cli.md
@@ -0,0 +1,13 @@
+# Command Line Tool
+
+Meh comes with a command line tool that helps you manage your comment system. The `meh` command provides utilities for database management, configuration, and importing comments from other platforms.
+
+To see available commands:
+
+    ./meh
+
+All commands support the `--site` (or `-s`) parameter to specify which site to operate on. This is useful if you're managing multiple sites with the same Meh installation.
+
+    ./meh --site myblog config
+
+If not specified, the default site name "meh" will be used. Site names have to be lowercase and can only contain letters, numbers, and underscores. Each site corresponds to a separate SQLite database.
diff --git a/doc/config.md b/doc/config.md
@@ -0,0 +1,46 @@
+# Configuration
+
+Meh uses a layered configuration system that allows for flexible setup across multiple sites:
+
+1. **Default Values**: Every configuration option has a sensible default value.
+
+2. **Environment Variables**: Defaults can be overridden by environment variables prefixed with `MEH_` (e.g., the `site_url` config can be set via the `MEH_SITE_URL` env var).
+
+3. **`.env` File**: For convenience, you can place environment variables in a `.env` file in the project root. The project contains a `.env.example` file that you can copy and modify.
+
+4. **Database Storage**: Site-specific configurations can stored in each site's database and take precedence over environment variables.
+
+## Configuration Hierarchy
+
+When Meh looks for a configuration value, it checks these sources in order:
+
+1. Default values (lowest priority)
+2. Environment variables / `.env` file
+3. Database values (highest priority)
+
+## Managing Configuration
+
+Use the `meh config` [CLI command](cli) to view or modify database configuration values:
+
+```
+# View all configuration values and their sources
+./meh config
+
+# View a specific configuration value
+./meh config site_url
+
+# Set a configuration value in the database
+./meh config site_url https://example.com
+
+# Remove a database configuration (revert to environment or default)
+./meh config site_url ""
+```
+
+For multi-site setups, use the `--site` parameter:
+
+```
+./meh --site blog1 config site_url https://blog1.example.com
+./meh --site blog2 config site_url https://blog2.example.com
+```
+
+Configs set up via Environment always apply to all sites, while configs set up via the database are site-specific.
diff --git a/doc/mastodon.md b/doc/mastodon.md
@@ -0,0 +1,50 @@
+## Mastodon Integration
+
+Meh includes built-in support for integrating with Mastodon, allowing you to import replies to your Mastodon posts as comments on your site.
+
+### Configuration
+
+To set up Mastodon integration:
+
+1. Configure your Mastodon account in your site settings:
+
+```
+./meh config mastodon_account "@yourusername@instance.social"
+```
+
+2. If you're using GoToSocial, even read access requires an API token. The easiest way to get one is to use the [Access Token Generator for Mastodon API](https://takahashim.github.io/mastodon-access-token/). You only need the `read` scope.
+
+```
+./meh config mastodon_token "your-api-token"
+```
+
+3. Set up a cron job to periodically fetch new posts and replies:
+
+```
+# Run every hour to check for new Mastodon posts and replies
+0 * * * * /path/to/meh mastodon
+```
+
+For multi-site setups you need to set up a `mastodon_account` config and cron job for each site. But you can have all sites use the same account.
+
+### How It Works
+
+The Mastodon integration:
+
+1. Fetches posts from your configured Mastodon account (uses the Mastodon API)
+2. Identifies posts that link to your site
+3. Tracks these posts in the database
+4. Periodically checks for replies to these posts
+5. Imports replies as comments on the corresponding blog post
+
+This creates a seamless bridge between discussions on your blog and on the Fediverse.
+
+### Manual Import
+
+You can manually trigger the Mastodon import process at any time:
+
+```
+./meh mastodon
+```
+
+This is useful for testing or for an initial import of existing conversations.
diff --git a/doc/migrate.md b/doc/migrate.md
@@ -0,0 +1,26 @@
+# Database Setup and Upgrade
+
+The `migrate` [CLI command](cli) is essential for setting up and maintaining your Meh installation:
+
+```
+./meh migrate
+```
+
+This command:
+
+1. Creates a new SQLite database for your site if it doesn't exist yet
+2. Applies any pending database schema migrations to keep your database structure up-to-date
+3. Generates a secure JWT secret if one doesn't exist
+
+You should run this command:
+- When first setting up Meh
+- After updating to a new version of Meh
+- When creating a new site in a multi-site setup (with the `--site` parameter)
+
+For multi-site setups, specify the site name:
+
+```
+./meh --site blog2 migrate
+```
+
+It is important to run this command for each of your sites when upgrading to a new version of Meh.

Original file line number	Diff line number	Diff line change
`@@ -6,16 +6,19 @@ class FileController`
`6`	`6`	`{`
`7`	`7`	`const DIST_PATH = __DIR__ . '/../../frontend/dist/meh';`
`8`	`8`	`const COMPONENTS_PATH = __DIR__ . '/../../frontend/src/components';`
	`9`	`+ const DOC_PATH = __DIR__ . '/../../doc';`
`9`	`10`	`const README = __DIR__ . '/../../README.md';`
`10`	`11`
`11`	`12`	`public function home()`
`12`	`13`	`{`
`13`	`14`	`header('Content-Type: text/html; charset=utf-8');`
`14`		`- echo '<html lang="en"><head><title>Meh</title></head><body>';`
	`15`	`+ echo '<html lang="en"><head><title>Meh</title>';`
	`16`	`+ echo '<link rel="stylesheet" href="https://unpkg.com/chota@latest">';`
	`17`	`+ echo '</head><body><div class="container">';`
`15`	`18`	`echo '<h1>Welcome to Meh</h1>';`
`16`	`19`	`echo '<p>It\'s a comment system.</p>';`
`17`	`20`	`echo '<p>Check out the <a href="/doc/index">documentation</a>.</p>';`
`18`		`- echo '</body></html>';`
	`21`	`+ echo '</div></body></html>';`
`19`	`22`	`}`
`20`	`23`
`21`	`24`	`/**`
`@@ -27,12 +30,12 @@ public function home()`
`27`	`30`	`*/`
`28`	`31`	`public function dist($file): void`
`29`	`32`	`{`
`30`		`- // everything else should be already handle by the router match type`
`31`		`- if(str_contains($file, '..') \|\| str_starts_with($file, '.')) {`
	`33`	`+ // everything else should be already handled by the router match type`
	`34`	`+ if (str_contains($file, '..') \|\| str_starts_with($file, '.')) {`
`32`	`35`	`throw new HttpException('Invalid file path', 400);`
`33`	`36`	`}`
`34`	`37`
`35`		`- if(!file_exists(self::DIST_PATH . '/' . $file)) {`
	`38`	`+ if (!file_exists(self::DIST_PATH . '/' . $file)) {`
`36`	`39`	`throw new HttpException('File not found', 404);`
`37`	`40`	`}`
`38`	`41`
`@@ -55,26 +58,30 @@ public function i18n($file): void`
`55`	`58`
`56`	`59`	`public function doc($file): void`
`57`	`60`	`{`
`58`		`- // everything else should be already handle by the router match type`
`59`		`- if(str_contains((string) $file, '..') \|\| str_starts_with((string) $file, '.')) {`
	`61`	`+ // everything else should be already handled by the router match type`
	`62`	`+ if (str_contains((string)$file, '..') \|\| str_starts_with((string)$file, '.')) {`
`60`	`63`	`throw new HttpException('Invalid file path', 400);`
`61`	`64`	`}`
`62`	`65`
`63`		`- if($file === 'index') {`
	`66`	`+ if ($file === 'index') {`
`64`	`67`	`$mdfile = self::README;`
	`68`	`+ } elseif (file_exists(self::DOC_PATH . '/' . $file . '.md')) {`
	`69`	`+ $mdfile = self::DOC_PATH . '/' . $file . '.md';`
`65`	`70`	`} else {`
`66`	`71`	`$mdfile = self::COMPONENTS_PATH . '/' . $file . '/readme.md';`
`67`	`72`	`}`
`68`	`73`
`69`		`- if(!file_exists($mdfile)) {`
	`74`	`+ if (!file_exists($mdfile)) {`
`70`	`75`	`throw new HttpException('File not found', 404);`
`71`	`76`	`}`
`72`	`77`
`73`	`78`	`$html = \Parsedown::instance()->text(file_get_contents($mdfile));`
`74`	`79`
`75`	`80`	`header('Content-Type: text/html; charset=utf-8');`
`76`		`- echo '<html lang="en"><head><title>' . $file . '</title></head><body>';`
	`81`	`+ echo '<html lang="en"><head><title>' . $file . '</title>';`
	`82`	`+ echo '<link rel="stylesheet" href="https://unpkg.com/chota@latest">';`
	`83`	`+ echo '</head><body><div class="container">';`
`77`	`84`	`echo $html;`
`78`		`- echo '</body></html>';`
	`85`	`+ echo '</div></body></html>';`
`79`	`86`	`}`
`80`	`87`	`}`