adding README
This commit is contained in:
Florian Walther
@@ -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
|
||||||
Reference in New Issue
Block a user