adds mdbook scaffolding

.gitignore

@@ -1,10 +1,2 @@
-.idea/
+book
-.cache/
+
-*.iml
-key-database.pogreb/
-acme-account.json
-build/
-vendor/
-pages
-certs.sqlite
-.bash_history

README.md

@@ -11,8 +11,7 @@ The Codeberg Pages Server addresses this lack by implementing a standalone servi
 that connects to Gitea via API.
 It is suitable to be deployed by other Gitea instances, too, to offer static pages hosting to their users.
 
-**End user documentation** can mainly be found at the [Wiki](https://codeberg.org/Codeberg/pages-server/wiki/Overview)
+**End user documentation** can mainly be found in the [Codeberg Documentation](https://docs.codeberg.org/codeberg-pages/).
-and the [Codeberg Documentation](https://docs.codeberg.org/codeberg-pages/).
 
 <a href="https://codeberg.org/Codeberg/pages-server"> <img src="https://codeberg.org/Codeberg/GetItOnCodeberg/raw/branch/main/get-it-on-blue-on-white.svg" alt="Get It On Codeberg" width="250"/> </a>
 
@@ -105,7 +104,6 @@ Previous maintainers:
 ### First steps
 
 The code of this repository is split in several modules.
-The [Architecture is explained](https://codeberg.org/Codeberg/pages-server/wiki/Architecture) in the wiki.
 
 The `cmd` folder holds the data necessary for interacting with the service via the cli.
 The heart of the software lives in the `server` folder and is split in several modules.

book.toml

@@ -0,0 +1,24 @@
+[book]
+authors = ["Codeberg Contributors"]
+language = "en"
+multilingual = true
+src = "src"
+title = "Pages"
+
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]
+max-level = 5
+
+[output.html]
+curly-quotes = true
+git-repository-icon = "fa-git"
+
+[output.html.playground]
+editable = true
+
+[output.html.search]
+enable = true
+
+[build]
+create-missing = false

src/SUMMARY.md

@@ -0,0 +1,8 @@
+# Pages
+
+[Index of Contents](title-page.md)
+----
+[Also Used At](also-used-at.md)
+[Architecture](architecture.md)
+[Overview](overview.md)
+[Repo Configuration](repo-configuration.md)

src/also-used-at.md

@@ -0,0 +1,3 @@
+# Also Used At
+
+- https://gitnet.page/ (https://gitnet.fr)

src/architecture.md

@@ -0,0 +1,24 @@
+# Architecture
+
+| package | description | depends on |
+|--|--|--|
+| main.go | init app in cmd/* | cmd, server/version |
+| cmd | start app, read config from args and env vars, validate args | server/{cache,certificates,gitea,handler}, github.com/urfave/cli
+| server/cache | create key/value cache based con settings | github.com/OrlovEvgeny/go-mcache |
+| server/database | create cert database witch persist certs for main and custom domain | github.com/go-acme/lego/v4/{certcrypto,certificate}, xorm.io/xorm |
+| server/certificates | request, mock, manage certificates via acme | server/{cache,context,database,dns,gitea,utils}, github.com/go-acme/lego/v4/{registration,providers/dns,upstream} |
+| server/context | smal wrapper for net/http response and requests | server/utils |
+| server/dns | handle dns lookups for custom domains | server/cache |
+| server/gitea | handle all gitea-backend calls and it's caching | server/cache, code.gitea.io/sdk/gitea |
+| server/handler | take all http(s) requests and determine how they need to be threated (default pages, custom domain, ...). it does however not serve stuff | html,server/{cache,context,dns,gitea,upstream,version} |
+| server/upstream | try to serve stuff based on args from handler | html,server/{cache,context,gitea} |
+| server/utils | general purpose functions | |
+| server/version | just store the program version | |
+
+## Concepts
+
+Each package creates a client that others can use e.g.:
+
+- server/gitea -> GiteaClient
+- server/certificates -> AcmeClient
+- ...

src/overview.md

@@ -0,0 +1,40 @@
+# Codeberg Pages
+
+Codeberg Pages users can easily deploy static websites on Codeberg using Git.
+
+The Codeberg Pages server responds to four different URLs:
+
+- https://raw.codeberg.org/username/reponame/: raw content, uses correct MIME types (HTML is forbidden though) & is accessible with CORS.
+- https://username.codeberg.page: user page, points the default branch of a user's or organization's pages repository
+- https://username.codeberg.page/reponame/: repo page, points to the pages branch of the repository
+- https://example.org: custom domain, points to a repo of choice as outlined below
+
+In all cases append a branch is done using an @ (e.g.
+https://username.codeberg.page/@develop/README.md).
+
+## Custom Domains
+
+WARNING: Custom domains aren't fully tested yet and users may run into Let's
+Encrypt Rate Limits for their domains. It is recommended to try it out on an
+unused subdomain first so as to complete one request, and if it fails, contact the
+maintainers who can
+check what the problem is. A better process for such errors is being worked on.
+
+Currently known pitfalls:
+
+- Either not have a `CAA` record, or explicitly allow letsencrypt.org
+
+For custom domains, two things are required:
+
+- A `.domains` file in the repository (in the branch in question), containing a list of domains that shall be usable to access that repository:
+    - One domain per line, leaving lines empty and comment out lines with #.
+    - All domains (including *.codeberg.page) will be redirected to the first domain in that file.
+
+- A `CNAME` record pointing to one of the following targets:
+    - username.codeberg.page → https://username.codeberg.page
+    - reponame.username.codeberg.page → https://username.codeberg.page/reponame/
+    - branchname.reponame.username.codeberg.page → https://username.codeberg.page/reponame/@branchname/
+
+If a `CNAME` record cannot be used to configure the target (e.g. for a zone
+root), a A/AAAA/ALIAS record to codeberg.page with an additional TXT record
+for the target (just as shown above for `CNAME` records) can be used.

src/repo-configuration.md

@@ -0,0 +1,3 @@
+# .domains
+
+List allowed custom domains, first entry is default and all other domains will be redirected to it.

src/title-page.md

@@ -0,0 +1,6 @@
+## Index of Contents
+
+[Also Used At](also-used-at.md)\
+[Architecture](architecture.md)\
+[Overview](overview.md)\
+[Repo Configuration](repo-configuration.md)