build: restrict the markdown languages to use for code blocks

albertony · albertony · commit f361cdf1cb60 · 2025-11-01T15:52:41.000+01:00
diff --git a/.markdownlint.yml b/.markdownlint.yml
@@ -41,3 +41,32 @@ single-title: # MD025
 # Markdown files we must use whatever works in the final HTML generated docs.
 # Suppress Markdownlint warning: Link fragments should be valid.
 link-fragments: false # MD051
+
+# Restrict the languages and language identifiers to use for code blocks.
+# We only want those supported by both Hugo and GitHub. These are documented
+# here:
+#   https://gohugo.io/content-management/syntax-highlighting/#languages
+#   https://docs.github.com//get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#syntax-highlighting
+# In addition, we only want to allow identifiers (aliases) that correspond to
+# the same language in Hugo and GitHub, and preferrably also VSCode and other
+# commonly used tools, to avoid confusion. An example of this is that "shell"
+# by some are considered an identifier for shell scripts, i.e. an alias for
+# "sh", while others consider it an identifier for shell sessions, i.e. an
+# alias for "console". Although Hugo and GitHub in this case are consistent and
+# have choosen the former, using "sh" instead, and not allowing use of "shell",
+# avoids the confusion entirely.
+fenced-code-language: # MD040
+  allowed_languages:
+    - text
+    - console
+    - sh
+    - bat
+    - ini
+    - json
+    - yaml
+    - go
+    - python
+    - c++
+    - c#
+    - java
+    - powershell
diff --git a/docs/content/docker.md b/docs/content/docker.md
@@ -126,7 +126,7 @@ token = {"access_token":...}
 Now create the file named `example.yml` with a swarm stack description
 like this:
 
-```yml
+```yaml
 version: '3'
 services:
   heimdall:
@@ -295,7 +295,7 @@ Each of them should be named after its volume and have at least two
 elements, the self-explanatory `driver: rclone` value and the
 `driver_opts:` structure playing the same role as `-o key=val` CLI flags:
 
-```yml
+```yaml
 volumes:
   volume_name_1:
     driver: rclone
@@ -463,7 +463,7 @@ to inform the docker daemon that a volume is (un-)available.
 As a workaround you can setup a healthcheck to verify that the mount
 is responding, for example:
 
-```yml
+```yaml
 services:
   my_service:
     image: my_image
diff --git a/docs/content/docs.md b/docs/content/docs.md
@@ -3210,13 +3210,13 @@ at rest or transfer. Detailed instructions for popular OSes:
 
 - Generate and store a password
 
-  ```pwsh
+  ```powershell
   New-Object -TypeName PSCredential -ArgumentList "rclone", (ConvertTo-SecureString -String ([System.Web.Security.Membership]::GeneratePassword(40, 10)) -AsPlainText -Force) | Export-Clixml -Path "rclone-credential.xml"
   ```
 
 - Add the password retrieval instruction
 
-  ```pwsh
+  ```powershell
   [Environment]::SetEnvironmentVariable("RCLONE_PASSWORD_COMMAND", "[System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR((Import-Clixml -Path "rclone-credential.xml").Password))")
   ```
 
diff --git a/docs/content/faq.md b/docs/content/faq.md
@@ -260,7 +260,7 @@ the port on the host.
 
 A simple solution may be restarting the Host Network Service with eg. Powershell
 
-```pwsh
+```powershell
 Restart-Service hns
 ```
 
diff --git a/docs/content/install.md b/docs/content/install.md
@@ -511,7 +511,7 @@ Instructions
    your local roles-directory
 2. add the role to the hosts you want rclone installed to:
 
-    ```yml
+    ```yaml
     - hosts: rclone-hosts
       roles:
         - rclone
@@ -638,7 +638,7 @@ Example of a PowerShell command that creates a Windows service for mounting
 some `remote:/files` as drive letter `X:`, for *all* users (service will be
 running as the local system account):
 
-```pwsh
+```powershell
 New-Service -Name Rclone -BinaryPathName 'c:\rclone\rclone.exe mount remote:/files X: --config c:\rclone\config\rclone.conf --log-file c:\rclone\logs\mount.txt'
 ```
 
diff --git a/librclone/README.md b/librclone/README.md
@@ -130,7 +130,7 @@ either.
 The interface of librclone is so simple, that all you need is to define the
 small struct `RcloneRPCResult`, from [librclone.go](librclone.go):
 
-```C++
+```c++
 struct RcloneRPCResult {
     char* Output;
     int	Status;
@@ -161,7 +161,7 @@ own escaping. This is not a Windows-specific issue, but there is the
 additional challenge that native filesystem path separator is the same as
 the escape character, and you may end up with strings like this:
 
-```C++
+```c++
 const char* input = "{"
 "\"fs\": \"C:\\\\Temp\","
 "\"remote\": \"sub/folder\","
