Dockerfile

@@ -1,4 +1,4 @@
-FROM squidfunk/mkdocs-material:9.4.14
+FROM squidfunk/mkdocs-material:9.5.7
 
 EXPOSE 8000
 
@@ -9,5 +9,6 @@ WORKDIR /docs
 RUN apk add --no-cache curl
 
 RUN pip install \
-  mkdocs-awesome-pages-plugin==2.9.1 \
-  mkdocs-material-extensions==1.1.1
+  mkdocs-material~=9.5.7 \
+  mkdocs-material-extensions~=1.1.1 \
+  mkdocs-awesome-pages-plugin~=2.9.1

docs/maintainers/index.md

@@ -1,8 +1,23 @@
 ---
-title: Maintainers guide
+title: Maintainers Guide
 ---
 
 Welcome to the maintainers guide! Maintainers are typically individuals who have a stake in building up and maintaining our digital configuration commons, the recipe configurations. Maintainers help keep recipes configurations up to date, respond to issues in a timely manner, help new users within the community and recruit new maintainers when possible.
 
-- [New maintainers tutorial](/maintainers/tutorial): If you want to package a recipe and/or become a maintainer, start here :rocket:
-- [Packaging handbook](/maintainers/handbook): One-stop shop for all you need to know to package recipes :package:
+<div class="grid cards" markdown>
+
+- __New maintainers tutorial__
+
+    If you want to package a recipe and/or become a maintainer, start here :rocket:
+
+    [Get Started](/maintainers/tutorial){ .md-button .md-button--primary }
+
+- __Packaging handbook__
+
+    One-stop shop for all you need to know to package recipes :package:
+
+    [Read Handbook](/maintainers/handbook){ .md-button .md-button--primary }
+
+</div>
+
+Maintainers are encouraged to submit documentation patches! Sharing is caring :sparkling_heart:

docs/operators/handbook.md

@@ -1,5 +1,5 @@
 ---
-title: Operations handbook
+title: Operators Handbook
 ---
 
 ## Understanding `~/.abra`

docs/operators/index.md

@@ -2,7 +2,22 @@
 title: Operators Guide
 ---
 
-Welcome to the operators guide! Operators are typically individuals, members of tech co-ops or collectives who provide services powered by Co-op Cloud. This documentation is meant to help new & experienced operators manage their deployments as well as provide a space for sharing tricks & tips for keeping things running smoothly. Operators are encouraged to submit documentation patches! Sharing is caring :sparkling_heart:
+Welcome to the operators guide! Operators are typically individuals, members of tech co-ops or collectives who provide services powered by Co-op Cloud. This documentation is meant to help new & experienced operators manage their deployments as well as provide a space for sharing tricks & tips for keeping things running smoothly.
 
-- [New operators tutorial](/operators/tutorial): If you want to become an operator, start here :rocket:
-- [Operations handbook](/operators/handbook): One-stop shop for all you need to know to manage a deployment :ribbon:
+<div class="grid cards" markdown>
+
+- __New Operators Tutorial__
+
+    If you want to become an operator, start your journey here :rocket:
+
+    [Get started](tutorial.md){ .md-button .md-button--primary }
+
+- __Operators Handbook__
+
+    One-stop shop for all you need to know to manage a deployment :ribbon:
+
+    [Read Handbook](handbook.md){ .md-button .md-button--primary }
+
+</div>
+
+Operators are encouraged to submit documentation patches! Sharing is caring :sparkling_heart:

docs/operators/tutorial.md

@@ -1,5 +1,5 @@
 ---
-title: New operators tutorial
+title: New Operators Tutorial
 ---
 
 ## The moving parts

docs/organisers/index.md

@@ -4,6 +4,20 @@ title: Organisers Guide
 
 Welcome to the organisers guide! Organisers are folks who focus on the social work in the project. Speaking for the project at talks, helping new tech co-ops & collectives join, keeping an eye out for funding opportunities, seeing what things come up in the community chats, etc. It's important work.
 
-We're still working out what it looks like to do this kind of work in the project. If you like the idea of this kinda of work and/or are already doing it, please send patches to improve this documentation :rocket:
+<div class="grid cards" markdown>
 
-- [Organising handbook](/organisers/handbook): One-stop shop for all you need to know to organise in the community :sparkles:
+- __Organisers handbook__
+
+    One-stop shop for all you need to know to organise in the community :sparkles:
+
+    [Read Handbook](/organisers/handbook){ .md-button .md-button--primary }
+
+- __Say Hello First__
+
+    If you like what you see, but are not sure how to best contribute :speech_left:
+
+    [Get In Touch](/get-involved/){ .md-button .md-button--primary }
+
+</div>
+
+We're still working out what it looks like to do this kind of work in the project. If you like the idea of this kinda of work and/or are already doing it, please send patches to improve this documentation :rocket:

docs/styles/extra.css

@@ -4,6 +4,14 @@
   --md-primary-fg-color--dark: #ee4a33;
 }
 
+/* Button styling tweaks */
+
+.md-button {
+  margin: .25em !important;
+  padding: .15em .6em !important;
+  font-size: .85em !important;
+}
+
 /* Navbar styling tweaks */
 
 .md-search__form {

mkdocs.yml

@@ -26,20 +26,28 @@ theme:
 copyright: Copyleft 2023 Co-op Cloud
 
 markdown_extensions:
-  - meta
   - admonition
+  - attr_list
   - codehilite:
       guess_lang: false
+  - def_list
+  - footnotes
+  - md_in_html
+  - meta
   - toc:
       permalink: true
-  - attr_list
-  - pymdownx.tabbed
-  - pymdownx.superfences
-  - pymdownx.tilde
-  - pymdownx.magiclink
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.details
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.magiclink
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tabbed
+  - pymdownx.tilde
 
 nav:
   - "Introduction":

requirements.txt

@@ -1,4 +1,15 @@
+markdown~=3.2
+
+mkdocs~=1.5.3
+mkdocs-material~=9.5.7
+mkdocs-material-extensions~=1.3.1
 mkdocs-awesome-pages-plugin==2.9.2
-mkdocs-material-extensions==1.3.1
-mkdocs-material==9.4.14
-mkdocs==1.5.3
+pygments~=2.16
+pymdown-extensions~=10.2
+
+# Requirements for plugins
+babel~=2.10
+colorama~=0.4
+paginate~=0.5
+regex>=2022.4
+requests~=2.26