cleanup: codeblocks, links (#35)

* cleanup: codeblocks, links

* mkdocs: more codeblocks formatting

docs/services/bastion-vm.md

@@ -14,6 +14,8 @@ This VM is an ephemeral machine that can be placed on any nomad client that has
 
 It acts as the point of ingress for Aperture, with ISS and our [mordor](../hardware/network/mordor.md) allowing traffic to reach it's IP address externally. The VM is configured as a Nomad client itself, in the `ingress` node pool to ensure that only ingress-type allocations are placed there (like [traefik](./traefik.md)). Those services can proxy requests from the Bastion VM to internal services using consul's service DNS resolution, it's service mesh, or by plain IP and port.
 
+![Ingress Topology with Bastion VM](../res/ingress-topology.png)
+
 `cloud-init` is given a static address during the initialisation phase to configure the interface. This ensures that, even if it is replanned, it will be able to accept traffic.
 
 The base image that the VM uses is a Debian 12 qcow file. After all configuration was done, the size of the image is `~3.2GB`. The image can be used to create replicas of the ingress on other external IP addresses, creating more availability if needed.

docs/services/index.md

@@ -18,11 +18,23 @@ Here you will find a list of all the services Redbrick runs, along with some con
 
 In order to add a new service, you will need to edit the [docs](https://github.com/redbrick/docs) repository.
 
-Adding a new service is as easy as creating a new file in `docs/services/` with an appropriate name, and adding the reference to `mkdocs.yml` in the root of the repository.
+Adding a new service is as easy as creating a new file in [`docs/services/`](https://github.com/redbrick/docs/tree/master/docs/services) with an appropriate name, and the page will be automatically added to the navigation pane.
+
+Try to keep file names short and concise, limited to one word if possible and avoid using spaces.
 
 The style guide for a service file should be as follows:
 
 ```md
+---
+title: ServiceName
+author:
+  - username
+tags:
+  - relevant
+  - tags
+
+---
+
 # ServiceName - `username`
 
 Short description on how the service works and where it is running

docs/services/md.md

@@ -1,5 +1,5 @@
 ---
-title: HedgeDoc
+title: MD (HedgeDoc)
 author:
   - wizzdom
 tags:
@@ -20,21 +20,21 @@ The important points are as follows:
 
 - connecting to the database:
 
-```bash
+```hcl title="Nomad"
 CMD_DB_URL = "postgres://{{ key "hedgedoc/db/user" }}:{{ key "hedgedoc/db/password" }}@{{ env "NOMAD_ADDR_db" }}/{{ key "hedgedoc/db/name" }}"
 ```
 
 - disabling anonymous users and email signup:
 
-```bash
+```hcl title="Nomad"
 CMD_ALLOW_EMAIL_REGISTER = "false"
 CMD_ALLOW_ANONYMOUS      = "false"
 CMD_EMAIL                = "false"
 ```
 
 - LDAP configuration:
 
-```bash
+```hcl title="Nomad"
 CMD_LDAP_URL             = "{{ key "hedgedoc/ldap/url" }}"
 CMD_LDAP_SEARCHBASE      = "ou=accounts,o=redbrick"
 CMD_LDAP_SEARCHFILTER    = "{{`(uid={{username}})`}}"

docs/services/paste.md

@@ -22,21 +22,21 @@ The main points are as follows:
 
 - configure URL shortener ([`shlink`](shlink.md))
 
-```php
+```php title="conf.php"
 urlshortener = "https://s.rb.dcu.ie/rest/v1/short-urls/shorten?apiKey={{ key "privatebin/shlink/api" }}&format=txt&longUrl="
 ```
 
 - enable file upload, set file size limit and enable compression
 
-```php
+```php title="conf.php"
 fileupload = true
 sizelimit = 10485760
 compression = "zlib"
 ```
 
 - Connect to PostgreSQL database
 
-```php
+```php title="conf.php"
 [model]
 class = Database
 [model_options]

docs/services/socs.md

@@ -1,6 +1,11 @@
+---
+title: Socs using Redbrick Infrastructure
+---
+
 # Socs Using Redbrick Infrastructure
 
 - MPS/DCUfm - [`icecast`](icecast.md)
 - MPS/TheCollegeView - [TheCollegeView](https://thecollegeview.ie) - `wordpress`
 - DCU Style - [The Look](https://thelookonline.dcu.ie) - `wordpress`
 - DCU Solar Racing - [Solarracing.ie](https://solarracing.ie)
+- DCU Games Society - [`minecraft`](minecraft.md)

docs/services/user-vms.md

@@ -1,3 +1,14 @@
+---
+title: User VMs
+author:
+  - distro
+  - wizzdom
+tags:
+  - aperture
+  - nomad
+  - qemu
+---
+
 # User VMs
 
 User VMs are deployed on [`aperture`](../hardware/aperture/index.md) using [nomad](nomad.md)'s [QEMU driver](https://developer.hashicorp.com/nomad/docs/drivers/qemu). 
@@ -58,7 +69,7 @@ nomad alloc logs <alloc-id> | grep -E "ens3.*global" | cut -d "|" -f 4 | xargs
 
 The VMs are configured with cloud-init. Their docs are pretty good, so I won't repeat them here. The files can be served by any HTTP server, and the address is placed into the job file in the QEMU options.
 
-```hcl
+```hcl title="Nomad"
 ...
         args = [
           ...

docs/tags.md

@@ -1,3 +1,3 @@
 
 <!--Do not remove this file-->
-<!--This is required for mkdocs to generate a tags page-->
+<!--This is required for mkdocs to generate a tags page-->

mkdocs.yml

@@ -84,10 +84,16 @@ markdown_extensions:
   - pymdownx.tabbed
   - pymdownx.superfences
   - pymdownx.tilde
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span
       pygments_lang_class: true
+      auto_title: true
+      linenums: true
+      linenums_style: pymdownx-inline
+      anchor_linenums: true
   - toc:
       permalink: true