Adding additional docs

.github/workflows/docs.yml

@@ -18,7 +18,8 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install mkdocs markdown-callouts mkdocs-material
+        pip install mkdocs
+        pip3 install $(mkdocs get-deps)
         sudo apt-get update
         sudo apt-get install -y lftp
 

doc/README.md

@@ -1,43 +1,20 @@
-# Hashtopolis
+# Documentation Development
 
-> [!CAUTION]
-> This is a new page that will be used for documentation. It is work in progress, so use with care!
+This page describes howto use the documentation locally or how to contribute to it.
 
+## Setup
 
+1. Make sure you are in the root of the server project and setup a virtual enviroment there.
+2. Install mkdocs
+3. Install required mkdocs extensions
+4. Start the server
+5. Browse to http://127.0.0.1:8000
 
-## Hashtopolis Protocol
-
-The current up-to-date protocol version which Hashtopolis uses to communicate with clients is contained in the `protocol.pdf` file. 
-The documentation for the User API can be found in `user-api/user-api.pdf`, listing all functions which can be called.
-
-## Generic Crackers
-
-Custom crackers which should be able to get distributed with Hashtopolis need to fulfill some minimal requirements as command line options. Shown here with the help function of a generic example implementation (which is available [here](https://github.com/hashtopolis/generic-cracker)):
-
-```
-cracker.exe [options] action
-Generic Cracker compatible with Hashtopolis
-
-Options:
-  -m, --mask <mask>                   Use mask for attack
-  -w, --wordlist <wordlist>           Use wordlist for attack
-  -a, --attacked-hashlist <hashlist>  Hashlist to attack
-  -s, --skip <skip>                   Keyspace to skip at the beginning
-  -l, --length <length>               Length of the keyspace to run
-  --timeout <seconds>                 Stop cracking process after fixed amount of time
-
-Arguments:
-  action                              Action to execute ('keyspace' or 'crack')
-```
-
-`-m` and `-w` are used to specify the type of attack, but these options are not mandatory to look like this.
-
-Please note that not all Hashtopolis clients are compatible with generic cracker binaries (check their README) and if there are slight differences in the cracker compared to the generic requirements there might be changes required on the client to adapt to another handling schema.
-
-## Slow Algorithms
-
-To extract all Hashcat modes which are flagged as slow hashes, following command can be run inside the hashcat directory:
-
-```
-grep -Hr SLOW_HASH src/modules/ | cut -d: -f1 | sort | cut -d'.' -f1 | sed 's/src\/modules\/module_[0]\?//g'
+``` bash
+cd hashtopolis
+virtualenv venv
+source venv/bin/activate
+pip3 install mkdocs
+pip3 install $(mkdocs get-deps)
+mkdocs server
 ```

doc/advanced.md

@@ -0,0 +1,33 @@
+# Advanced usage
+
+## Generic Crackers
+
+Custom crackers which should be able to get distributed with Hashtopolis need to fulfill some minimal requirements as command line options. Shown here with the help function of a generic example implementation (which is available [here](https://github.com/hashtopolis/generic-cracker)):
+
+```
+cracker.exe [options] action
+Generic Cracker compatible with Hashtopolis
+
+Options:
+  -m, --mask <mask>                   Use mask for attack
+  -w, --wordlist <wordlist>           Use wordlist for attack
+  -a, --attacked-hashlist <hashlist>  Hashlist to attack
+  -s, --skip <skip>                   Keyspace to skip at the beginning
+  -l, --length <length>               Length of the keyspace to run
+  --timeout <seconds>                 Stop cracking process after fixed amount of time
+
+Arguments:
+  action                              Action to execute ('keyspace' or 'crack')
+```
+
+`-m` and `-w` are used to specify the type of attack, but these options are not mandatory to look like this.
+
+Please note that not all Hashtopolis clients are compatible with generic cracker binaries (check their README) and if there are slight differences in the cracker compared to the generic requirements there might be changes required on the client to adapt to another handling schema.
+
+## Slow Algorithms
+
+To extract all Hashcat modes which are flagged as slow hashes, following command can be run inside the hashcat directory:
+
+```
+grep -Hr SLOW_HASH src/modules/ | cut -d: -f1 | sort | cut -d'.' -f1 | sed 's/src\/modules\/module_[0]\?//g'
+```

doc/index.md

@@ -0,0 +1,6 @@
+# Hashtopolis documentation
+
+> [!CAUTION]
+> This is the new documentation of Hashtopolis. It is work in progress, so use with care!
+
+You can find the old documentation still inside this folder, please check the [Hashtopolis Communication Protocol (V2)](protocol.pdf) docs. The user api documentation can be found here: [Hashtopolis User API (V1)](user-api/user-api.pdf).

mkdocs.yml

@@ -4,6 +4,7 @@ repo_url: https://github.com/hashtopolis/server
 docs_dir: doc
 theme:
   name: material
+  logo: assests/images/logo.png
 edit_uri: blob/docs/doc/ # Edit the URL to the static branch and folder
 markdown_extensions:
   - github-callouts # Add the ability of notes, warnings, etc.