From caa8a72487f8333f02cebb00394c76109fea9be9 Mon Sep 17 00:00:00 2001 From: Bruno Galvao Date: Wed, 13 May 2026 12:53:13 +0700 Subject: [PATCH 1/5] docs: adopt PaperMoon styleguide via AGENTS.md + Vale lint Pilot adoption of the agent-loadable PaperMoon documentation styleguide: - AGENTS.md at repo root pointing at the canonical papermoonio/documentation-style-guide/AGENTS.md. Coding agents (Claude Code, Cursor, Codex, etc.) load AGENTS.md automatically when they open this repository, so authoring sessions pick up the documentation rules without manual context wiring. - .vale.ini and styles/PaperMoon/ mirroring the styleguide repo's Vale rules: banned phrases (delve, leverage, seamless, robust, "it's important to note", "in summary", "currently", etc., simply, just, easily, obviously), terminology substitutions (ERC-20, JSON-RPC, dApp, TestNet, MainNet), emoji ban, descriptive link text, INSERT_ placeholder format, first-person plural warning, and the no-exclamation rule. Vocab accept-list seeds Polkadot-specific terms. - .github/workflows/vale.yml runs Vale on changed markdown files in every PR. Scoped to added/modified .md files only (not the full tree) so existing tech debt does not fail the workflow; the gate applies to net-new content. Refresh process: when the styleguide repo updates, copy .vale.ini and styles/ over again. The pointer in AGENTS.md always resolves to the latest canonical source. --- .github/workflows/vale.yml | 40 +++++++++++++++++ .vale.ini | 21 +++++++++ AGENTS.md | 44 +++++++++++++++++++ styles/PaperMoon/BannedPhrases.yml | 19 ++++++++ styles/PaperMoon/DiscouragedPhrases.yml | 19 ++++++++ styles/PaperMoon/FirstPersonPlural.yml | 9 ++++ styles/PaperMoon/LinkText.yml | 10 +++++ styles/PaperMoon/NoEmoji.yml | 15 +++++++ styles/PaperMoon/NoExclamation.yml | 6 +++ styles/PaperMoon/Placeholders.yml | 8 ++++ styles/PaperMoon/Terminology.yml | 15 +++++++ .../config/vocabularies/PaperMoon/accept.txt | 37 ++++++++++++++++ 12 files changed, 243 insertions(+) create mode 100644 .github/workflows/vale.yml create mode 100644 .vale.ini create mode 100644 AGENTS.md create mode 100644 styles/PaperMoon/BannedPhrases.yml create mode 100644 styles/PaperMoon/DiscouragedPhrases.yml create mode 100644 styles/PaperMoon/FirstPersonPlural.yml create mode 100644 styles/PaperMoon/LinkText.yml create mode 100644 styles/PaperMoon/NoEmoji.yml create mode 100644 styles/PaperMoon/NoExclamation.yml create mode 100644 styles/PaperMoon/Placeholders.yml create mode 100644 styles/PaperMoon/Terminology.yml create mode 100644 styles/config/vocabularies/PaperMoon/accept.txt diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 000000000..e2456ec87 --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,40 @@ +name: Vale style check + +on: + pull_request: + paths: + - "**.md" + - ".vale.ini" + - "styles/**" + - ".github/workflows/vale.yml" + +permissions: + contents: read + pull-requests: read + +jobs: + vale: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: List changed markdown files + id: changed + run: | + base="${{ github.event.pull_request.base.sha }}" + head="${{ github.event.pull_request.head.sha }}" + files=$(git diff --name-only --diff-filter=AM "$base...$head" -- '*.md' | tr '\n' ' ') + echo "files=$files" >> "$GITHUB_OUTPUT" + echo "Changed markdown files: $files" + + - name: Run Vale on changed files + if: steps.changed.outputs.files != '' + uses: errata-ai/vale-action@reviewdog + with: + files: ${{ steps.changed.outputs.files }} + fail_on_error: true + reporter: github-pr-review + filter_mode: added + token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 000000000..b2d0365c2 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,21 @@ +StylesPath = styles +MinAlertLevel = suggestion +Vocab = PaperMoon + +# Rules mirrored from papermoonio/documentation-style-guide. When that +# repo updates, refresh this directory in lockstep. +# +# To also lint against Google's style, run `vale sync` after adding: +# Packages = Google +# then add `Google` to the BasedOnStyles list below. + +[*.md] +BasedOnStyles = Vale, PaperMoon + +TokenIgnores = (?:dApp|TestNet|MainNet|ERC-\d+|JSON-RPC) +BlockIgnores = (?s) *(```.*?```) + +# AGENTS.md describes the rules and references banned content by name; +# it is not subject to its own rules. +[AGENTS.md] +BasedOnStyles = diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..e0c28addf --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,44 @@ +# AGENTS.md — polkadot-docs + +This file is loaded automatically by coding agents (Claude Code, Cursor, Codex, and any tool that respects the `AGENTS.md` convention) when they open this repository. Read it before generating or editing any documentation. + +## Style and authoring rules + +Documentation in this repository follows the **PaperMoon Documentation Style Guide**. The agent-loadable rule set lives in a separate repository so it can be shared across customers and updated independently: + +- **Canonical source**: [`papermoonio/documentation-style-guide/AGENTS.md`](https://github.com/papermoonio/documentation-style-guide/blob/main/AGENTS.md) +- **Prose reference**: [`papermoonio/documentation-style-guide/style-guide.md`](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md) +- **Reviewer checklist**: [`papermoonio/documentation-style-guide/checklist.md`](https://github.com/papermoonio/documentation-style-guide/blob/main/checklist.md) + +**Read the canonical `AGENTS.md` before authoring.** It front-loads the rules that AI-generated documentation most often violates — list punctuation, bold misuse, em dashes, banned phrases, terminology, code-identifier backticks, identifier consistency, image filenames, and the "no redundant subheadings above lead-in lists" rule. The pre-output checklist at the bottom of that file is the last thing to run before returning a draft. + +## Linting + +This repo ships a Vale configuration mirroring the PaperMoon styleguide's rules. Run locally: + +```bash +vale . +``` + +CI runs `vale` against changed markdown files on every pull request (see `.github/workflows/vale.yml`). + +## Project-specific rules + +These supplement (and where they conflict, override) the canonical styleguide: + +- **Customer override on heading case**: This site uses Chicago title case per the styleguide default. +- **`{target=\_blank}` on external links** is enforced. Same-page anchors do not take it. +- **Snippet includes**: Reusable code lives in `.snippets/code/` and is included via `--8<-- 'code/path/to/file.ext'`. Do not inline code that already exists as a snippet. +- **Variables**: `variables.yml` at the repo root holds shared version pins and identifiers. Reference via `{{ variable_name }}`. + +## Precedence + +When rules conflict: + +1. **This file** (`polkadot-docs/AGENTS.md`) — project-specific overrides win. +2. **PaperMoon canonical styleguide** — default. +3. **Google developer documentation style guide** — fallback for anything the PaperMoon guide does not cover. + +## How to use this in an agent session + +A typical session opens by reading this file, then fetching the canonical styleguide rules (the file at the GitHub URL above, or a local clone if present). Apply the rules during generation, not just at review time. Run the pre-output checklist from the canonical `AGENTS.md` before returning a draft. diff --git a/styles/PaperMoon/BannedPhrases.yml b/styles/PaperMoon/BannedPhrases.yml new file mode 100644 index 000000000..e6507b2d4 --- /dev/null +++ b/styles/PaperMoon/BannedPhrases.yml @@ -0,0 +1,19 @@ +extends: existence +message: "Don't use '%s'. See the Banned Phrases list in style-guide.md." +level: error +ignorecase: true +tokens: + - "\\betc\\." + - "in today's world" + - "in the modern era" + - "it's important to note" + - "it is important to note" + - "it's worth noting" + - "it is worth noting" + - "in summary" + - "in conclusion" + - "feel free to" + - "at the time of writing" + - "as of today" + - "delve into" + - "dive into" diff --git a/styles/PaperMoon/DiscouragedPhrases.yml b/styles/PaperMoon/DiscouragedPhrases.yml new file mode 100644 index 000000000..7d93fa5d1 --- /dev/null +++ b/styles/PaperMoon/DiscouragedPhrases.yml @@ -0,0 +1,19 @@ +extends: existence +message: "Consider rewriting without '%s' — often filler or LLM cliché." +level: warning +ignorecase: true +tokens: + - "\\bleverage\\b" + - "\\butilize\\b" + - "\\bseamless\\b" + - "\\bseamlessly\\b" + - "\\brobust\\b" + - "\\bpowerful\\b" + - "\\bcutting-edge\\b" + - "\\bstate-of-the-art\\b" + - "\\bunder the hood\\b" + - "\\bcurrently\\b" + - "\\bsimply\\b" + - "\\bjust\\b" + - "\\beasily\\b" + - "\\bobviously\\b" diff --git a/styles/PaperMoon/FirstPersonPlural.yml b/styles/PaperMoon/FirstPersonPlural.yml new file mode 100644 index 000000000..700822a9a --- /dev/null +++ b/styles/PaperMoon/FirstPersonPlural.yml @@ -0,0 +1,9 @@ +extends: existence +message: "Avoid first-person plural ('%s'). Address the reader as 'you'." +level: warning +ignorecase: true +tokens: + - "\\bwe\\b" + - "\\bour\\b" + - "\\bus\\b" + - "\\blet's\\b" diff --git a/styles/PaperMoon/LinkText.yml b/styles/PaperMoon/LinkText.yml new file mode 100644 index 000000000..c66065780 --- /dev/null +++ b/styles/PaperMoon/LinkText.yml @@ -0,0 +1,10 @@ +extends: existence +message: "Use descriptive link text. Avoid generic words like '%s' inside link text." +level: error +scope: text +tokens: + - '\[here\]\(' + - '\[click here\]\(' + - '\[this\]\(' + - '\[read more\]\(' + - '\[learn more\]\(' diff --git a/styles/PaperMoon/NoEmoji.yml b/styles/PaperMoon/NoEmoji.yml new file mode 100644 index 000000000..fc4475587 --- /dev/null +++ b/styles/PaperMoon/NoEmoji.yml @@ -0,0 +1,15 @@ +extends: existence +message: "Do not use emojis in documentation. Use 'Do:' / 'Don't:' labels instead of colored markers." +level: error +nonword: true +tokens: + - '[\x{1F300}-\x{1F6FF}]' + - '[\x{1F900}-\x{1F9FF}]' + - '[\x{2600}-\x{26FF}]' + - '[\x{2700}-\x{27BF}]' + - '[\x{1F000}-\x{1F02F}]' + - '✅' + - '❌' + - '🟢' + - '🔴' + - '⚠️' diff --git a/styles/PaperMoon/NoExclamation.yml b/styles/PaperMoon/NoExclamation.yml new file mode 100644 index 000000000..48a60487e --- /dev/null +++ b/styles/PaperMoon/NoExclamation.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Avoid exclamation marks in formal writing." +level: warning +nonword: true +tokens: + - '\w+!(?!\[)' diff --git a/styles/PaperMoon/Placeholders.yml b/styles/PaperMoon/Placeholders.yml new file mode 100644 index 000000000..7d20e9a26 --- /dev/null +++ b/styles/PaperMoon/Placeholders.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Use INSERT_UPPER_SNAKE_CASE placeholders that describe the value. Avoid '%s'." +level: warning +ignorecase: false +tokens: + - "YOUR_[A-Z_]+_HERE" + - "INSERT_[A-Z_]+_HERE" + - "" diff --git a/styles/PaperMoon/Terminology.yml b/styles/PaperMoon/Terminology.yml new file mode 100644 index 000000000..01da20ff9 --- /dev/null +++ b/styles/PaperMoon/Terminology.yml @@ -0,0 +1,15 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +level: error +ignorecase: false +swap: + '\betc\.': "and more" + '\bdapp\b': dApp + '\bDApp\b': dApp + '\btestnet\b': TestNet + '\btest net\b': TestNet + '\bmainnet\b': MainNet + '\bmain net\b': MainNet + '\bERC(\d+)\b': "ERC-$1" + '\bJSON RPC\b': JSON-RPC + '\bJSONRPC\b': JSON-RPC diff --git a/styles/config/vocabularies/PaperMoon/accept.txt b/styles/config/vocabularies/PaperMoon/accept.txt new file mode 100644 index 000000000..024dd610f --- /dev/null +++ b/styles/config/vocabularies/PaperMoon/accept.txt @@ -0,0 +1,37 @@ +dApp +dApps +TestNet +TestNets +MainNet +MainNets +PaperMoon +Polkadot +Kusama +Moonbeam +Moonriver +Moonbase +parachain +parachains +relay chain +Substrate +JSON-RPC +Web3 +EVM +WASM +testnet +mainnet +repo +repos +repository +repositories +markdownlint +MkDocs +mkdocs +devcontainer +runnable +hyperlink +hyperlinks +backslash +kebab +linter +lintable From 51e405c97aa6326b3eae2a52023bf8b9adfb76cd Mon Sep 17 00:00:00 2001 From: Bruno Galvao Date: Sat, 23 May 2026 08:03:20 +0700 Subject: [PATCH 2/5] Pull Vale rules from canonical styleguide at CI time MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Eliminates the duplicated rule files this PR previously carried: styles/PaperMoon/*.yml and styles/config/vocabularies/PaperMoon/accept.txt were copies of the canonical files in papermoonio/documentation-style-guide, so the lint rules drifted any time the canonical updated. Architecture now: - scripts/sync-styleguide-vale.sh clones the styleguide repo and copies styles/PaperMoon/ and the PaperMoon vocab into local styles/ before linting. Run it locally before `vale .`; CI runs it automatically. - .gitignore excludes the synced directories so they are never committed. - styles/config/vocabularies/Polkadot/accept.txt holds the project's own vocab (Polkadot, Kusama, Paseo, parachain, etc.) — these are ecosystem-specific terms that the canonical PaperMoon vocab intentionally does not carry. - .vale.ini now loads both vocabs (Vocab = PaperMoon, Polkadot) and references the synced styles directory. - .github/workflows/vale.yml adds a sync step before invoking Vale. Result: the canonical PaperMoon styleguide repo is the only place PaperMoon lint rules live. polkadot-docs carries only what is genuinely project-specific (Polkadot vocab, project overrides, the CI workflow). --- .github/workflows/vale.yml | 6 ++- .gitignore | 6 +++ .vale.ini | 9 +++-- AGENTS.md | 9 +++-- scripts/sync-styleguide-vale.sh | 35 +++++++++++++++++ styles/PaperMoon/BannedPhrases.yml | 19 --------- styles/PaperMoon/DiscouragedPhrases.yml | 19 --------- styles/PaperMoon/FirstPersonPlural.yml | 9 ----- styles/PaperMoon/LinkText.yml | 10 ----- styles/PaperMoon/NoEmoji.yml | 15 ------- styles/PaperMoon/NoExclamation.yml | 6 --- styles/PaperMoon/Placeholders.yml | 8 ---- styles/PaperMoon/Terminology.yml | 15 ------- .../config/vocabularies/PaperMoon/accept.txt | 37 ------------------ .../config/vocabularies/Polkadot/accept.txt | 39 +++++++++++++++++++ 15 files changed, 97 insertions(+), 145 deletions(-) create mode 100755 scripts/sync-styleguide-vale.sh delete mode 100644 styles/PaperMoon/BannedPhrases.yml delete mode 100644 styles/PaperMoon/DiscouragedPhrases.yml delete mode 100644 styles/PaperMoon/FirstPersonPlural.yml delete mode 100644 styles/PaperMoon/LinkText.yml delete mode 100644 styles/PaperMoon/NoEmoji.yml delete mode 100644 styles/PaperMoon/NoExclamation.yml delete mode 100644 styles/PaperMoon/Placeholders.yml delete mode 100644 styles/PaperMoon/Terminology.yml delete mode 100644 styles/config/vocabularies/PaperMoon/accept.txt create mode 100644 styles/config/vocabularies/Polkadot/accept.txt diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index e2456ec87..2b49ff233 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -5,7 +5,8 @@ on: paths: - "**.md" - ".vale.ini" - - "styles/**" + - "styles/config/vocabularies/Polkadot/**" + - "scripts/sync-styleguide-vale.sh" - ".github/workflows/vale.yml" permissions: @@ -20,6 +21,9 @@ jobs: with: fetch-depth: 0 + - name: Sync canonical Vale rules from the PaperMoon styleguide + run: ./scripts/sync-styleguide-vale.sh + - name: List changed markdown files id: changed run: | diff --git a/.gitignore b/.gitignore index b7d7669c7..2c9ccd39c 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,9 @@ scripts/__pycache__/* .github/instructions/kluster-code-verify.instructions.md .kluster + +# Vale rules and vocab synced from papermoonio/documentation-style-guide +# by scripts/sync-styleguide-vale.sh (CI runs the script before linting). +# The canonical repo is the single source of truth — never commit copies. +styles/PaperMoon/ +styles/config/vocabularies/PaperMoon/ diff --git a/.vale.ini b/.vale.ini index b2d0365c2..d9c5c2e01 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,9 +1,12 @@ StylesPath = styles MinAlertLevel = suggestion -Vocab = PaperMoon +Vocab = PaperMoon, Polkadot -# Rules mirrored from papermoonio/documentation-style-guide. When that -# repo updates, refresh this directory in lockstep. +# Vale rules and the PaperMoon vocab in styles/PaperMoon/ and +# styles/config/vocabularies/PaperMoon/ are synced from the canonical +# papermoonio/documentation-style-guide repo and are gitignored. +# Run `./scripts/sync-styleguide-vale.sh` before linting locally; +# CI runs the script automatically (see .github/workflows/vale.yml). # # To also lint against Google's style, run `vale sync` after adding: # Packages = Google diff --git a/AGENTS.md b/AGENTS.md index e0c28addf..de4da0ea3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,13 +14,16 @@ Documentation in this repository follows the **PaperMoon Documentation Style Gui ## Linting -This repo ships a Vale configuration mirroring the PaperMoon styleguide's rules. Run locally: +Vale rules and the PaperMoon vocab are not copied into this repo — they are pulled from the canonical [`papermoonio/documentation-style-guide`](https://github.com/papermoonio/documentation-style-guide) repo on every CI run, and on demand for local linting. The single source of truth is the styleguide repo. ```bash -vale . +./scripts/sync-styleguide-vale.sh # pull canonical Vale rules + PaperMoon vocab +vale . # lint ``` -CI runs `vale` against changed markdown files on every pull request (see `.github/workflows/vale.yml`). +The `styles/PaperMoon/` and `styles/config/vocabularies/PaperMoon/` directories are gitignored. Project-specific vocab lives in `styles/config/vocabularies/Polkadot/` and is committed. + +CI runs the sync script and then Vale against changed markdown files on every pull request (see `.github/workflows/vale.yml`). ## Project-specific rules diff --git a/scripts/sync-styleguide-vale.sh b/scripts/sync-styleguide-vale.sh new file mode 100755 index 000000000..8b7cbdd4a --- /dev/null +++ b/scripts/sync-styleguide-vale.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +# Sync canonical Vale rules and the PaperMoon vocab from the +# papermoonio/documentation-style-guide repository into this repo's +# styles/ directory. The synced files are gitignored — the canonical +# repo is the single source of truth. +# +# Usage: +# ./scripts/sync-styleguide-vale.sh # sync from main +# ./scripts/sync-styleguide-vale.sh # sync from a branch, tag, or sha +# +# Project-specific vocab (styles/config/vocabularies/Polkadot/) is +# managed in this repo and is NOT overwritten. + +set -euo pipefail + +REPO=papermoonio/documentation-style-guide +REF=${1:-main} + +repo_root=$(git rev-parse --show-toplevel) +cd "$repo_root" + +tmpdir=$(mktemp -d) +trap 'rm -rf "$tmpdir"' EXIT + +echo "Cloning $REPO@$REF..." +git clone --depth=1 --branch="$REF" --quiet "https://github.com/$REPO" "$tmpdir/styleguide" + +mkdir -p styles/PaperMoon styles/config/vocabularies/PaperMoon + +cp "$tmpdir/styleguide"/styles/PaperMoon/*.yml styles/PaperMoon/ +cp "$tmpdir/styleguide"/styles/config/vocabularies/PaperMoon/accept.txt \ + styles/config/vocabularies/PaperMoon/accept.txt + +echo "Synced Vale rules and PaperMoon vocab from $REPO@$REF." +echo "Run 'vale .' to lint." diff --git a/styles/PaperMoon/BannedPhrases.yml b/styles/PaperMoon/BannedPhrases.yml deleted file mode 100644 index e6507b2d4..000000000 --- a/styles/PaperMoon/BannedPhrases.yml +++ /dev/null @@ -1,19 +0,0 @@ -extends: existence -message: "Don't use '%s'. See the Banned Phrases list in style-guide.md." -level: error -ignorecase: true -tokens: - - "\\betc\\." - - "in today's world" - - "in the modern era" - - "it's important to note" - - "it is important to note" - - "it's worth noting" - - "it is worth noting" - - "in summary" - - "in conclusion" - - "feel free to" - - "at the time of writing" - - "as of today" - - "delve into" - - "dive into" diff --git a/styles/PaperMoon/DiscouragedPhrases.yml b/styles/PaperMoon/DiscouragedPhrases.yml deleted file mode 100644 index 7d93fa5d1..000000000 --- a/styles/PaperMoon/DiscouragedPhrases.yml +++ /dev/null @@ -1,19 +0,0 @@ -extends: existence -message: "Consider rewriting without '%s' — often filler or LLM cliché." -level: warning -ignorecase: true -tokens: - - "\\bleverage\\b" - - "\\butilize\\b" - - "\\bseamless\\b" - - "\\bseamlessly\\b" - - "\\brobust\\b" - - "\\bpowerful\\b" - - "\\bcutting-edge\\b" - - "\\bstate-of-the-art\\b" - - "\\bunder the hood\\b" - - "\\bcurrently\\b" - - "\\bsimply\\b" - - "\\bjust\\b" - - "\\beasily\\b" - - "\\bobviously\\b" diff --git a/styles/PaperMoon/FirstPersonPlural.yml b/styles/PaperMoon/FirstPersonPlural.yml deleted file mode 100644 index 700822a9a..000000000 --- a/styles/PaperMoon/FirstPersonPlural.yml +++ /dev/null @@ -1,9 +0,0 @@ -extends: existence -message: "Avoid first-person plural ('%s'). Address the reader as 'you'." -level: warning -ignorecase: true -tokens: - - "\\bwe\\b" - - "\\bour\\b" - - "\\bus\\b" - - "\\blet's\\b" diff --git a/styles/PaperMoon/LinkText.yml b/styles/PaperMoon/LinkText.yml deleted file mode 100644 index c66065780..000000000 --- a/styles/PaperMoon/LinkText.yml +++ /dev/null @@ -1,10 +0,0 @@ -extends: existence -message: "Use descriptive link text. Avoid generic words like '%s' inside link text." -level: error -scope: text -tokens: - - '\[here\]\(' - - '\[click here\]\(' - - '\[this\]\(' - - '\[read more\]\(' - - '\[learn more\]\(' diff --git a/styles/PaperMoon/NoEmoji.yml b/styles/PaperMoon/NoEmoji.yml deleted file mode 100644 index fc4475587..000000000 --- a/styles/PaperMoon/NoEmoji.yml +++ /dev/null @@ -1,15 +0,0 @@ -extends: existence -message: "Do not use emojis in documentation. Use 'Do:' / 'Don't:' labels instead of colored markers." -level: error -nonword: true -tokens: - - '[\x{1F300}-\x{1F6FF}]' - - '[\x{1F900}-\x{1F9FF}]' - - '[\x{2600}-\x{26FF}]' - - '[\x{2700}-\x{27BF}]' - - '[\x{1F000}-\x{1F02F}]' - - '✅' - - '❌' - - '🟢' - - '🔴' - - '⚠️' diff --git a/styles/PaperMoon/NoExclamation.yml b/styles/PaperMoon/NoExclamation.yml deleted file mode 100644 index 48a60487e..000000000 --- a/styles/PaperMoon/NoExclamation.yml +++ /dev/null @@ -1,6 +0,0 @@ -extends: existence -message: "Avoid exclamation marks in formal writing." -level: warning -nonword: true -tokens: - - '\w+!(?!\[)' diff --git a/styles/PaperMoon/Placeholders.yml b/styles/PaperMoon/Placeholders.yml deleted file mode 100644 index 7d20e9a26..000000000 --- a/styles/PaperMoon/Placeholders.yml +++ /dev/null @@ -1,8 +0,0 @@ -extends: existence -message: "Use INSERT_UPPER_SNAKE_CASE placeholders that describe the value. Avoid '%s'." -level: warning -ignorecase: false -tokens: - - "YOUR_[A-Z_]+_HERE" - - "INSERT_[A-Z_]+_HERE" - - "" diff --git a/styles/PaperMoon/Terminology.yml b/styles/PaperMoon/Terminology.yml deleted file mode 100644 index 01da20ff9..000000000 --- a/styles/PaperMoon/Terminology.yml +++ /dev/null @@ -1,15 +0,0 @@ -extends: substitution -message: "Use '%s' instead of '%s'." -level: error -ignorecase: false -swap: - '\betc\.': "and more" - '\bdapp\b': dApp - '\bDApp\b': dApp - '\btestnet\b': TestNet - '\btest net\b': TestNet - '\bmainnet\b': MainNet - '\bmain net\b': MainNet - '\bERC(\d+)\b': "ERC-$1" - '\bJSON RPC\b': JSON-RPC - '\bJSONRPC\b': JSON-RPC diff --git a/styles/config/vocabularies/PaperMoon/accept.txt b/styles/config/vocabularies/PaperMoon/accept.txt deleted file mode 100644 index 024dd610f..000000000 --- a/styles/config/vocabularies/PaperMoon/accept.txt +++ /dev/null @@ -1,37 +0,0 @@ -dApp -dApps -TestNet -TestNets -MainNet -MainNets -PaperMoon -Polkadot -Kusama -Moonbeam -Moonriver -Moonbase -parachain -parachains -relay chain -Substrate -JSON-RPC -Web3 -EVM -WASM -testnet -mainnet -repo -repos -repository -repositories -markdownlint -MkDocs -mkdocs -devcontainer -runnable -hyperlink -hyperlinks -backslash -kebab -linter -lintable diff --git a/styles/config/vocabularies/Polkadot/accept.txt b/styles/config/vocabularies/Polkadot/accept.txt new file mode 100644 index 000000000..8f70b4088 --- /dev/null +++ b/styles/config/vocabularies/Polkadot/accept.txt @@ -0,0 +1,39 @@ +Polkadot +Kusama +Paseo +Westend +Moonbeam +Moonriver +Moonbase +parachain +parachains +parathread +parathreads +relay chain +relaychain +Substrate +collator +collators +nominator +nominators +validator +validators +extrinsic +extrinsics +pallet +pallets +runtime +runtimes +XCM +SDK +SS58 +Subxt +Dedot +Chopsticks +PAPI +Polkadot.js +omninode +Zombienet +Bulletin +ink +ScaleCodec From 251fd38936fe504306656110634cd4e2cfa46ad5 Mon Sep 17 00:00:00 2001 From: Bruno Galvao Date: Tue, 26 May 2026 09:14:34 +0700 Subject: [PATCH 3/5] Align target=_blank guidance with updated canonical styleguide papermoonio/documentation-style-guide#6 dropped the manual {target=\_blank} rule after review (the MkDocs plugin handles opening external links in a new tab automatically). The project-specific override in this file still said it was "enforced", which now contradicts canonical. Update to mirror the canonical guidance: the plugin handles it, do not add manually. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index de4da0ea3..2564b0552 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,7 +30,7 @@ CI runs the sync script and then Vale against changed markdown files on every pu These supplement (and where they conflict, override) the canonical styleguide: - **Customer override on heading case**: This site uses Chicago title case per the styleguide default. -- **`{target=\_blank}` on external links** is enforced. Same-page anchors do not take it. +- **External links open in a new tab**: this is handled by the MkDocs plugin configured for this site. Do not add `{target=\_blank}` manually — the canonical styleguide also drops the manual rule. - **Snippet includes**: Reusable code lives in `.snippets/code/` and is included via `--8<-- 'code/path/to/file.ext'`. Do not inline code that already exists as a snippet. - **Variables**: `variables.yml` at the repo root holds shared version pins and identifiers. Reference via `{{ variable_name }}`. From 6984f50074f5200a37e123d457e41c28b1ae6b3d Mon Sep 17 00:00:00 2001 From: Bruno Galvao Date: Fri, 29 May 2026 14:30:39 +0700 Subject: [PATCH 4/5] Disable Vale.Spelling; enforce house style only The spell-checker arrived with the base Vale style and flags an endless tail of valid tool/package names on a technical docs repo with no typo-catching benefit worth the vocab-curation toil. Keep the curated PaperMoon house-style rules plus Vale.Repetition and Vale.Terms. --- .vale.ini | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.vale.ini b/.vale.ini index d9c5c2e01..d23030b95 100644 --- a/.vale.ini +++ b/.vale.ini @@ -15,6 +15,13 @@ Vocab = PaperMoon, Polkadot [*.md] BasedOnStyles = Vale, PaperMoon +# Vale.Spelling (Hunspell) is disabled: this repo enforces house style, +# not spelling. On a deeply technical docs repo the spell-checker flags an +# endless tail of valid tool/package names (npm, toolchain, Turbopack, ...) +# with no typo-catching benefit worth the vocab-curation toil. The curated +# PaperMoon house-style rules and Vale.Repetition/Vale.Terms stay enabled. +Vale.Spelling = NO + TokenIgnores = (?:dApp|TestNet|MainNet|ERC-\d+|JSON-RPC) BlockIgnores = (?s) *(```.*?```) From 856468fbd9db439a8caac1482001161ff628f7b6 Mon Sep 17 00:00:00 2001 From: Bruno Galvao Date: Fri, 29 May 2026 14:50:49 +0700 Subject: [PATCH 5/5] Address review: non-blocking Vale check + move sync script to .github/scripts - Vale CI is now advisory (fail_on_error: false, reporter github-pr-check): findings surface in the Checks tab instead of blocking merge or posting inline review comments. Still reruns on every push so the check status tracks the latest commit. Addresses noise concerns from the prior Vale run (polkadot-developers/polkadot-docs#38). - Move sync-styleguide-vale.sh from scripts/ to .github/scripts/ alongside the other CI scripts; update all references. --- {scripts => .github/scripts}/sync-styleguide-vale.sh | 4 ++-- .github/workflows/vale.yml | 12 ++++++++---- .gitignore | 2 +- .vale.ini | 2 +- AGENTS.md | 2 +- 5 files changed, 13 insertions(+), 9 deletions(-) rename {scripts => .github/scripts}/sync-styleguide-vale.sh (86%) diff --git a/scripts/sync-styleguide-vale.sh b/.github/scripts/sync-styleguide-vale.sh similarity index 86% rename from scripts/sync-styleguide-vale.sh rename to .github/scripts/sync-styleguide-vale.sh index 8b7cbdd4a..ad190256c 100755 --- a/scripts/sync-styleguide-vale.sh +++ b/.github/scripts/sync-styleguide-vale.sh @@ -5,8 +5,8 @@ # repo is the single source of truth. # # Usage: -# ./scripts/sync-styleguide-vale.sh # sync from main -# ./scripts/sync-styleguide-vale.sh # sync from a branch, tag, or sha +# ./.github/scripts/sync-styleguide-vale.sh # sync from main +# ./.github/scripts/sync-styleguide-vale.sh # sync from a branch, tag, or sha # # Project-specific vocab (styles/config/vocabularies/Polkadot/) is # managed in this repo and is NOT overwritten. diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index 2b49ff233..37e838b51 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -6,11 +6,12 @@ on: - "**.md" - ".vale.ini" - "styles/config/vocabularies/Polkadot/**" - - "scripts/sync-styleguide-vale.sh" + - ".github/scripts/sync-styleguide-vale.sh" - ".github/workflows/vale.yml" permissions: contents: read + checks: write pull-requests: read jobs: @@ -22,7 +23,7 @@ jobs: fetch-depth: 0 - name: Sync canonical Vale rules from the PaperMoon styleguide - run: ./scripts/sync-styleguide-vale.sh + run: ./.github/scripts/sync-styleguide-vale.sh - name: List changed markdown files id: changed @@ -38,7 +39,10 @@ jobs: uses: errata-ai/vale-action@reviewdog with: files: ${{ steps.changed.outputs.files }} - fail_on_error: true - reporter: github-pr-review + # Advisory only: surface findings in the Checks tab without blocking + # merge or spamming inline review comments. Reruns on every push, so + # the check status always reflects the latest commit. + fail_on_error: false + reporter: github-pr-check filter_mode: added token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index 2c9ccd39c..b0338f86e 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,7 @@ scripts/__pycache__/* .kluster # Vale rules and vocab synced from papermoonio/documentation-style-guide -# by scripts/sync-styleguide-vale.sh (CI runs the script before linting). +# by .github/scripts/sync-styleguide-vale.sh (CI runs the script before linting). # The canonical repo is the single source of truth — never commit copies. styles/PaperMoon/ styles/config/vocabularies/PaperMoon/ diff --git a/.vale.ini b/.vale.ini index d23030b95..cd94bdbe0 100644 --- a/.vale.ini +++ b/.vale.ini @@ -5,7 +5,7 @@ Vocab = PaperMoon, Polkadot # Vale rules and the PaperMoon vocab in styles/PaperMoon/ and # styles/config/vocabularies/PaperMoon/ are synced from the canonical # papermoonio/documentation-style-guide repo and are gitignored. -# Run `./scripts/sync-styleguide-vale.sh` before linting locally; +# Run `./.github/scripts/sync-styleguide-vale.sh` before linting locally; # CI runs the script automatically (see .github/workflows/vale.yml). # # To also lint against Google's style, run `vale sync` after adding: diff --git a/AGENTS.md b/AGENTS.md index 2564b0552..0db584a43 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ Documentation in this repository follows the **PaperMoon Documentation Style Gui Vale rules and the PaperMoon vocab are not copied into this repo — they are pulled from the canonical [`papermoonio/documentation-style-guide`](https://github.com/papermoonio/documentation-style-guide) repo on every CI run, and on demand for local linting. The single source of truth is the styleguide repo. ```bash -./scripts/sync-styleguide-vale.sh # pull canonical Vale rules + PaperMoon vocab +./.github/scripts/sync-styleguide-vale.sh # pull canonical Vale rules + PaperMoon vocab vale . # lint ```