Merge pull request #2 from UNIVERSE-HPC/main

Update from upstream

.github/workflows/lint.yaml

@@ -1,12 +1,14 @@
-name: Check Markdown and Front Matter
+name: Lint markdown files
 
 on:
   push:
+    branches:
+      - main
     paths:
-      - '**/*.md'
+      - "**/*.md"
   pull_request:
     paths:
-      - '**/*.md'
+      - "**/*.md"
 
 jobs:
   check-markdown-yaml:
@@ -19,4 +21,35 @@ jobs:
       - name: Run Front Matter Linting
         uses: alasdairwilson/front-matter-lint@main
         with:
-          directory: '.'
+          directory: "."
+
+  lint-python-codeblocks:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Lint Python Code Blocks in Markdown
+        uses: OxfordRSE/lint-md-codeblocks@main
+        with:
+          directory: "."
+          language: "python"
+
+  lint-markdown:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: "20"
+
+      - name: Install markdownlint-cli
+        run: npm install -g markdownlint-cli
+
+      - name: Lint Markdown files
+        run: markdownlint '**/*.md' --ignore '*/*/slides/*' --ignore README.md

.gitignore

@@ -1,4 +1,5 @@
 
 .idea/
 .DS_Store
-*.code-workspace
+*.code-workspace
+.vscode

.markdownlint.yaml

@@ -0,0 +1,7 @@
+default: true
+MD041: false # Ignore first line heading warnings (because we title set in front matters)
+MD013: false # Ignore line length warnings
+MD033:
+  allowed_elements: ["kbd"]
+MD024:
+  siblings_only: true

CONTRIBUTING.md

@@ -1,6 +1,7 @@
 # Contributing guidelines
 
 To contribute new material, or update existing material please:
+
   1. Create an issue on this repo with a description of the proposed change
   2. Fork the repo and create a new branch. Add commits to your branch in your own fork with the changes. Please provide the issue number in each commit message, e.g. a commit message for issue number 5 might be "#5 added version control material"
   3. When you are ready, open a pull request to merge your new commits to the `main` branch of this repo.
@@ -13,7 +14,7 @@ It is useful to see how your change is rendered into a webpage using the [Gutenb
 
 The file structure in this repo defines the structure of the generated material, there are three levels of subdirectories, each with their own `index.md` file, which contains metadata:
 
-```
+```text
 - index.md
 - [theme.id]
   - index.md
@@ -34,38 +35,39 @@ Each folder has an `index.md` with metadata for that theme/course/section.
 ### Material metadata
 
 The top level `index.md` has a yaml block containing the keys:
-  - `id`, a string with a unique id for this material
-  - `name`, a string with the material title
-  - `themes`, an array of folder names of the themes within this material
+
+- `id`, a string with a unique id for this material
+- `name`, a string with the material title
+- `themes`, an array of folder names of the themes within this material
 
 The theme names correspond to subfolders in this repo. The rest of the content of this file is markdown formatted content with a top-level description of the material.
 
 ### Theme metadata
 
 The theme level `index.md` has a yaml block containing the keys:
 
-  - `id`, a string with a unique id (unique within this material) for this theme
-  - `name`, a string with the theme title
-  - `courses`, an array of folder names of the courses within this material
+- `id`, a string with a unique id (unique within this material) for this theme
+- `name`, a string with the theme title
+- `courses`, an array of folder names of the courses within this material
 
 The course names correspond to subfolders in this theme folder. The rest of the content of this file is markdown formatted content with a top-level description of the theme.
 
 ### Course metadata
 
 The course level `index.md` has a yaml block containing the keys:
 
-  - `id`, a string with a unique id (unique within this theme) for this theme
-  - `name`, a string with the theme title
-  - `files`, an array of filenames of the sections within this material
+- `id`, a string with a unique id (unique within this theme) for this theme
+- `name`, a string with the theme title
+- `files`, an array of filenames of the sections within this material
 
 The file names correspond to markdown files in this course folder. The rest of the content of this file is markdown formatted content with a top-level description of the course.
 
 ### Section metadata
 
 Each section markdown file has a yaml block containing the keys. Note that the `id` of each section is implicitly defined from the filename, so a section filename `array.md` would have an id `array`.
 
-  - `name`, a string with the section title
-  - `dependsOn`, an array of identifiers indicating the pre-requisite sections/courses/themes for this section
+- `name`, a string with the section title
+- `dependsOn`, an array of identifiers indicating the pre-requisite sections/courses/themes for this section
 
 Each entry in `dependsOn` indicates a course dependency using
 `<theme.id>.<course.id>` or a section dependency using
@@ -115,7 +117,6 @@ The id must be unique within this particular section, and the title is any strin
 The solution directive produces a section that is initially hidden, but which a
 user can click to display. It can be written using the following syntax:
 
-
 ```pandoc
 :::solution
 
@@ -126,7 +127,6 @@ The answer is 42.
 
 Note that solutions can be nested within challenges by matching the number of colons:
 
-
 ```pandoc
 ::::challenge{id=big_question title="Hitchhikers question"}
 
@@ -141,10 +141,9 @@ The answer is 42.
 
 ### Callout directive
 
-The callout directive produces a highlighted and bordered block of markdown content. It 
+The callout directive produces a highlighted and bordered block of markdown content. It
 can be written using the following syntax:
 
-
 ```pandoc
 :::callout
 
@@ -153,7 +152,9 @@ be found on [the series Wikipedia entry](https://en.wikipedia.org/wiki/The_Hitch
 
 :::
 ```
-Different variants/flavours of callout are available by using the syntax 
+
+Different variants/flavours of callout are available by using the syntax
+
 ```pandoc
 :::callout{variant="variant"}
 Text
@@ -165,19 +166,25 @@ Variants available are "danger", "warning", "tip", "discussion", "note" and "key
 ![image](https://private-user-images.githubusercontent.com/60351846/301895586-343ade2a-0c4e-4f20-9559-8e3a4986a523.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MTQxMjkxMjcsIm5iZiI6MTcxNDEyODgyNywicGF0aCI6Ii82MDM1MTg0Ni8zMDE4OTU1ODYtMzQzYWRlMmEtMGM0ZS00ZjIwLTk1NTktOGUzYTQ5ODZhNTIzLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDA0MjYlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQwNDI2VDEwNTM0N1omWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPThjYjRmMGVkYTJmNWRmNTZkZWQwYWUzMzI0MTg0N2I0M2Q4ZDBkYWJlMmMwOWU3MWNmYTkzMTdiYzFmZGRhZjAmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0JmFjdG9yX2lkPTAma2V5X2lkPTAmcmVwb19pZD0wIn0.I4hgqTxWYcVN9TXzcFjDcyxotBrq_-o0TFWuVlJXW14)
 
 #### Danger
+
 Used to inform students to be aware that there is a danger that they could break their development environment or lose data if an action is not performed correctly.
 
 #### Warning
+
 Used to warn students that they should be careful when performing a task in case there is a risk of a breaking change or issue arising that is less serious than something in the "danger" category or precautions to take to ensure good practice.
 
 #### Tip
+
 Used to inform students of a useful tip that may help them complete a task or help them in a wider context.
 
 #### Discussion
+
 Used to introduce a discussion topics as part of a training session or as a thinking point if completing the training individually, these help students better understand a concept.
 
 #### Note
+
 Used to highlight additional information that the student may wat to bear in mind when completing a task or thinking about a topic.
 
 #### Key Points
+
 Used to summarise the most essential or critical information in a topic. These can be takeaways or highlights that students should focus on.

README.md

@@ -1,4 +1,5 @@
 # About
+
 This repository contains course materials that have been developed or adapted as part of the [UNIVERSE-HPC project](http://www.universe-hpc.ac.uk/).
 
 If you are interested in working through the course materials **as a learner or instructor**, please do so through the [Gutenberg platform](https://train.oxrse.uk/material).
@@ -8,6 +9,7 @@ If you are interested in **contributing** material to this repository, please se
 If you are interested in contributing to the Gutenberg web application, please do so [here](https://github.com/OxfordRSE/gutenberg)
 
 ## License
+
 This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
 This means that you are free to share and adapt the materials in this repository, as long as you provide attribution to the authors.
 You can read the full terms in the [LICENSE file](LICENSE).