refactor: fix semantic linebreaks (#46)

mschoettle · web-flow · commit 6d3786c2dd74 · 2024-11-13T06:36:11.000-05:00
Enforce semantic linebreaks and fix all occurrences.

Add SARIF formatter and use sarif-upload action to show them in the PR.
diff --git a/.github/markdownlint/.markdownlint-cli2.yaml b/.github/markdownlint/.markdownlint-cli2.yaml
@@ -0,0 +1,16 @@
+# https://github.com/DavidAnson/markdownlint-cli2#markdownlint-cli2yaml
+
+# additional configuration to the config in the root of the project
+# this additional config is used during the markdownlint CI job
+
+# use custom rule contained in supplementary rules image as a workaround
+# more details: https://github.com/DavidAnson/vscode-markdownlint/issues/336
+customRules:
+  # Enforce one sentence per line
+  # semantic line breaks (https://sembr.org/)
+  # See: https://github.com/DavidAnson/markdownlint/pull/719
+  - "markdownlint-rule-max-one-sentence-per-line"
+
+outputFormatters:
+  - - markdownlint-cli2-formatter-pretty
+  - - markdownlint-cli2-formatter-sarif
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -29,5 +29,25 @@ jobs:
         run: uv lock --locked
       - name: Run pre-commit
         uses: pre-commit/action@v3.0.1
+      - name: Run markdownlint
+        uses: YannickTeKulve/docker-run-action@0.0.6
+        with:
+          image: davidanson/markdownlint-cli2-rules:v0.14.0
+          # node user does not have permissions to workspace due to user id mismatch
+          options: -v ${{ github.workspace }}:/workdir --user root
+          # don't fail step if there are violations
+          run: markdownlint-cli2 --config .github/markdownlint/.markdownlint-cli2.yaml "**/*.md" || true
+      - name: Upload SARIF file
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          # Path to SARIF file relative to the root of the repository
+          sarif_file: markdownlint-cli2-sarif.sarif
+          # Optional category for the results
+          # Used to differentiate multiple results for one commit
+          category: markdownlint
+      # fail if there are markdownlint violations
+      - name: Check markdownlint results
+        run: |
+          cat markdownlint-cli2-sarif.sarif | grep -q '"results": \[\]'
       - name: Build mkdocs site
         run: uv run mkdocs build --strict
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -19,3 +19,17 @@ MD034: false
 # See: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
 # See: https://squidfunk.github.io/mkdocs-material/reference/admonitions/
 MD046: false
+
+max-one-sentence-per-line:
+  # ignore admonition syntax
+  # see: https://github.com/aepfli/markdownlint-rule-max-one-sentence-per-line/pull/52/files#r1579994724
+  ignored_words:
+    - "ie"
+    - "i.e"
+    - "eg"
+    - "e.g"
+    - "etc"
+    - "ex"
+    - "!!"
+    - "??"
+    - "vs"
diff --git a/docs/blog/posts/2012/hide-star-besides-email-addresses-in-thunderbird.md b/docs/blog/posts/2012/hide-star-besides-email-addresses-in-thunderbird.md
@@ -12,7 +12,8 @@ slug: hide-star-besides-email-addresses-in-thunderbird
 
 If you&mdash;for some reason&mdash;don't like the yellow (for contacts in your address book) or gray (for unknown contacts) star next to email addresses in the message header there's a simple way on how to hide it.
 
-If you don't have one yet, all it needs is a file called [userChrome.css](https://web.archive.org/web/20130728221756/https://developer.mozilla.org/en-US/docs/Thunderbird/Thunderbird_Configuration_Files#userChrome.css) inside a folder called `chrome` inside your profile folder. Add the following content:
+If you don't have one yet, all it needs is a file called [userChrome.css](https://web.archive.org/web/20130728221756/https://developer.mozilla.org/en-US/docs/Thunderbird/Thunderbird_Configuration_Files#userChrome.css) inside a folder called `chrome` inside your profile folder.
+Add the following content:
 
 ```css
 .emailStar {
diff --git a/docs/blog/posts/2013/reducing-file-size-of-a-pdf-on-mac-os.md b/docs/blog/posts/2013/reducing-file-size-of-a-pdf-on-mac-os.md
@@ -15,7 +15,8 @@ Instead of sending large files, it is almost always recommended to reduce the fi
 To do that, there are several ways.
 For example, there is an app called [_PDF Squeezer_](https://apps.apple.com/de/app/pdf-squeezer-4/id1502111349?l=en-GB&mt=12 "PDF Squeezer") in the _Mac App Store_ (in 2013: €3.59 or $3.99, more expensive today).
 
-The same functionality can be achieved using _Quartz filters_ in the _ColorSync Utility_. There is already one called _Reduce File Size_ but it might lead to a blurry PDF.
+The same functionality can be achieved using _Quartz filters_ in the _ColorSync Utility_.
+There is already one called _Reduce File Size_ but it might lead to a blurry PDF.
 You can copy this filter and adjust the settings.
 However, I found custom filters in the [Apple Support Community](https://discussions.apple.com/message/21402148#21402148 "Apple Support Community") that work quite well.
 
diff --git a/docs/blog/posts/2015/thunderbird-extension-toggle-headers-updated.md b/docs/blog/posts/2015/thunderbird-extension-toggle-headers-updated.md
@@ -20,7 +20,10 @@ Generally, I prefer to be contacted directly with bug reports and be able to res
 If a developer doesn't respond, a bad review is then acceptable.
 However, in this case bad reviews could be turned into very good ones, so no complaints in the end :smile:.
 
-Long story short, a new version of Toggle Headers was released. Basically, [Toggle Headers v1.0](https://addons.thunderbird.net/thunderbird/addon/toggle-headers/) restores support for _CompactHeader 2.1.0_ and higher, but at the same time, it still works with older versions. Unfortunately, the new version of _CompactHeader_ contains a bug that prevents toggling between the header modes (_Normal_/_All_) to work properly. I [reported the bug](https://forums.mozillazine.org/viewtopic.php?p=14375693#p14375693) in the referenced support forums, but haven't received a response to date.
+Long story short, a new version of Toggle Headers was released.
+Basically, [Toggle Headers v1.0](https://addons.thunderbird.net/thunderbird/addon/toggle-headers/) restores support for _CompactHeader 2.1.0_ and higher, but at the same time, it still works with older versions.
+Unfortunately, the new version of _CompactHeader_ contains a bug that prevents toggling between the header modes (_Normal_/_All_) to work properly.
+I [reported the bug](https://forums.mozillazine.org/viewtopic.php?p=14375693#p14375693) in the referenced support forums, but haven't received a response to date.
 
 This required a workaround to be integrated into the new version.
 When switching from collapsed header pane and _Normal_ to _All_ headers and then back to _Normal_, the header pane would stay expanded.
diff --git a/docs/blog/posts/2016/firefox-close-tab-button-on-hover.md b/docs/blog/posts/2016/firefox-close-tab-button-on-hover.md
@@ -49,6 +49,7 @@ Place this file into the `chrome` folder inside your profile's directory.
 Follow the [directions from Mozilla to find out where to find the profile's directory location](https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data).
 If the `chrome` folder does not exist, you need to create it first.
 
+<!-- markdownlint-disable-next-line max-one-sentence-per-line -->
 >? NOTE: **Additional step for Firefox before `v113` only**
 > In the address bar, open `about:config` and change the following preferences:
 > `browser.tabs.tabClipWidth` to `99`
diff --git a/docs/blog/posts/2018/digging-into-the-firefox-ui-for-the-tab-close-button.md b/docs/blog/posts/2018/digging-into-the-firefox-ui-for-the-tab-close-button.md
@@ -9,7 +9,7 @@ slug: digging-into-the-firefox-ui-for-the-tab-close-button
 ---
 # Digging into the Firefox UI for the tab close button
 
-Oops ... last year a new Firefox version broke the ["close button on tab hover" tweak](../2016/firefox-close-tab-button-on-hover.md) and I mentioned I will write a separate blog post on how I found out why and how to fix it.
+Last year a new Firefox version broke the ["close button on tab hover" tweak](../2016/firefox-close-tab-button-on-hover.md) and I mentioned I will write a separate blog post on how I found out why and how to fix it.
 Life happened, but fortunately I wrote down bullet points about what I did.
 
 It seems that with Firefox 54 something in the UI changed which broke the functionality.
diff --git a/docs/blog/posts/2020/migrating-data-to-nextcloud.md b/docs/blog/posts/2020/migrating-data-to-nextcloud.md
@@ -25,7 +25,8 @@ Even then, you can use the same procedure I used.
 
 ## Copy data to external drive
 
-For the external drive, I formatted it as _ExFat_ so that my Mac can write to it. On the Raspberry Pi, I had to install `exfat-fuse`.
+For the external drive, I formatted it as _ExFat_ so that my Mac can write to it.
+On the Raspberry Pi, I had to install `exfat-fuse`.
 I tried _FAT32_ as it is supported out-of-the-box by both but it has a limitation on maximum file size.
 I considered using _ext4_ but write support on the Mac supposedly is not stable.
 
diff --git a/docs/blog/posts/2020/notes-on-docker.md b/docs/blog/posts/2020/notes-on-docker.md
@@ -86,7 +86,8 @@ networks:
 ## Running the database on the host
 
 As outlined previously, I have a [_MariaDB_ instance running on the host](./notes-on-setting-up-my-raspberry-pi.md).
-Why is it not running in a container? I did consider it but containers are supposed to be stateless and the [general recommendation is to not run production databases in Docker](https://vsupalov.com/database-in-docker/).
+Why is it not running in a container?
+I did consider it but containers are supposed to be stateless and the [general recommendation is to not run production databases in Docker](https://vsupalov.com/database-in-docker/).
 There is an interesting discussion about this on [Reddit](https://www.reddit.com/r/docker/comments/amo2cc/running_production_databases_in_docker/) as well.
 In the end, it seemed like a risk (which I am not willing to take).
 
@@ -103,7 +104,8 @@ _MariaDB_ is then bound to the host IP of that network.
 A disadvantage is that then only Docker containers within that network can access the database.
 So if you have any other application on the host that needs to access the database that doesn't work.
 
-When creating database users, instead of specifying `'user'@'localhost'` you could say `'user'@'172.22.0.%'`. This assumes that your subnet is `172.22.0.0/24`.
+When creating database users, instead of specifying `'user'@'localhost'` you could say `'user'@'172.22.0.%'`.
+This assumes that your subnet is `172.22.0.0/24`.
 This way you don't need to know the specific IP address of a container.
 Also, the IP address of a container is not guaranteed to be the same if you restart your containers.
 To create a database with a user do the following in the SQL console (when running `sudo mysql` from the host):
@@ -118,7 +120,8 @@ FLUSH PRIVILEGES;
 
 If ever you perform a `docker logs <containername>` you most likely will notice that the timezone does not match your host's timezone (unless you happen to live in the _GMT_ timezone :smile:).
 By default, [Docker syncs the time but not timezone](https://stackoverflow.com/q/22800624), so the timezone is `GMT`/`UTC`.
-Some images do support the [setting of an environment variable](https://github.com/docker-library/redis/issues/127) `TZ` specifying the timezone but it is not always the case. If you want to support this for your own image, you need to install the `tzdata` system package.
+Some images do support the [setting of an environment variable](https://github.com/docker-library/redis/issues/127) `TZ` specifying the timezone but it is not always the case.
+If you want to support this for your own image, you need to install the `tzdata` system package.
 However, you can also simply add a bind mount to your volumes:
 
 ```yaml
diff --git a/docs/blog/posts/2020/notes-on-setting-up-my-raspberry-pi.md b/docs/blog/posts/2020/notes-on-setting-up-my-raspberry-pi.md
@@ -37,7 +37,8 @@ To enable it, a file called `ssh` needs to be added to the root of the volume on
 See [step 3 of the SSH Pi documentation](https://www.raspberrypi.org/documentation/remote-access/ssh/README.md) for more details.
 Basically `cd` to the root of the volume (most likely `/Volumes/boot`) on your machine and do `touch ssh`.
 
-With this it is possible to plug the card into the RPi and boot it. Then `ssh pi@<IPOfRaspberryPi>` should work.
+With this it is possible to plug the card into the RPi and boot it.
+Then `ssh pi@<IPOfRaspberryPi>` should work.
 
 ## Setting Up Raspbian
 
diff --git a/docs/blog/posts/2020/notes-on-traefik-v2-nextcloud-etc.md b/docs/blog/posts/2020/notes-on-traefik-v2-nextcloud-etc.md
@@ -143,7 +143,8 @@ certificatesResolvers:
 
 TIP: I highly recommend to first try the staging server at the beginning to avoid rate limiting.
 
-With just this, traefik will however not try to request a certificate. This is where the dynamic configuration comes into play.
+With just this, traefik will however not try to request a certificate.
+This is where the dynamic configuration comes into play.
 So, in the `dynamic-conf.yml` there are the [TLS options](https://doc.traefik.io/traefik/https/tls/) defined:
 
 ```yaml title="dynamic-conf.yml"
diff --git a/docs/blog/posts/2021/covid-19-montreal-dashboard.md b/docs/blog/posts/2021/covid-19-montreal-dashboard.md
@@ -39,4 +39,5 @@ Great timing since this was already in use here.
 So I could focus on wrangling all the different data formats.
 I hadn't used [Plotly/Dash](https://plotly.com/) before but I was able to quickly figure things out and make contributions to the different charts.
 
-The dashboard is available in French, English, Mandarin and Spanish. And it is [open source](https://github.com/jeremymoreau/covid19mtl) so contributions are more than welcome.
+The dashboard is available in French, English, Mandarin and Spanish.
+And it is [open source](https://github.com/jeremymoreau/covid19mtl) so contributions are more than welcome.
diff --git a/docs/blog/posts/2021/set-up-debian.md b/docs/blog/posts/2021/set-up-debian.md
@@ -127,7 +127,8 @@ Now, install a firewall (here `ufw`) to only open the ports that you really need
 
 5. Try to log in from another terminal to verify it is still working.
 
-That's pretty much it. You might also want to [set up msmtp](./setting-up-msmtp.md) so that you receive email from your system, cron etc.
+That's pretty much it.
+You might also want to [set up msmtp](./setting-up-msmtp.md) so that you receive email from your system, cron etc.
 There are also the following packages I find useful which I install:
 
 * `htop`: Allows to interactively monitor the system resources and processes.
diff --git a/docs/index.md b/docs/index.md
@@ -1,5 +1,11 @@
 # Hallo, Hi, Bonjour :wave:
 
-I am Matthias, a German living in Montréal, Canada. I am passionate about tech, open source, racquet sports (especially table tennis and squash), and specialty coffee. I like to help others, and so just like with contributing to open source projects, I intend to share information here that are hopefully helpful to someone else.
+I am Matthias, a German living in Montréal, Canada.
+I am passionate about tech, open source, racquet sports (especially table tennis and squash), and specialty coffee.
+I like to help others, and so just like with contributing to open source projects, I intend to share information here that are hopefully helpful to someone else.
 
-I enjoy building and improving software, in particular building reusable software. With an eye for details and the ability to understand and see the big picture, I am able to provide well-thought-out solutions. It also allows me to quickly understand new/unfamiliar code or concepts and connect the dots when debugging and solving problems. I strive for reusable, clean and maintainable code. I see myself as a generalist, knowing various technologies and the ability to quickly learn new technologies and concepts.
+I enjoy building and improving software, in particular building reusable software.
+With an eye for details and the ability to understand and see the big picture, I am able to provide well-thought-out solutions.
+It also allows me to quickly understand new/unfamiliar code or concepts and connect the dots when debugging and solving problems.
+I strive for reusable, clean and maintainable code.
+I see myself as a generalist, knowing various technologies and the ability to quickly learn new technologies and concepts.
diff --git a/docs/research/index.md b/docs/research/index.md
@@ -80,6 +80,7 @@ I have been a Teaching Assistant for the following courses at McGill University:
 
 ## Awards
 
+<!-- markdownlint-disable-next-line max-one-sentence-per-line -->
 I have received the following awards during my studies (M.Sc. and Ph.D.):
 
 * McGill School of Computer Science Graduate Excellence Award (2015)
diff --git a/docs/research/publications.md b/docs/research/publications.md
@@ -1,4 +1,5 @@
-<!-- markdownlint-disable MD042 -->
+<!-- markdownlint-disable no-empty-links -->
+<!-- markdownlint-disable max-one-sentence-per-line -->
 # Publications
 
 ## 2019
