feat: markdown linting / formatting

.github/workflows/ci.yaml

@@ -31,6 +31,15 @@ jobs:
           node-version-file: ".nvmrc"
           cache: npm
 
+      - name: Run rumdl
+        uses: rvben/rumdl-action@v0
+        with:
+          version: latest
+          path: "."
+          file_types: "md,mdx"
+          changed_files_only: true
+          fail_on_error: true
+
       - name: Install dependencies
         run: npm ci
 

.rumdl.toml

@@ -0,0 +1,48 @@
+[global]
+# Keep legacy long lines and preserve alignment in code examples.
+disable = ["MD013", "MD034", "MD064"]
+
+# Enable table formatting/fixing support.
+extend-enable = ["MD060"]
+
+# Keep this empty for now; URL auto-fixing is covered by disabled MD034.
+unfixable = []
+
+[MD004]
+# Enforce '-' as the single bullet style across docs.
+style = "dash"
+
+[MD046]
+# Require fenced code blocks globally.
+style = "fenced"
+
+[per-file-flavor]
+# Parse MDX files with MDX-aware rules.
+"**/*.mdx" = "mdx"
+
+[per-file-ignores]
+# Historical changelog entries use legacy heading/list structures.
+"src/content/changelog/*.md" = ["MD001", "MD036"]
+
+# README uses custom HTML header layout and no leading H1.
+"README.md" = ["MD033", "MD041"]
+
+# Existing docs use inline HTML for embeds/widgets and should stay unchanged.
+"src/content/docs/online-payments/apm/apple-pay.mdx" = ["MD033"]
+"src/content/docs/online-payments/apm/google-pay.mdx" = ["MD033"]
+"src/content/docs/online-payments/checkouts/card-widget.mdx" = ["MD033"]
+"src/content/docs/terminal-payments/sdks/android-sdk.mdx" = ["MD033"]
+
+# Plugin pages use raw URL constants/props for MDX components.
+"src/content/docs/online-payments/plugins/prestashop.mdx" = ["MD034"]
+"src/content/docs/online-payments/plugins/woocommerce.mdx" = ["MD034"]
+
+# Legacy iOS SDK page has dense mixed MDX/Steps/list patterns.
+# Keep it build-safe by scoping rule ignores until the page is refactored.
+"src/content/docs/terminal-payments/sdks/ios-sdk.mdx" = ["MD004", "MD007", "MD012", "MD030", "MD031", "MD032", "MD040", "MD046", "MD049", "MD051", "MD060", "MD069"]
+
+# Legacy mixed Tabs+code snippets trigger MD046 false positives after formatting.
+"src/content/docs/online-payments/guides/refund.mdx" = ["MD046", "MD051"]
+"src/content/docs/online-payments/guides/single-payment.mdx" = ["MD046"]
+"src/content/docs/online-payments/guides/tokenization-with-payment-sdk.mdx" = ["MD046"]
+"src/content/docs/online-payments/sdks/react-native.mdx" = ["MD046"]

AGENTS.md

@@ -42,6 +42,13 @@ For files in `src/content/docs/`, include frontmatter at the top of every page.
 
 CI relies on `npm run check`. When editing MDX content, preview via `npm run dev` to verify navigation, sidebar ordering, and snippet rendering. There is no Jest-style test suite; document any manual verification steps in the pull request if behavior changes or APIs are added.
 
+## Markdown Linting Guidelines
+
+- Prefer fixing markdown issues in content first instead of adding linter exceptions.
+- Run `npm run lint:markdown` and `npm run build` after markdown-heavy changes to catch MDX parsing regressions early.
+- `rumdl` can produce impractical suggestions for complex MDX (for example mixed Tabs/Steps/components); in such cases, adding scoped ignores in `.rumdl.toml` is acceptable.
+- Every new ignore must be narrowly scoped (per-file/per-rule) and include a short comment explaining why it is needed.
+
 ## Validation Matrix
 
 Run at least the following commands before submitting changes:

package.json

@@ -32,9 +32,12 @@
     "precheck": "astro sync",
     "check": "astro check",
     "prelint": "astro sync",
-    "lint": "npx eslint",
-    "format": "npm run format:src && npm run format:content",
-    "format:content": "prettier --write \"**/*.{md,mdx,astro}\"",
+    "lint": "npm run lint:src",
+    "lint:src": "npx eslint",
+    "lint:markdown": "chmod +x node_modules/@rumdl/cli-*/rumdl 2>/dev/null || true && rumdl check .",
+    "format": "npm run format:src && npm run format:astro && npm run format:markdown",
+    "format:astro": "npx prettier --write \"**/*.astro\"",
+    "format:markdown": "chmod +x node_modules/@rumdl/cli-*/rumdl 2>/dev/null || true && rumdl fmt .",
     "format:src": "npx prettier --write \"**/*.{js,jsx,ts,tsx,mjs,css,json}\"",
     "linkcheck": "CHECK_LINKS=true astro build",
     "test": "vitest run"
@@ -76,6 +79,7 @@
     "react-content-loader": "^7.1.2",
     "react-dom": "^19.2.4",
     "react-final-form": "^7.0.0",
+    "rumdl": "0.1.30",
     "sass": "^1.97.3",
     "starlight-image-zoom": "^0.13.0",
     "starlight-links-validator": "^0.19.2",

src/content/docs/online-payments/3ds.mdx

@@ -7,7 +7,6 @@ sidebar:
 
 import { Aside } from '@astrojs/starlight/components';
 
-
 <Aside type="caution">
 
 Affects all electronic payments accepted by merchants operating within the European Union.
@@ -42,7 +41,7 @@ Both the merchant account and card issuer must support 3-D Secure. The flow adds
 
 1. Add the `redirect_url` parameter to your [checkout creation request](/api/checkouts/create). This URL receives the user after payment completion.
 
-2. [Process the checkout](/api/checkouts/process) to get a `next_step` object with details for the required next action, allowing you to redirect the user to a required challenge screen. 
+2. [Process the checkout](/api/checkouts/process) to get a `next_step` object with details for the required next action, allowing you to redirect the user to a required challenge screen.
 
 3. Use the `next_step` content to redirect an end user to a challenge screen. The `next_step` object contains:
 

src/content/docs/online-payments/apm/google-pay.mdx

@@ -9,15 +9,14 @@ sidebar:
 import { Aside } from '@astrojs/starlight/components';
 import Image from '@components/content/Image.astro';
 
-
 In this guide, you will learn how to directly integrate Google Pay with SumUp. Please note that you can also offer Google Pay through our Payment Widget (see [Payment Widget documentation](/online-payments/checkouts/card-widget#alternative-payment-methods)).
 
 ## Prerequisites
 
 - You have a SumUp merchant account and have already filled in your [account details](https://me.sumup.com/account).
 - If you want to test payments without involving real funds, [create a sandbox merchant account](/online-payments/#getting-a-sandbox-merchant-account).
 - Review [Google Pay API terms of service](https://payments.developers.google.com/terms/sellertos).
-- Complete the domain onboarding setup steps described in your Dashboard under **Settings** > **For developers** > **Payment wallets**. You can read Google's tutorial [Google Pay for Payments](https://developers.google.com/pay/api/web/guides/tutorial), which covers the requirements you're expected to follow in order to successfully offer this payment method. 
+- Complete the domain onboarding setup steps described in your Dashboard under **Settings** > **For developers** > **Payment wallets**. You can read Google's tutorial [Google Pay for Payments](https://developers.google.com/pay/api/web/guides/tutorial), which covers the requirements you're expected to follow in order to successfully offer this payment method.
 
 <Image alt="Screenshot of the dashboard Developer Settings, showing Payment wallets section that includes Apple Pay and Google Pay" src="/img/guides/find_payment_wallets.png" width="80%" />