From 27927f45be222f7563f03d8d61302189520013ce Mon Sep 17 00:00:00 2001
From: Florian Walther <florian.walther@certainity.com>
Date: Fri, 1 May 2026 18:41:48 +0200
Subject: [PATCH] adding README

---
 README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6370b90
--- /dev/null
+++ b/README.md
@@ -0,0 +1,130 @@
+# mdhost
+
+A simple, single-binary Go web application for hosting and sharing markdown files.
+
+## Features
+
+- **Create, view, edit, and delete** markdown files via web interface
+- **Stable file IDs** - unique identifiers don't change when files are edited
+- **Syntax highlighting** for code blocks (bash, go, python, etc.)
+- **Optional authentication** - anonymous users can create files, registered users can claim them
+- **Access control** - edit/delete only your own files, public/private visibility toggle
+- **Responsive UI** - mobile-friendly CSS layout
+- **Persistent storage** - all data (users, sessions, file metadata) survives server restarts
+
+## Quick Start
+
+### Build
+
+```bash
+go build -o mdhost .
+```
+
+### Run
+
+```bash
+./mdhost
+```
+
+The server will start on `http://localhost:8080`.
+
+### Usage
+
+1. **List files**: Visit `/` to see all public markdown files
+2. **Add a file**: Click "add" in the nav bar, enter title and content, submit
+3. **View a file**: Click any file name in the list
+4. **Edit a file**: Click the `[edit]` link next to a file, or visit `/edit?id=<file-id>`
+5. **Delete a file**: Click the `[delete]` button (only visible for files you own)
+
+## Authentication
+
+### Anonymous Use
+
+You can create and edit files without an account. Files created anonymously are associated with your browser session (via cookie).
+
+### Register
+
+Click "register" in the nav bar to create an account. After registering:
+- Your existing anonymous files are automatically claimed and linked to your account
+- You can edit/delete all files created in your session
+
+### Login/Logout
+
+- Click "login" to authenticate with existing credentials
+- Click "logout" to end your session
+
+### Claiming Files
+
+Files created while anonymous are automatically claimed when you register or login from the same browser.
+
+## File Visibility
+
+- **Public files**: Appear in the public list, visible to all users
+- **Private files**: Only accessible via direct URL, don't appear in public list
+- Toggle visibility using the "Listed in public list" checkbox when editing
+
+## Configuration
+
+The following variables can be modified at the top of `main.go`:
+
+```go
+var (
+    postsDir  = "./posts"      // Directory for markdown files
+    dataDir   = "./data"       // Directory for persistent data (data.json)
+    port      = ":8080"        // Server port
+)
+
+var ListFormat = "ul"  // List rendering: "ul" (bullet), "ol" (numbered), "plain"
+```
+
+## Data Storage
+
+- **Markdown files**: Stored in `./posts/` directory
+- **Metadata**: Stored in `./data/data.json` (users, sessions, file metadata)
+- All data persists across server restarts
+
+## ID Generation
+
+File IDs are generated as the first 12 characters of a SHA1 hash:
+```
+SHA1(filename + creation_timestamp)[:12]
+```
+
+The creation timestamp is stored in the file's `CreatedAt` field and persists across restarts, ensuring stable IDs.
+
+## Security
+
+- Passwords are hashed using bcrypt
+- Sessions use HTTP-only cookies with 1-year expiry
+- File ownership is enforced (users can only edit/delete their own files)
+- Private files are hidden from public listings but accessible via direct URL
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | List all public files |
+| GET | `/home` | Homepage with README |
+| GET | `/view/{id}` | View rendered markdown |
+| GET | `/add` | Form to create new file |
+| POST | `/create` | Create new file |
+| GET | `/edit` | Select file to edit |
+| GET | `/edit?id={id}` | Edit specific file |
+| POST | `/update` | Save file edits |
+| POST | `/delete` | Delete a file |
+| GET/POST | `/register` | Create user account |
+| GET/POST | `/login` | Authenticate |
+| GET | `/logout` | Clear session |
+| GET | `/claim` | Claim anonymous files (auto-handled in register) |
+
+## Dependencies
+
+- Go 1.26+
+- `github.com/yuin/goldmark` v1.8.2
+- `github.com/yuin/goldmark-highlighting` v0.0.0-20220208100518-594be1970594
+- `github.com/alecthomas/chroma/v2` v2.24.1
+- `golang.org/x/crypto/bcrypt` v0.50.0
+
+## License
+
+MIT License