Add conda environment and ci.yml for GitHub action

.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: ci
+on:
+  push:
+    branches:
+      - master
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.10
+      - run: pip install mkdocs-material
+      - run: pip install mkdocs-git-revision-date-plugin
+      - run: mkdocs gh-deploy --force

README.md

@@ -8,20 +8,43 @@ This documentation project makes use of
   * [MkDocs](https://www.mkdocs.org/)
   * [MkDocs Material Design Theme](https://squidfunk.github.io/mkdocs-material)
 
+To make changes and test it locally, you have to setup mkdocs-material and all other dependencies. We are delivering a conda environemnt file right within this repo. A possible installation scenario for macOS using Homebrew might look like:
+
+```
+# Install miniconda using Homebrew
+brew install --cask miniconda
+
+# Setup conda
+conda init "$(basename "${SHELL}")"
+# --> For changes to take effect, close and re-open your current shell <--
+
+# Fetch the documentation repository
+git clone https://github.com/hpc-unibe-ch/hpc-docs.git
+cd hpc-docs
+
+# Create and activate the environment
+conda create
+conda activate hpcdocs
+
+# Start the local mkdocs webserver that renders and displays all change instantly
+mkdocs serve
+```
+
 ## Contributions
 
 Everybody is invited to contribute to the doucmentation. If you find that certain topics
 are not sufficiently covered or difficult to understand, you can fork this repository,
 fix the respective part and then send us a pull request. Even for such small things like
 typos! Yes, really, we appreciate your effort!
 
-You can make our live easier when you ship logically selfcontained pull requests, which means:
+You can make our life easier when you ship logically selfcontained pull requests, which means:
 
   * one logical change per pull reuqest (typos or a new paragraph on topic X, another for topic Y)
   * squash multiple commits before starting the pull request
 
 Thanks you!
 
+
 ## License
 
 This work is licensed under the Creative Commons Attribution 3.0 Switzerland

environment.yml

@@ -0,0 +1,7 @@
+name: hpcdocs
+dependencies:
+  - python=3.10
+  - pip
+  - pip:
+      - mkdocs-material
+      - mkdocs-git-revision-date-plugin

mkdocs.yml

@@ -62,20 +62,14 @@ nav:
   - FAQ: general/faq.md
   - Hall of Fame: halloffame.md
   - Code of Conduct: code-of-conduct.md
-      #
-      #
-      #  - Home: index.md
-      #  - User Guide:
-      #    - Getting Started: user-guide/getting-started.md
-      #    - File Transfer: user-guide/file-transfer.md
-      #    - Job Management with Slurm:
+
 
 # Copyright footer
 copyright: 'Copyright © University of Bern, IT Service Office'
-# Social links at botoom right
+# Link to repo
 repo_name: 'hpc-unibe-ch/hpc-docs'
 repo_url: 'https://github.com/hpc-unibe-ch/hpc-docs'
-edit_uri: ''
+edit_uri: 'edit/main/docs'
 
 # Configuration
 theme:
@@ -84,24 +78,31 @@ theme:
 extra_css:
  - 'stylesheets/unibe.css'
 
+plugins:
+  - git-revision-date
+
 # See https://python-markdown.github.io/extensions/ and
 # See https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions#Bundles
 #     https://facelessuser.github.io/pymdown-extensions/
 markdown_extensions:
   - abbr
+  - admonition
+  - attr_list
   - def_list
   - footnotes
-  - tables
-  - admonition
   - codehilite:
       guess_lang: false
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
   - sane_lists
   - smarty
+  - tables
   - toc
-  - pymdownx.superfences
-  - attr_list
-
 
+# Social links bottom right
 extra:
   social:
     - icon: fontawesome/brands/github-alt