Simplify PR template, introduce MD linter (#3051)

* Convert checkboxes to questions

Signed-off-by: Kim Brose <[email protected]>

* document internal links

Signed-off-by: HarHarLinks <[email protected]>

* document blog taxonomies

Signed-off-by: HarHarLinks <[email protected]>

* update PR bot CI from https://github.com/HarHarLinks/pr-template-autoclose

Signed-off-by: HarHarLinks <[email protected]>

* fix heading depth (MD001 MD003)

Signed-off-by: HarHarLinks <[email protected]>

* fix code blocks

Signed-off-by: HarHarLinks <[email protected]>

* fix spaces in link text (MD039)

Signed-off-by: HarHarLinks <[email protected]>

* fix no newline at end of file (MD047)

Signed-off-by: HarHarLinks <[email protected]>

* fix bare URLs without angle backets (MD034)

Signed-off-by: HarHarLinks <[email protected]>

* remove redundant attribute

Signed-off-by: HarHarLinks <[email protected]>

* linter exception

Signed-off-by: HarHarLinks <[email protected]>

* lint links and headings with rumdl instead of checklist

Signed-off-by: HarHarLinks <[email protected]>

* convert signoff checklist to heading

Signed-off-by: HarHarLinks <[email protected]>

* configure linter to .rumdl.toml explicitly

Signed-off-by: HarHarLinks <[email protected]>

* bump rumdl action

Signed-off-by: HarHarLinks <[email protected]>

* Shorten comments in the template

Co-authored-by: Thibault Martin <[email protected]>
Signed-off-by: Kim Brose <[email protected]>

* Remove rumdl default config example comments

Co-authored-by: Thibault Martin <[email protected]>
Signed-off-by: Kim Brose <[email protected]>

* explain more about the pr-bot

Signed-off-by: HarHarLinks <[email protected]>

* pin rumdl action to v0

Signed-off-by: HarHarLinks <[email protected]>

* fix unlinked email address in coc

Signed-off-by: HarHarLinks <[email protected]>

---------

Signed-off-by: Kim Brose <[email protected]>
Signed-off-by: HarHarLinks <[email protected]>
Co-authored-by: Thibault Martin <[email protected]>

Author: HarHarLinks

.github/pull_request_template.md

@@ -1,32 +1,33 @@
+### Description
+
+<!-- Please describe what you added or changed. This helps us review the PR faster. -->
+
+
+
+### Related issues
+
+<!-- If you know that your PR closes issues, please list them here -->
+
+### Role
+
+<!-- Are you contributing as an individual or on behalf of an organisation? Are you affiliated with any project relevant to this PR? -->
+
+### Timeline
+
+<!-- By when do you need us to review your PR at the latest? -->
+
+### Signoff
+
+Please [sign off](https://github.com/matrix-org/matrix.org/blob/main/CONTRIBUTING.md) your individual commits or whole pull request.
+
+
+
+<!-- ------------------------------ DO NOT WRITE BELOW THIS LINE ------------------------------ -->
 <!-- Thank you for creating a Pull Request to the matrix.org website!
      Please read our documentation for contributors to make the review process a smooth as possible:
      - https://github.com/matrix-org/matrix.org/blob/main/README.md
      - https://github.com/matrix-org/matrix.org/blob/main/CONTRIBUTING.md
      - https://github.com/matrix-org/matrix.org/blob/main/CONTENT.md
-
-     You can use the CI build or a local environment to check your changes are working as expected.
      
      If you have questions at any time, please contact the Website & Content Working Group at
      https://matrix.to/#/#matrix.org-website:matrix.org -->
-
-### Description
-<!-- Please describe what you added here, and add a screenshot or video if possible.
-     That makes it easier to understand the change. -->
-
-### :heavy_check_mark: Checklist
-<!-- Please tick as appropriate, but don't remove this checklist from your PR, as it is useful for reviewers, too. -->
-
-- [x] Keep this checklist
-- Check for common mistakes:
-  - [ ] Wrap plain URLs in `<>` to linkify them ([learn more](https://github.com/matrix-org/matrix.org/blob/main/CONTENT.md#publishing-to-the-blog)).
-  - [ ] Use the right level of headings: The page title will use a level 1 headings, so your headings should use level 2 and below.
-  - [ ] Use internal links: when linking to another page on <https://matrix.org>, use the Zola `[label](@/target.md)` [syntax](https://www.getzola.org/documentation/content/linking/#internal-links).
-- For blog posts:
-  - [ ] Verify the date and post ordering on the `/blog` page, especially for multiple posts on the same day. Prefer UTC format, e.g. `2025-12-01T14:00:00Z` for Dec 1st, 2025, 2pm UTC.
-  - [ ] Set the correct author and category. Browse existing ones at <https://matrix.org/author/> and <https://matrix.org/category/> to match them.
-- [ ] If you hold a specific role in relation to the content you are contributing, such as project maintainer or on behalf of a team or organisation, please let us know. See [example](https://github.com/matrix-org/matrix.org/pull/2969).
-- [ ] If your PR is time-sensitive in any way, please mention the attached timeline and context in the PR description.
-- [ ] Mention any issues related to the PR. Use [GitHub keywords](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) as appropriate.
-- [ ] Your individual commits or pull request is [signed off](https://github.com/matrix-org/matrix.org/blob/main/CONTRIBUTING.md).
-
-<!-- ------------------------------ DO NOT WRITE BELOW THIS LINE ------------------------------ -->

.github/workflows/linter.yaml

@@ -0,0 +1,27 @@
+name: Linters
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  run:
+    name: Spell Check with Typos
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout Actions Repository
+      uses: actions/checkout@v6
+
+    - name: Check spelling
+      uses: crate-ci/[email protected]
+
+  rumdl-check:
+    name: Lint Markdown with rumdl
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: rvben/rumdl@v0
+        with:
+          config: .rumdl.toml
+          report-type: annotations

.github/workflows/pr-bot.yml

@@ -1,35 +1,33 @@
 name: PR Bot
 
 on:
-  pull_request:
+  pull_request_target:  # unblock read/write repository permission, even when it is triggered from a public fork - https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#permissions
     types: [opened, reopened, ready_for_review]  # https://docs.github.com/en/webhooks/webhook-events-and-payloads?actionType=ready_for_review#pull_request
 
 jobs:
   missing-template:
     name: Auto-draft PRs missing template
     runs-on: ubuntu-latest
-    permissions: write-all
-    env:
-      CHECKOUT_DIR: my-repo
+    permissions:
+      pull-requests: write
+      contents: write  # Needed for the bot to turn the PR into a draft if the template is missing
+                       # https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request
 
     steps:
-      - uses: actions/checkout@v5
-        with:
-          path: ${{ env.CHECKOUT_DIR }}
-
       - name: Check if the PR template was deleted
         env:
           GH_TOKEN: ${{ github.token }}
           BASE_URL: ${{ github.server.url }}/${{ github.repository }}/blob/main
           PR_NUMBER: ${{ github.event.number }}
-        working-directory: ${{ env.CHECKOUT_DIR }}
         run: |
-          if ! gh pr view $PR_NUMBER --json 'body' | grep -q "don't remove this checklist from your PR"; then
-            gh pr ready $PR_NUMBER --undo  # mark as draft
-            gh pr edit $PR_NUMBER --add-label 'missing-template'
-            gh pr review $PR_NUMBER --request-changes --body "Thanks for contributing to the matrix.org website. I have automatically marked your pull request as a draft. Please restore the [PR template]($BASE_URL/.github/pull_request_template.md?plain=1) to your PR description and follow our [contributing guidelines]($BASE_URL/CONTRIBUTING.md), then undraft to let the team know the PR is ready for review."
+          cmd="gh pr -R ${{ github.repository }}"
+          if ! $cmd view $PR_NUMBER --json 'body' | grep -q "Description"; then
+            $cmd ready $PR_NUMBER --undo  # mark as draft
+            $cmd edit $PR_NUMBER --add-label 'missing-template'
+            $cmd review $PR_NUMBER --request-changes --body "Thanks for contributing to the matrix.org website. I have automatically marked your pull request as a draft. Please restore the [PR template]($BASE_URL/.github/pull_request_template.md?plain=1) to your PR description and follow our [contributing guidelines]($BASE_URL/CONTRIBUTING.md), then undraft to let the team know the PR is ready for review."
+            exit 1
           fi
-          if gh pr view $PR_NUMBER --json 'labels' | grep -q "missing-template"; then
-            gh pr edit $PR_NUMBER --remove-label 'missing-template'
-            gh pr review $PR_NUMBER --approve --body "Thank you for applying the PR template. The PR is now ready for review by a human."
+          if $cmd view $PR_NUMBER --json 'labels' | grep -q "missing-template"; then
+            $cmd edit $PR_NUMBER --remove-label 'missing-template'
+            $cmd review $PR_NUMBER --approve --body "Thank you for applying the PR template. The PR is now ready for review by a human."
           fi

.github/workflows/spell-check.yaml

@@ -0,0 +1,42 @@
+# rumdl configuration file
+
+# Global configuration options
+[global]
+# List of rules to disable (uncomment and modify as needed)
+# disable = ["MD013", "MD033"]
+
+# List of rules to enable exclusively (if provided, only these rules will run)
+enable = ["MD001", "MD003", "MD011", "MD034", "MD039"]
+
+# List of file/directory patterns to include for linting (if provided, only these will be linted)
+# include = [
+#    "docs/*.md",
+#    "src/**/*.md",
+#    "README.md"
+# ]
+
+# List of file/directory patterns to exclude from linting
+exclude = [
+    # Common directories to exclude
+    ".git",
+    ".github",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+
+    # legacy content
+    "content/blog/2014",
+    "content/blog/2015",
+    "content/blog/2016",
+    "content/blog/2017",
+    "content/blog/2018",
+]
+
+# Respect .gitignore files when scanning directories (default: true)
+respect-gitignore = true
+
+# Markdown flavor/dialect (uncomment to enable)
+# Options: mkdocs, gfm, commonmark
+flavor = "commonmark"  # https://www.getzola.org/documentation/getting-started/overview/
+

.rumdl.toml

@@ -4,6 +4,19 @@ The matrix.org website is powered by [Zola](https://www.getzola.org/), a [static
 
 This documentation is about helping you create new content that the static site generator will accept. To get your content actually deploy on matrix.org, you need to be familiar with git, GitHub and Pull Requests. If that's not the case, we suggest either finding someone who is and can help, or dropping us a line in the [Matrix.org Website chat room](https://matrix.to/#/#matrix.org-website:matrix.org).
 
+## General tips
+
+### Internal links
+
+Zola can automatically check internal links if they are added using the [Zola internal link syntax](https://www.getzola.org/documentation/content/linking/#internal-links).
+
+Tl;dr: Linking to a file located at content/pages/about.md would be `[my link](@/pages/about.md)`.
+
+There are some edge cases, for example this can only work when a file generating a page actually exists, e.g. not for entirely generated pages such as the blog's `/category/` pages.
+We collect such issues in [#2829](https://github.com/matrix-org/matrix.org/issues/2829) and welcome ideas to improve this approach.
+
+We still prefer this approach on a best effort basis as it has already proven useful.
+
 ## Publishing to the blog
 
 Articles on the blog are written in the markdown format. Markdown should generally be the same everywhere, but there are small variations around what you can or can't do with it. Zola supports the [CommonMark variant](https://commonmark.org/help/) of Markdown. Note that Zola's Markdown parser is pedantic about links and requires to use `<>` around a link without title.
@@ -25,6 +38,8 @@ Once this structure is in place, you need to write the actual blog post. It is a
 
 In the frontmatter, make sure to format the date as `year-month-day` (e.g. `2024-01-22`) then append `T` to specify the time as `hour:minute:seconds` (e.g. `12:30:00`) and add a final `Z` to specify that the time is on the UTC time zone. We use UTC to make it easier for humans to figure out which blog post is going to be published first if two blog posts are issued on the same day.
 
+The `taxonomies` automatically create groupings of blog posts and also filter into respective atom feeds readers can subscribe to. It is hence important to choose correct and consistent values for both author(s) and categories. You can browse existing ones at <https://matrix.org/author/> and <https://matrix.org/category/> to match them.
+
 You can use the following template to create a new blog post:
 
 ```markdown

CONTENT.md

@@ -28,8 +28,8 @@ just 612MiB.
 For more information on this please check out these 2 articles which also
 explain why `--depth=1` is not ideal and which implications this has:
 
-- https://github.blog/open-source/git/get-up-to-speed-with-partial-clone-and-shallow-clone/
-- https://web.archive.org/web/20241001150554/https://nayak.io/posts/git-clone-optimizations/
+- <https://github.blog/open-source/git/get-up-to-speed-with-partial-clone-and-shallow-clone/>
+- <https://web.archive.org/web/20241001150554/https://nayak.io/posts/git-clone-optimizations/>
 
 ## Building the website
 
@@ -41,5 +41,5 @@ zola serve
 ```
 
 Zola will build the website and start a web server, usually at
-http://127.0.0.1:1111
+<http://127.0.0.1:1111>
 

README.md

@@ -57,7 +57,8 @@ app_service_config_files:
   - "/path/to/appservice/registration.yaml"
 </pre>
 NB: Note the "-" at the start; this indicates a list element. The registration file <code>registration.yaml</code> should look like:
-<pre># registration.yaml
+```
+# registration.yaml
 
 # this is the base URL of the application service
 url: "http://localhost:5000"
@@ -78,11 +79,12 @@ namespaces:
   aliases:
     - exclusive: false
       regex: "#logged_.*"
-</pre>
+```
 <strong>You will need to restart the home server after editing the config file before it will take effect.</strong>
 
 To test everything is working correctly, go ahead and explicitly create a room with the alias "#logged_test:localhost" and send a message into the room: the HS will relay the message to the AS by PUTing to /transactions/&lt;tid&gt; and you should see your AS print the event on the terminal. This will monitor any room which has an alias prefix of "#logged_", but it won't lazily create room aliases if they don't already exist. This means it will only log messages in the room you created before: #logged_test:localhost. Try joining the room "#logged_test2:localhost" without creating it, and it will fail. Let's fix that and add in lazy room creation:
-<pre>@app.route("/rooms/&lt;alias&gt;")
+```
+@app.route("/rooms/<alias>")
 def query_alias(alias):
     alias_localpart = alias.split(":")[0][1:]
     requests.post(
@@ -94,7 +96,7 @@ def query_alias(alias):
         headers={'{'}"Content-Type":"application/json"{'}'}
     )
     return jsonify({'{'}{'}'})
-</pre>
+```
 This makes the application service lazily create a room with the requested alias whenever the HS queries the AS for the existence of that alias (when users try to join that room), allowing any room with the alias prefix #logged_ to be sent to the AS. Now try joining the room "#logged_test2:localhost" and it will work as you'd expect.  You can see that if this were a real bridge, the AS would have checked for the existence of #logged_test2 in the remote network, and then lazily-created it in Matrix as required.
 
 Application services are powerful components which extend the functionality of home servers, but they are limited. They can only ever function in a "passive" way. For example, you cannot implement an application service which censors swear words in rooms, because there is no way to prevent the event from being sent. Aside from the fact that censoring will not work when using end-to-end encryption, all federated home servers would also need to reject the event in order to stop developing an inconsistent event graph. To "actively" monitor events, another component called a "Policy Server" is required, which is beyond the scope of this post.  Also, Application Services can result in a performance bottleneck, as all events on the homeserver must be ordered and sent to the registered application services.  If you are bridging huge amounts of traffic, you may be better off having your bridge directly talk the Server-Server federation API rather than the simpler Application Service API.

content/blog/2015/03/2015-03-02-introduction-to-application-services.md

@@ -11,7 +11,7 @@ category = ["Tutorials"]
 
 Synapse has had support for exporting a comprehensive range of metrics via HTTP since 0.8.1 - we added this to help quantify the benefits of all the performance work which is going on currently in advance of Synapse 0.9. If you're interested in monitoring your own synapse and seeing what's going on using something like Prometheus, Leo just wrote a quick tutorial on getting up and running:
 
-#### How to monitor Synapse metrics using Prometheus
+### How to monitor Synapse metrics using Prometheus
 
 <dl>
 <dt>1: Install prometheus:</dt><dd>Follow instructions at <a href="http://prometheus.io/docs/introduction/install/">http://prometheus.io/docs/introduction/install/</a></dd>

content/blog/2015/04/2015-04-23-monitoring-synapse-metrics-with-prometheus.md

@@ -80,14 +80,14 @@ The full changelog for 0.3 of the spec is:
 
 This is a medium-sized release; the main thing being to support configurable room visibility within groups (so that whenever you add a room to a group, you're not forced into sharing their existence with the general public, but can choose to just tell group members about them).  There's also a bunch of useful bug fixes and some performance improvements, including lots of contributions from the community this release (thank you!).  Full release notes are:
 
-##### Changes in synapse v0.25.0 (2017-11-15)
+#### Changes in synapse v0.25.0 (2017-11-15)
 
 Bug fixes:
 <ul>
  	<li>Fix port script (PR <a class="issue-link js-issue-link" href="https://github.com/matrix-org/synapse/pull/2673" data-error-text="Failed to load issue title" data-id="273841564" data-permission-text="Issue title is private" data-url="https://github.com/matrix-org/synapse/issues/2673">#2673</a>)</li>
 </ul>
 
-##### Changes in synapse v0.25.0-rc1 (2017-11-14)
+#### Changes in synapse v0.25.0-rc1 (2017-11-14)
 
 Features:
 <ul>