ci: deterministic docs checks to replace Mintlify Automate workflows by alexander-sei · Pull Request #15 · sei-protocol/sei-docs

alexander-sei · 2026-05-30T23:19:51Z

What

Replaces the deterministic Mintlify "Automate" workflows with free, no-AI GitHub Actions. Anything that doesn't need an LLM to judge or write shouldn't cost AI credits — link-checking, spelling, SEO-metadata auditing, and style-guide rules are all deterministic.

Every config here was tuned by running the actual tool over our content, not written blind.

Checks added

Workflow	Replaces	Behavior
`spelling.yml` + `_typos.toml`	"Fix grammar & typos" (spelling)	Blocks PRs — high precision
`prose-style.yml` + `.vale.ini` + `.github/styles/Sei`	"Apply style guide" + grammar	Advisory — annotates changed lines only, never blocks
`seo-audit.yml` + `scripts/audit-seo.mjs`	"Audit SEO metadata"	Blocks only on missing title/description
`external-links.yml` + `lychee.toml`	gap beside `mint broken-links`	Scheduled — opens an issue on external link rot

The Vale rules come straight from AGENTS.md and STYLE_GUIDE.md (terminology like "gas fees" → "gas", CW → CosmWasm, sentence-case headings, qualifying language).
The SEO audit reuses the docs.json navigation walk from scripts/generate-llms.mjs, so it only checks published pages.
external-links.yml checks only external hosts (blog.sei.io, dashboard.sei.io, third-party); internal links remain mint broken-links' job.

Verification (run locally over the full repo)

typos: found 5 real typos, 1 false positive. Three hand-written ones are fixed in this PR; maxiumum and UPnP are allowlisted because they come from the auto-generated seid config block in node/node-operators.mdx (fixing them would be reverted by sync-default-configs.yml).
SEO audit: 0 errors, 67 advisory warnings across 132 pages — every published page already has title + description, so the gate only prevents regressions.
Vale: 0 errors (advisory only). Scoped to changed lines because the docs carry a ~1,345-heading Title Case backlog; full-repo gating would be pure noise.
All workflows pass YAML validation.

Typo fixes included

Surfaced by the new spelling check (kept in a separate commit):

node/statesync.mdx: sycing → syncing
evm/reference.mdx: hexdecimal → hexadecimal
evm/evm-verify-contracts.mdx: Prerequsite → Prerequisite

After merge — Mintlify toggles to turn off

Fix broken links (already covered), Audit SEO metadata, Fix grammar & typos, Apply style guide. The two "Draft improvements from assistant conversations / user feedback" workflows stay on Mintlify — their data lives in the platform and genuinely needs AI.

Notes

crate-ci/typos@master is unpinned (Mintlify's docs recommend it that way); can pin to a SHA if preferred.
external-links.yml runs weekly and opens a fresh issue each failing week; easy to switch to monthly or a rolling issue.
Changelog generation was intentionally dropped — not a fit for this repo.

🤖 Generated with Claude Code

Free, no-AI GitHub Actions replacing the deterministic Mintlify Automate workflows: - spelling.yml + _typos.toml: spell-check on PRs (blocking; high precision) - prose-style.yml + .vale.ini + .github/styles/Sei: style-guide and grammar linting derived from AGENTS.md and STYLE_GUIDE.md (advisory, changed lines only, so the existing heading backlog doesn't create noise) - seo-audit.yml + scripts/audit-seo.mjs: title/description + page-structure audit over docs.json pages (blocks only on missing metadata) - external-links.yml + lychee.toml: scheduled external link-rot check that opens an issue; complements the existing mint broken-links workflow Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Surfaced by the new typos check: - node/statesync.mdx: sycing -> syncing - evm/reference.mdx: hexdecimal -> hexadecimal - evm/evm-verify-contracts.mdx: Prerequsite -> Prerequisite Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

cursor · 2026-05-30T23:19:57Z

PR Summary

Low Risk
Changes are docs-site CI, lint configs, and minor MDX typo fixes; no runtime or application code paths.

Overview
Adds deterministic GitHub Actions for docs quality so spelling, style, SEO, and external link rot no longer depend on Mintlify Automate / AI credits.

CI & config: New workflows run typos (spelling.yml + _typos.toml, blocks PRs), Vale on changed lines only (prose-style.yml, .vale.ini, custom Sei rules + vocab — advisory), SEO audit via new scripts/audit-seo.mjs walking docs.json (fails on missing title/description only), and weekly lychee external link checks that open a tracking issue (external-links.yml + lychee.toml). Deprecated cosmos-sdk/** is excluded from Vale and link checks where noted.

Content fixes: Three typos in MDX (Prerequisite, hexadecimal, syncing) plus typos allowlists for generated config (UPnP, maxiumum).

^{Reviewed by Cursor Bugbot for commit fc0ec5d. Bugbot is set up for automated code reviews on this repo. Configure here.}

mintlify · 2026-05-30T23:20:32Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
sei-docs	🟢 Ready	View Preview	May 30, 2026, 11:21 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

cursor

Cursor Bugbot has reviewed your changes using default effort and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fc0ec5d. Configure here.}

cursor · 2026-05-30T23:28:56Z

+      - uses: actions/checkout@v4
+
+      - name: Check spelling
+        uses: crate-ci/typos@master


Unpinned GitHub Action uses mutable branch reference

Medium Severity

crate-ci/typos@master is pinned to a mutable branch, not a specific commit SHA or release tag. Any push to the upstream master branch — including a supply-chain compromise — would automatically execute in this repo's CI. The crate-ci/typos docs themselves recommend pinning to a version tag (e.g., @v1.45.0). The PR description acknowledges this but defers the fix, leaving the window open.

^{Reviewed by Cursor Bugbot for commit fc0ec5d. Configure here.}

cursor · 2026-05-30T23:28:56Z

+	}
+	walk(navigation);
+	return Array.from(new Set(pages));
+}


Duplicated collectPages function across two scripts

Low Severity

The collectPages function in audit-seo.mjs is a verbatim copy of the identical function in scripts/generate-llms.mjs. If the docs.json navigation structure evolves (e.g., a new key is added alongside pages/groups/tabs), the fix would need to be applied in both places independently. Extracting it into a shared utility module would keep them in sync.

^{Reviewed by Cursor Bugbot for commit fc0ec5d. Configure here.}

cursor · 2026-05-30T23:28:56Z

+tokens:
+  - 'click here'
+  - '\[here\]\('
+  - '\[this link\]\('


Vale existence tokens can't match raw markdown syntax

Low Severity

The tokens '\[here\]\(' and '\[this link\]\(' attempt to match raw markdown link syntax like [here](url). However, Vale's existence extension operates on the processed text scope by default, not raw markup. Vale strips markdown syntax before matching, so the brackets and parentheses in these patterns will never appear in the text being checked, making both tokens effectively dead. The first token 'click here' works fine since it's plain text. To catch standalone [here](…) links, a scope: raw directive or a different rule extension would be needed.

^{Reviewed by Cursor Bugbot for commit fc0ec5d. Configure here.}

alexander-sei and others added 2 commits May 31, 2026 02:19

docs: fix three spelling typos

fc0ec5d

Surfaced by the new typos check: - node/statesync.mdx: sycing -> syncing - evm/reference.mdx: hexdecimal -> hexadecimal - evm/evm-verify-contracts.mdx: Prerequsite -> Prerequisite Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

mintlify Bot deployed to staging May 30, 2026 23:21 View deployment

cursor Bot reviewed May 30, 2026

View reviewed changes

alexander-sei merged commit a3256ca into main May 31, 2026
10 checks passed

alexander-sei deleted the ci/deterministic-docs-checks branch May 31, 2026 09:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ci: deterministic docs checks to replace Mintlify Automate workflows#15

ci: deterministic docs checks to replace Mintlify Automate workflows#15
alexander-sei merged 2 commits into
mainfrom
ci/deterministic-docs-checks

alexander-sei commented May 30, 2026

Uh oh!

cursor Bot commented May 30, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented May 30, 2026 •

edited

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot May 30, 2026

Uh oh!

cursor Bot May 30, 2026

Uh oh!

cursor Bot May 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

alexander-sei commented May 30, 2026

What

Checks added

Verification (run locally over the full repo)

Typo fixes included

After merge — Mintlify toggles to turn off

Notes

Uh oh!

cursor Bot commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

mintlify Bot commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot May 30, 2026

Choose a reason for hiding this comment

Unpinned GitHub Action uses mutable branch reference

Uh oh!

cursor Bot May 30, 2026

Choose a reason for hiding this comment

Duplicated collectPages function across two scripts

Uh oh!

cursor Bot May 30, 2026

Choose a reason for hiding this comment

Vale existence tokens can't match raw markdown syntax

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

cursor Bot commented May 30, 2026 •

edited

Loading

mintlify Bot commented May 30, 2026 •

edited

Loading

Duplicated `collectPages` function across two scripts