Merge pull request #406 from NLeSC/automatic-formatting

Enable automatic formatting of the guide

.github/dependabot.yml

@@ -3,7 +3,6 @@
 
 version: 2
 updates:
-
   # Set update schedule for GitHub Actions
   - package-ecosystem: "github-actions"
     directory: "/"

.github/workflows/link-checker-pr.yml

@@ -13,9 +13,9 @@ jobs:
         with:
           # Avoid using single or double quotes for multiline patterns
           files: |
-             **.md
+            **.md
           matrix: true
-  
+
   linkChecker:
     runs-on: ubuntu-latest
     needs: changedFiles

.github/workflows/link-checker.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - main
   schedule:
-    - cron: '0 4 * * *'  
+    - cron: "0 4 * * *"
 jobs:
   linkChecker:
     runs-on: ubuntu-latest

.github/workflows/pdf.yml

@@ -16,7 +16,7 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: "20"
 
       - name: Install uploader
         run: npm install @iomeg/zenodo-upload
@@ -33,7 +33,7 @@ jobs:
             --user $(id -u):$(id -g) \
             -e "PDF_OUTPUT_NAME=guide-nlesc.pdf" \
             ghcr.io/kernoeb/docker-docsify-pdf:latest
-        
+
       - name: Upload PDF as an artifact
         if: always()
         uses: actions/upload-artifact@v4

.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.4.2
+    hooks:
+      - id: prettier

CITATION.cff

@@ -109,7 +109,7 @@ authors:
   - affiliation: "Netherlands eScience Center"
     family-names: Zapata
     given-names: Felipe
-    orcid:  "https://orcid.org/0000-0001-8286-677X"
+    orcid: "https://orcid.org/0000-0001-8286-677X"
   - affiliation: "Netherlands eScience Center"
     family-names: Bakker
     given-names: Tom

CONTRIBUTING.md

@@ -1,12 +1,12 @@
 # Contributing to this Guide
+
 - [Who? You!](#who_you)
 - [Audience](#audience)
 - [Scope](#scope)
 - [How?](#how)
 - [Technical details (docsify)](#technical-details)
 - [Zen of the Guide](#zen-of-the-guide)
 
-
 # Who? You!
 
 This guide is primarily written by the Research Software Engineers at the Netherlands eScience Center.
@@ -16,12 +16,13 @@ Contributions by anyone (also outside the Center) are most welcome!
 
 While everybody is encouraged to contribute where they can, we appoint maintainers for specific pages to regularly keep things up to date and think along with contributors.
 To see who is responsible for which part of the guide see the maintainer listed at the top of a page.
-If you are interested in becoming a chapter owner for a page that is listed as *unmaintained*, please open a pull request to add your name instead of *unmaintained*.
+If you are interested in becoming a chapter owner for a page that is listed as _unmaintained_, please open a pull request to add your name instead of _unmaintained_.
 
 ## Editorial board
 
 The editors make sure content is in line with [the scope](#scope), that it is maintainable and that it is maintained.
 In practice they will:
+
 - track, lead towards satisfactory conclusion of and when necessary (in case of disagreement) decide on issues, discussions and pull requests,
 - flag content that needs to be updated or removed,
 - ask for input from page maintainers or other contributors,
@@ -30,21 +31,20 @@ In practice they will:
 and do any other regular editing tasks.
 
 Currently the team consists of:
+
 - Bouwe Andela [@bouweandela](https://github.com/bouweandela) (research software engineer)
 - Carlos Martínez Ortiz [@c-martinez](https://github.com/c-martinez) (community manager)
 - Patrick Bos [@egpbos](https://github.com/egpbos) (technology lead)
 
-
-
 # Audience
 
 Our eScience Center _RSEs_ are the prototypical audience members, in particular those starting out in some unfamiliar area of technology.
 Some characteristics include:
+
 - They are interested in _intermediate to advanced level_ best practices. If there are already ten easily found blog posts about it, it doesn't have to be in the Guide.
 - They are a _programmer or researcher_ that is already familiar with some other programming language or software-related technology.
 - They may be generally interested (in particular topics of eScience practice and research software development in general or how this is done at the eScience Center specifically), but their main aim is towards _practical_ application, not to create a literature study of the current landscape of (research) software.
 
-
 # Scope
 
 To make sure the information in this guide stays relevant and up to date it is intentionally low on technical details.
@@ -73,13 +73,12 @@ In practice, this means the Guide (for now) will mostly consist of language guid
 It can also sometimes function as a staging/draft area for eventually moving content to the Turing Way.
 However, we will urge you to contribute to the Turing Way directly.
 
-
 ## For significant changes / additions, especially new chapters
+
 Please check if your contribution fits in [The Turing Way](https://github.com/the-turing-way/the-turing-way) before considering contributing to this guide.
 Feel free to ask the [editors](#editorial-board) if you are unsure or open an [issue](https://github.com/NLeSC/guide/issues) to discuss it.
 If it does not fit, please open an [issue](https://github.com/NLeSC/guide/issues) to discuss your planned contribution before starting to work on it, to avoid disappointment later.
 
-
 # How?
 
 ## Style, form
@@ -92,14 +91,25 @@ A well written piece of advice should contain the following information:
 4. Long how: also explain other options for implementing advice, e.g. _here's a list of some more version control programs and/or services which we can recommend_.
 
 ## Technical
+
 Please use branches and pull requests to contribute content. If you are not part of the Netherlands eScience Center organization but would still like to contribute please do by submitting a pull request from a fork.
 
 ```shell
 git clone https://github.com/NLeSC/guide.git
+cd guide
 git branch newbranch
 git checkout newbranch
 ```
 
+Please install [pre-commit](https://pre-commit.com/) and enable the pre-commit
+hooks by running
+
+```shell
+pre-commit install
+```
+
+to automatically format your changes when committing.
+
 Add your new awesome feature, fix bugs, make other changes.
 
 To preview changes locally, host the repo with a static file web server:
@@ -116,7 +126,7 @@ To check if there are any broken links use [lychee](https://github.com/lycheever
 docker run --init -it -v `pwd`:/docs lycheeverse/lychee /docs --config=docs/lychee.toml
 ```
 
-If everything works as it should, ``git add``, ``commit`` and ``push`` like normal.
+If everything works as it should, `git add`, `commit` and `push` like normal.
 
 If you have made a significant contribution to the guide, please make sure to add yourself to the `CITATION.cff` file so your name can be included in the list of authors of the guide.
 
@@ -125,27 +135,27 @@ If you have made a significant contribution to the guide, please make sure to ad
 We host a PDF version of the guide on [Zenodo](https://doi.org/10.5281/zenodo.4020564).
 To update it a [new release](https://github.com/NLeSC/guide/releases) needs to be made of the guide. This will trigger a GitHub action to create a new Zenodo version with the PDF file.
 
-
 # Technical details
 
 The basics of how the Guide is implemented.
 
 The Guide is rendered by [docsify](https://docsify.js.org) and hosted on GitHub Pages.
 Deployment is "automatic" from the main branch, because docsify requires no build step into static HTML pages, but rather generates HTML dynamically from the MarkDown files in the Guide repository.
 The only configuration that was necessary for this automatic deployment is:
+
 1. The [index.html](https://github.com/NLeSC/guide/blob/main/index.html) file in the root directory that loads docsify.
 2. The empty [.nojekyll](https://github.com/NLeSC/guide/blob/main/.nojekyll) file, which tells GitHub that we're not dealing with Jekyll here (the GitHub Pages default).
 3. Telling GitHub in the Settings -> Pages menu to load the Pages content from the root directory.
-4. The [_sidebar.md](https://github.com/NLeSC/guide/blob/main/_sidebar.md) file for the table of contents.
+4. The [\_sidebar.md](https://github.com/NLeSC/guide/blob/main/_sidebar.md) file for the table of contents.
 
 Plugins that we use:
+
 - The [docsify full text search plugin](https://docsify.js.org/#/plugins?id=full-text-search)
 - The [docsify Google Analytics plugin](https://docsify.js.org/#/plugins?id=google-analytics)
 - [Prism](https://docsify.js.org/#/language-highlight) is used for language highlighting.
 
 If you want to change anything in this part, please discuss in an issue.
 
-
 # Zen of the Guide
 
 0. Help your colleagues.

README.md

@@ -6,6 +6,7 @@ This is a guide to research software development at the Netherlands eScience Cen
 It is a living document, written by and for our research software engineers (RSEs) and our collaborators.
 
 We write it for two reasons:
+
 1. To have a trusted source for quickly getting started on selected software development topics.
    We hope this will help RSEs (including our future selves!) to get off to a flying start on new projects in software/technological areas they are not yet familiar with.
 2. To discuss and reach consensus on such topics/areas.
@@ -42,6 +43,7 @@ You'll hone your writing skills while you're at it.
 
 See the [Contributing to this Guide](/CONTRIBUTING.md) chapter if you want to know more about how you can help, or ask one of the editors.
 Currently the editorial team consists of:
+
 - Bouwe Andela [@bouweandela](https://github.com/bouweandela) (research software engineer)
 - Carlos Martínez Ortiz [@c-martinez](https://github.com/c-martinez) (community manager)
 - Patrick Bos [@egpbos](https://github.com/egpbos) (technology lead)

_sidebar.md

@@ -1,15 +1,14 @@
-
-* [Introduction](/README.md)
-* [Best practices](/best_practices.md)
-* [Language Guides](/language_guides/languages_overview.md)
-   * [Bash](/language_guides/bash.md)
-   * [JavaScript and TypeScript](/language_guides/javascript.md)
-   * [Python](/language_guides/python.md)
-   * [R](/language_guides/r.md)
-   * [C and C++](/language_guides/ccpp.md)
-   * [Fortran](/language_guides/fortran.md)
-* [Technology Guides](/technology/technology_overview.md)
-   * [GPU programming](/technology/gpu.md)
-   * [UX - User Experience](/technology/user_experience.md)
-   * [Datasets](/technology/datasets.md)
-* [Contributing to this Guide](/CONTRIBUTING.md)
+- [Introduction](/README.md)
+- [Best practices](/best_practices.md)
+- [Language Guides](/language_guides/languages_overview.md)
+  - [Bash](/language_guides/bash.md)
+  - [JavaScript and TypeScript](/language_guides/javascript.md)
+  - [Python](/language_guides/python.md)
+  - [R](/language_guides/r.md)
+  - [C and C++](/language_guides/ccpp.md)
+  - [Fortran](/language_guides/fortran.md)
+- [Technology Guides](/technology/technology_overview.md)
+  - [GPU programming](/technology/gpu.md)
+  - [UX - User Experience](/technology/user_experience.md)
+  - [Datasets](/technology/datasets.md)
+- [Contributing to this Guide](/CONTRIBUTING.md)

best_practices.md

@@ -104,10 +104,12 @@ developing in.
 Below is a list of editors that support many programming languages.
 
 Integrated Development Environments (IDEs):
+
 - [Visual Studio Code](https://code.visualstudio.com/) - modern editor with extensive plugin ecosystem that can make it as powerful as most IDEs
 - [JetBrains IDEs](https://www.jetbrains.com/ides/) - specialized IDEs for Python, C++, Java and web, all using the IntelliJ framework
 - [Eclipse](https://www.eclipse.org/ide/) - a bit older but still nice
 
 Text editors:
+
 - [vim](https://www.vim.org/) - classic text editor
 - [emacs](https://www.gnu.org/software/emacs/) - classic text editor

index.html

@@ -1,36 +1,42 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Netherlands eScience Center Guide</title>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+    <meta name="description" content="Description" />
+    <meta
+      name="viewport"
+      content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
+    />
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/docsify/themes/vue.css"
+    />
+    <link rel="stylesheet" href="/styles.css" />
+    <link rel="icon" type="image/png" href="images/favicon.png" />
+  </head>
 
-<head>
-  <meta charset="UTF-8">
-  <title>Netherlands eScience Center Guide</title>
-  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
-  <meta name="description" content="Description">
-  <meta name="viewport"
-    content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
-    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify/themes/vue.css">
-    <link rel="stylesheet" href="/styles.css">
-  <link rel="icon" type="image/png" href="images/favicon.png">
-</head>
-
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      name: 'Netherlands eScience Center Guide',
-      repo: 'NLeSC/guide',
-      loadSidebar: true,
-      logo:'/images/netherlands-escience-center-logo-RGB.png',
-      alias: {
-        '/.*/_sidebar.md': '/_sidebar.md'
-      },
-      relativePath: true
-    }
-  </script>
-  <script src="https://cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js" data-ga="UA-55088238-8"></script>
-  <script src="https://cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/prismjs/components/prism-bash.min.js"></script>
-</body>
-
+  <body>
+    <div id="app"></div>
+    <script>
+      window.$docsify = {
+        name: "Netherlands eScience Center Guide",
+        repo: "NLeSC/guide",
+        loadSidebar: true,
+        logo: "/images/netherlands-escience-center-logo-RGB.png",
+        alias: {
+          "/.*/_sidebar.md": "/_sidebar.md",
+        },
+        relativePath: true,
+      };
+    </script>
+    <script
+      src="https://cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"
+      data-ga="UA-55088238-8"
+    ></script>
+    <script src="https://cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/prismjs/components/prism-bash.min.js"></script>
+  </body>
 </html>