Merge pull request #363 from ZeitOnline/docs

Docs: Migriere zu MkDocs
ZeitOnline · Oct 14, 2024 · 2617117 · 2617117
2 parents ca0ce28 + cf492c5
commit 2617117
Show file tree

Hide file tree

Showing 9 changed files with 45 additions and 230 deletions.
diff --git a/bin/docs b/bin/docs
@@ -0,0 +1,21 @@
+#!/bin/bash
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$DIR/.."
+zon_mkdocs_image="europe-west3-docker.pkg.dev/zeitonline-engineering/docker-zon/zon-mkdocs:latest"
+
+docker pull $zon_mkdocs_image
+
+COMMAND=${1:-html}
+case $COMMAND in
+    serve)
+        docker run --rm -it -p 8000:8000 -v ${PWD}:/docs $zon_mkdocs_image
+    ;;
+    html)
+        docker run --rm -v ${PWD}:/docs $zon_mkdocs_image build --site-dir public
+    ;;
+    *)
+        echo "Unrecognized command: $COMMAND"
+        exit 1
+    ;;
+esac
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/_build/.gitignore b/docs/_build/.gitignore
diff --git a/docs/application/i18n.md b/docs/application/i18n.md
@@ -1,8 +1,7 @@
 # Internationalization
 
-:::{note}
-The i18n Feature is currently not actively supported anymore - the workaround is to translate the texts using the theming mechanism, where you can replace tagged markup with translated versions.
-:::
+!!! note
+    The i18n Feature is currently not actively supported anymore - the workaround is to translate the texts using the theming mechanism, where you can replace tagged markup with translated versions.
 
 All user facing text of the `briefkasen` application are translated using a `gettext` messsage catalog. To customize and update these messages you must:
 

diff --git a/docs/compose.yaml b/docs/compose.yaml
diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/index.md b/docs/index.md
@@ -1,25 +1,17 @@
-```{include} overview.md
-```
+# ZEIT Online Briefkasten
 
-Deployment
+The `briefkasten` (German for letterbox) is a reasonably secure web application for submitting content anonymously.
 
-: This section contains all the information on how to install, configure and run your own instance of the briefkasten stack.
+It allows to upload attachments which are then sanitized of a number of meta-data which could compromise the submitters identity. Next, the sanitized files are encrypted via GPG and sent via email to a pre-configured list of recipients. The original (potentially 'dirty') files are then deleted from the file system of the server. Thus, neither should admins with access to the server be able to access any submissions, nor should any of the recipients have access to the unsanitized raw material.
 
-```{toctree}
-:maxdepth: 2
+Upon successful upload the submitter receives a unique URL with a token that he or she can use to access any replies the recipients may post. That reply is the only data persisted on the server.
 
-deployment/index
-deployment/monitoring
-```
+The implementation doesn't just contain the application itself but includes a complete deployment setup following what we believe to be best practices so that anybody should be able to host their own secure `briefkasten` with minimal setup pain.
 
-Application
+[Deployment](deployment/index.md)
 
-> This section contains information on the inner workings of the application and how to develop or extend it or how to create a custom theme for it.
+> This section contains all the information on how to install, configure and run your own instance of the briefkasten stack.
 
-```{toctree}
-:maxdepth: 2
+[Application](application/develop.md)
 
-application/develop
-application/workings
-application/i18n
-```
+> This section contains information on the inner workings of the application and how to develop or extend it or how to create a custom theme for it.
diff --git a/docs/overview.md b/docs/overview.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,13 @@
+INHERIT: /zon/common_config.yaml
+site_name: Briefkasten
+repo_url: https://github.com/ZeitOnline/briefkasten
+
+nav:
+    - index.md
+    - Deployment:
+        - deployment/index.md
+        - deployment/monitoring.md
+    - Application:
+        - application/develop.md
+        - application/workings.md
+        - application/i18n.md