From cf9b42923540dd16586439c2b5a54b96982d90ac Mon Sep 17 00:00:00 2001
From: "Hahn Axel (hahn)" <axel.hahn@iml.unibe.ch>
Date: Thu, 14 Apr 2022 16:04:22 +0200
Subject: [PATCH] update docs
---
docs/10_Features.md | 7 ++
docs/20_Configuration.md | 77 ++++++++++++++++++
docs/30_Installation.md | 21 +++++
docs/_index.md | 108 -------------------------
docs/config.json | 21 +++++
docs/style.css | 165 +++++++++++++++++++++++++++++++++++++++
readme.md | 2 +-
7 files changed, 292 insertions(+), 109 deletions(-)
create mode 100644 docs/10_Features.md
create mode 100644 docs/20_Configuration.md
create mode 100644 docs/30_Installation.md
create mode 100644 docs/config.json
create mode 100644 docs/style.css
diff --git a/docs/10_Features.md b/docs/10_Features.md
new file mode 100644
index 0000000..57c07ba
--- /dev/null
+++ b/docs/10_Features.md
@@ -0,0 +1,7 @@
+# Features #
+
+* handle Redirects with strings or regex
+* one config file per handled domain
+* aliases can be defined to handle same redirects
+* optional debugging (will be written into http reponse header)
+* admin to list and filter all existing domains and redirects
diff --git a/docs/20_Configuration.md b/docs/20_Configuration.md
new file mode 100644
index 0000000..4926e55
--- /dev/null
+++ b/docs/20_Configuration.md
@@ -0,0 +1,77 @@
+
+# Configuration #
+
+In the config folder are json files. Copy the dist files to the same filename without ".dist"
+
+* redirects_[FQDN].json
+* aliases.json
+
+## Redirects ##
+
+There are 2 required sections to define redirects:
+
+* direct
+* regex
+
+The section "direct" will be scanned first and has priority.
+The json will be read into a hash ... if you define a direct rule twice then
+the last rule will win.
+
+If no direct rule matches the regex section will be scanned. Winner is the
+first matching regex.
+
+If no rule matches a 404 will be shown.
+
+Hint: if you set regex ".*" as last entry it works as a catchall for unmatched
+requests and you can define a default redirect target instead of showing a 404.
+
+Both redirect section contain a redirect definition
+
+* code - http status code for redirection
+* target - target url of the redirect
+
+Status codes
+
+* 301 => 'Moved Permanently'; the url is outdated
+* 307 => 'Temporary Redirect'; the url is valid
+* 308 => 'Permanent Redirect'; the url is outdated
+
+Suggestion for redirection lifecycle:
+
+* an active redirect (i.e. a campaign) use code 307
+* if the redirect has finished its life, switch the code to 308 or 301.
+* remove the redirect (which results into 404)
+
+Example:
+
+```json
+{
+ "direct":{
+ "heise": {"code": 307, "target": "https://www.heise.de" }
+ },
+
+ "regex":{
+ "^$": {"code": 307, "target": "https://www.iml.unibe.ch" },
+ "^ax.l.*": {"code": 307, "target": "https://www.axel-hahn.de" }
+ }
+}
+```
+
+## Server aliases ##
+
+If you have multiple domains with the same rules you can define aliases.
+
+Example:
+
+```json
+{
+ "www.example.com": "example.com",
+ "zzz-domainname": "existing-host-with-redirect-config"
+}
+```
+
+The key is the name of the alias. The value is a domain for that was written a
+redirect_[hostname].json already.
+
+The existance of a redirect config has higher priority than an entry in the
+aliases config.
diff --git a/docs/30_Installation.md b/docs/30_Installation.md
new file mode 100644
index 0000000..b186704
--- /dev/null
+++ b/docs/30_Installation.md
@@ -0,0 +1,21 @@
+# Installation #
+
+Extract archive 1 level above webroot. The document root of the web must point
+to the public_html directory. The config folder is outside the webroot.
+
+Redirect all requests to the index.php. Activate the .htaccess or (better)
+add the config of the htaccess file to the vhost config.
+
+```text
+RewriteEngine On
+RewriteBase /
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule ^.*$ /index.php [L]
+```
+
+In the DNS point all hostnames with redirects only to this server (i.e. with
+a CNAME).
+
+If you don't have a single vhost in the webserver then additionally add the
+domains to "catch" as ServerAlias.
diff --git a/docs/_index.md b/docs/_index.md
index 3d56d14..419f8df 100644
--- a/docs/_index.md
+++ b/docs/_index.md
@@ -11,111 +11,3 @@ License: GNUP GPL 3.0
* PHP 7+
* Webserver (docs describe usage for Apache httpd)
-
-## Installation ##
-
-Extract archive 1 level above webroot. The document root of the web must point
-to the public_html directory. The config folder is outside the webroot.
-
-Redirect all requests to the index.php. Activate the .htaccess or (better)
-add the config of the htaccess file to the vhost config.
-
-```text
-RewriteEngine On
-RewriteBase /
-RewriteCond %{REQUEST_FILENAME} !-f
-RewriteCond %{REQUEST_FILENAME} !-d
-RewriteRule ^.*$ /index.php [L]
-```
-
-In the DNS point all hostnames with redirects only to this server (i.e. with
-a CNAME).
-
-If you don't have a single vhost in the webserver then additionally add the
-domains to "catch" as ServerAlias.
-
-## Configuration ##
-
-In the config folder are json files. Copy the dist files to the same filename without ".dist"
-
-* redirects_[FQDN].json
-* aliases.json
-
-### Redirects ###
-
-There are 2 required sections to define redirects:
-
-* direct
-* regex
-
-The section "direct" will be scanned first and has priority.
-The json will be read into a hash ... if you define a direct rule twice then
-the last rule will win.
-
-If no direct rule matches the regex section will be scanned. Winner is the
-first matching regex.
-
-If no rule matches a 404 will be shown.
-
-Hint: if you set regex ".*" as last entry it works as a catchall for unmatched
-requests and you can define a default redirect target instead of showing a 404.
-
-Both redirect section contain a redirect definition
-
-* code - http status code for redirection
-* target - target url of the redirect
-
-Status codes
-
-* 301 => 'Moved Permanently'; the url is outdated
-* 307 => 'Temporary Redirect'; the url is valid
-* 308 => 'Permanent Redirect'; the url is outdated
-
-Suggestion for redirection lifecycle:
-
-* an active redirect (i.e. a campaign) use code 307
-* if the redirect has finished its life, switch the code to 308 or 301.
-* remove the redirect (which results into 404)
-
-Example:
-
-```json
-{
- "direct":{
- "heise": {"code": 307, "target": "https://www.heise.de" }
- },
-
- "regex":{
- "^$": {"code": 307, "target": "https://www.iml.unibe.ch" },
- "^ax.l.*": {"code": 307, "target": "https://www.axel-hahn.de" }
- }
-}
-```
-
-### Server aliases ###
-
-If you have multiple domains with the same rules you can define aliases.
-
-Example:
-
-```json
-{
- "www.example.com": "example.com",
- "zzz-domainname": "existing-host-with-redirect-config"
-}
-```
-
-The key is the name of the alias. The value is a domain for that was written a
-redirect_[hostname].json already.
-
-The existance of a redirect config has higher priority than an entry in the
-aliases config.
-
-## Ideas ##
-
-The current functionality is available with rewrite rules. Maybe in future
-one of these features could be implmeneted:
-
-* track request before redirecting to generate a statistic
-* lifecycle of campaign short urls
-* admin interface / just a viewer for all definitions
diff --git a/docs/config.json b/docs/config.json
new file mode 100644
index 0000000..0f1bdb2
--- /dev/null
+++ b/docs/config.json
@@ -0,0 +1,21 @@
+{
+ "title": "IML Redirect",
+ "author": "Axel Hahn",
+ "tagline": "Redirect urls of any domain that points here.",
+ "ignore": {
+ "files": ["30_PHP-client/Plugins/Checks/_skeleton.md"],
+ "folders": ["99_Not_Ready"]
+ },
+ "html": {
+ "auto_toc": true,
+ "auto_landing": false,
+ "date_modified": false,
+ "jump_buttons": true,
+ "edit_on_github_": "iml-it/appmonitor/tree/master/docs",
+ "links": {
+ "Git Repo": "https://git-repo.iml.unibe.ch/iml-open-source/redirect-handler/"
+ },
+ "theme": "daux-blue",
+ "search": true
+ }
+}
\ No newline at end of file
diff --git a/docs/style.css b/docs/style.css
new file mode 100644
index 0000000..02b2415
--- /dev/null
+++ b/docs/style.css
@@ -0,0 +1,165 @@
+/*
+
+ patch css elements of daux.io blue theme
+
+*/
+
+
+/* ---------- vars ---------- */
+
+:root{
+
+ /* background colors */
+ --bg:none;
+ --bg-body: #fff;
+ --bg-navlinkactive:#f4f4f4;
+ --bg-navlinkactive: linear-gradient(-90deg,rgba(0,0,0,0), rgba(40,60,80,0.05) 30%);
+ --bg-pre:#f8f8f8;
+ --bg-toc: #fff;
+
+ /* foreground colors */
+ --color: #234;
+ --navlinkactive:#f33;
+ --title: #aaa;
+
+ --link:#12a;
+ --toclink:rgba(40,60,80,0.8);
+
+ --h1: rgba(40,60,80,0.8);
+ --h1-bottom: 1px solid rgba(40,60,80,0.1);
+ --h2: rgba(40,60,80,0.5);
+ --h3: rgba(40,60,80,0.3);
+
+}
+
+/* ---------- tags ---------- */
+
+body, *{color: var(--color); }
+body{background: var(--bg-body);}
+
+
+a{color: var(--link);}
+a:hover{opacity: 0.7;}
+
+h1>a{ color:var(--title);}
+_h1:nth-child(1){position: fixed; background: var(--bg); box-shadow: 0 0 1em #ccc; padding: 0 1em}
+h1:nth-child(1)>a{ color:var(--navlinkactive); }
+
+.s-content h1{color: var(--h1); font-size: 200%; font-weight:bold; margin-top: 2em; border-bottom: var(--h1-bottom);}
+.s-content h2{color: var(--h2); font-size: 160%; }
+.s-content h3{color: var(--h3); font-size: 140%; }
+.s-content h4{margin: 0; font-size: 100%; text-align: center; background-color: rgba(0,0,0,0.05);padding: 0.3em;}
+
+.s-content pre{
+ background: var(--bg-pre);
+}
+
+/* ---------- classes ---------- */
+
+.required{color:#a42;}
+.optional{color:#888;}
+
+
+/* ----- top left */
+.Brand,
+.Columns__left {
+ background: var(--bg);
+ border-right: 0px solid #e7e7e9;
+ color: var(--color);
+}
+.Brand{font-size: 200%;
+ background_: linear-gradient(-10deg,#fff 50%, #ddd);
+ background: var(--bg);
+}
+.Columns__right__content {
+ background: var(--bg);
+}
+
+/* ----- Navi left */
+
+.Nav a:hover{
+ background: none;
+ color: var(--navlinkactive) !important;
+}
+
+.Nav__item--active {
+ border-right_: 0.3em solid var(--navlinkactive);
+}
+.Nav__item--active > a{
+ background: var(--bg-navlinkactive);
+ color: var(--navlinkactive);
+}
+.Nav .Nav .Nav__item--active a {
+ color: var(--navlinkactive);
+}
+.Nav .Nav .Nav__item a {
+ opacity: 1;
+}
+.Nav__item--open > a {
+ background-color: var(--bg);
+}
+
+.Nav a[href*="__Welcome"]{
+ background: url("/icons/house.png") no-repeat 10px 4px ;
+ padding-left: 40px;
+}
+.Nav a[href*="__How_does_it_work"]{
+ background: url("/icons/light-bulb.png") no-repeat 10px 4px ;
+ padding-left: 40px;
+}
+
+
+
+
+/* ---------- classes ---------- */
+
+/* FIX smaller fnt size in tables */
+.s-content table {
+ font-size: 1em;
+}
+
+
+/* TOC */
+@media(min-width:1700px){
+ .TableOfContentsContainer{
+ position: fixed;
+ right: 2em;
+ top: 1em;
+ }
+}
+
+.TableOfContentsContainer{
+ border-top-left-radius: 1em;
+ background-color: var(--bg-toc);
+ border-left: 2px solid rgba(0,0,0,0.05);
+ padding: 0em;
+}
+.TableOfContentsContainer__content {
+
+ border: none;
+ font-size: 0.5em;
+
+}
+ul.TableOfContents ul{
+ list-style-type: none;
+ padding-left: 1em;
+}
+.TableOfContentsContainer a{ color:var(--toclink);}
+
+.TableOfContentsContainer__content > .TableOfContents > li + li {
+ border-top: none;
+}
+.TableOfContentsContainer__content > .TableOfContents > li {
+ border-bottom: 1px dashed #ddd;
+}
+
+/* pager - prev .. next */
+.s-content{
+ margin-bottom: 6em;
+}
+.Pager{
+ border-top: 1px dashed #aaa; margin: 0; padding: 1em;
+}
+.Pager a{
+ color:var(--navlinkactive);
+}
diff --git a/readme.md b/readme.md
index 1223bd5..d59789d 100644
--- a/readme.md
+++ b/readme.md
@@ -7,4 +7,4 @@ Author: Axel Hahn; Institute for Medical Education; University of Bern
License: GNUP GPL 3.0
-see [docs](./docs)
+See the [docs](./docs)
--
GitLab