From f4b04bd3f4d516f7d7afbd62da123cf6de1e0f5d Mon Sep 17 00:00:00 2001
From: Florian <f.weber@flweber.me>
Date: Sun, 2 Mar 2025 23:36:18 +0100
Subject: [PATCH] Improving readme

---
 README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 54 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2e308e3..1a3c9af 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,55 @@
-# morlana-pages
+# Morlana Pages Free Subdomain Service
+
+## Overview
+This repository provides a free subdomain service for the `morlana.page` domain, similar to `js.org`. Users can request a subdomain by forking this repository, adding their domain entry to `domains.yaml`, and submitting a pull request.
+
+## How It Works
+1. Fork this repository.
+2. Add your subdomain entry to `domains.yaml`, ensuring it is in alphabetical order.
+3. Submit a pull request.
+4. Once the PR is approved and merged, an automated workflow updates the DNS records via the Cloudflare API.
+
+## Subdomain Requirements
+- Only **CNAME** records are allowed.
+- The Cloudflare proxy is **enabled by default**, but can be disabled per subdomain.
+- Reserved domains cannot be registered (e.g., `www.morlana.page`).
+
+## How to Request a Subdomain
+### 1. Edit `domains.yaml`
+Add your subdomain under the `subdomains` section:
+
+```yaml
+subdomains:
+  - name: "your-subdomain"
+    target: "your-site.example.com"
+    proxy: true  # Set to false if you want to disable the Cloudflare proxy
+    note: "Optional description"
+```
+
+### 2. Submit a Pull Request
+- Ensure that your subdomain entry is in **alphabetical order**.
+- Verify that your CNAME target is correct.
+- Create a pull request with your changes.
+
+## Reserved Domains
+Some subdomains are **reserved** and cannot be registered. The list includes:
+- `www.morlana.page`
+- `api.morlana.page`
+- `mail.morlana.page`
+- Domains matching specific patterns (e.g., `admin.*`, `internal.*`).
+
+## Automation
+Once a pull request is merged, a GitHub Action will:
+1. Validate the `domains.yaml` file.
+2. Check for duplicate or reserved domains.
+3. Update the Cloudflare DNS settings automatically.
+
+## Setup for Maintainers
+### Environment Variables
+To enable Cloudflare DNS updates, set the following secrets in Gitea:
+- `CLOUDFLARE_API_TOKEN`: API token with DNS write access.
+- `CLOUDFLARE_ZONE_ID`: Cloudflare Zone ID for `morlana.page`.
+
+## License
+This project is open-source and licensed under the BSD-3-Clause.