Repository navigation
docs: Lint page structure with manni, restructure every docs page by type, and embed integration procedures as partials - #1177
Merged
Conversation
promptless
Bot
requested review from
adit-chandra,
frances720,
hawkeyexl and
mattlink
as code owners
October 19, 2026 21:30
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Oct 20, 2026
This was referenced Oct 20, 2026
| <Aside type="note"> | ||
| If your Vale config references external style packages (like Microsoft, Google, or write-good), Promptless downloads them automatically. This happens the first time it lints during a session. | ||
| </Aside> | ||
| 3. In **Vale config path**, enter the repo-relative path to your Vale configuration file, such as `.vale.ini` or `docs/.vale.ini`. |
Contributor
Author
There was a problem hiding this comment.
Citation
The Vale config path field sits under a doc collection's More filters (optional) expander on the Configuration page's Doc collections tab.
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposed changes
Pages now carry a doc type in their
type:frontmatter. This PR checks each page's structure against the template for its type, usingmanni lint structure. It restructures and edits every docs page so all 132 pass: fifteen of the worst-failing pages in three passes of five, then the remaining 117 in one pass, with each page's type re-assessed. Review passes retype five pages as how-to guides and move every integration's connection procedure into shared MDX partials. The PR pins manni 4.13.0.Lint integration
manni.config.yamlgets alint:section. Pages route bytype:to manni's built-in Good Docs Project templates (tgdp:*:1.6). The four types the site uses that manni has no template for are mapped:installation-guideandquickstartto how-to, andglossaryandcontact-supportto reference.manni.ymlgets astructurejob. On a PR it lints only the docs pages the PR adds or changes, and annotates them inline. Onmainit lints every page. Both steps are advisory (continue-on-error), so the job never blocks a merge. The existingvalidatejob is unchanged.npm run lint:structureruns the lint locally. AGENTS.md documents it and notes thatnpx manni checknow includes the structure job. ADR 0006 records the decision.Baseline (measured with manni 4.12.2): with this config, 131 of 132 pages fail on
main, with 415 findings. Most findings arereferenceH2 sections with no table (the TGDP reference template wants a table in every entry section after the first) andconceptpages with noUse casessection. With this PR, all 132 pages pass, with 0 findings. To make structure findings block PRs, removecontinue-on-errorfrom the PR step.First pass (5 pages). These are the pages with the most findings, apart from ones that already had three or more open suggestions editing them.
reference/integrations/github-enterprise.mdx(11 findings): retyped fromreferencetohow-to, because the page is a nine-step procedure. It gains Overview, Before you start, and See also sections. Permissions and webhook events are now tables, replacing four per-permission screenshots. Hostname requirements move into the prerequisites. "Whitelist" becomes "allow list".connect/triggers/github-commits.mdx(7): reference tables for use cases, commit vs. PR triggers, match-clause fields, and publishing options. The#auto-merge-modeanchor is kept.connect/triggers/slack-messages.mdx(7): tables for trigger methods, attachments, reply modes, channel types, and what Promptless reads. The duplicate Configuration section is merged into Passive channel listening. The#thread-reply-trigger-modeanchor is kept.governance/reference/pig-cli-reference.mdx(7): option tables for every command, and a cause table for failed commands. Fixes a stale fact:pig init --orgis now required. It no longer defaults toPromptless(Require customer organization when initializing a hub pig-toolchain#93).security/how-promptless-uses-ai.mdx(7): the data-handling, least-privilege, and enterprise points are now scannable tables, each with its source link.last-updatedis restamped withnpx manni meta derive --fields last-updatedon only the edited pages.Second pass (5 pages). These are the next-worst pages, and they include pages that other open suggestions also edit. Those suggestions need a rebase after this merges.
governance/start-here/key-concepts.mdx(12 findings): the 15 one-term sections are now four groups (hub content; builds, releases, and updates; hosts and trace collection; analysis and remediation). Each group opens with a Term and Definition table. Details and examples sit in H3s that keep the old heading anchors.connect/triggers/github-prs.mdx(12): tables for trigger modes, match-clause fields, which PRs trigger a review, publishing options, and where an@promptlessmention works. The redundant "How it works" overview is removed. Fixes stale facts:trigger_onis required (openedwas labeled the default), the topics filter's current dashboard label, and draft PRs, where a mention in the title or description still starts work.connect/doc-locations/github-repos.mdx(12): 12 thin sections become 7, with tables for supported platforms, doc collection settings, path scope, PR publishing behaviors, Slack link labels, and FAQ. Fixes stale facts: admins can edit doc collection settings, including the repository, in the dashboard. The page also gets the repository picker's current empty message, mdBook and Sphinx in the platform list, and auto-merge for PR-triggered docs PRs.#supported-platformsnow exists, so two existing links to it resolve.connect/triggers/gitlab-merge-requests.mdx(11): tables for match-clause fields (addsbranches), webhook status colors, publishing options, and what a comment mention does. Fixes "opened or updated" to "opens or merges", the GitLab events a trigger acts on.reference/integrations/gitlab.mdx(9): tables for capabilities by host, token requirements, webhook events, and FAQ. Fixes the trigger events, the Refresh access control name, and the stale directory-trigger steps. It also removes a claim that webhooks can be customized.The second pass keeps every heading that other pages link to, except
#supported-docs-platforms(no inbound links).Third pass: five pages retyped as how-to guides (review feedback). Per review,
connect/triggers/github-commits.mdx,github-prs.mdx,gitlab-merge-requests.mdx,slack-messages.mdx, andreference/integrations/gitlab.mdxchange fromtype: referencetotype: how-to. Each now follows the TGDP how-to template, likegithub-enterprise.mdx: Overview, Before you start, task sections with verb headings, and See also. The trigger pages'referencetag becomesguide, matchingjira-automation.mdx. All five passmanni lint structure.slack-messages.mdx: tasks for requesting docs from a thread, replying in a thread Promptless is in, changing the thread reply trigger mode, and setting up passive channel listening.gitlab.mdx: token requirements and token scope considerations move into Before you start. Installation becomes an eight-step "Connect a GitLab group" procedure. Merge request triggers, publishing, and the FAQ (now "Fix common connection problems") follow as tasks.github-commits#auto-merge-mode→#turn-on-auto-merge-mode,github-prs#trigger-modes→#choose-trigger-modes,#directory-specific-triggers→#limit-a-trigger-to-specific-directories,#repository-topics→#limit-a-trigger-to-tagged-repositories,gitlab-merge-requests#webhook-delivery-status→#check-webhook-delivery-status,#comment-mention-acknowledgment→#confirm-promptless-saw-your-mention,slack-messages#thread-reply-trigger-mode→#change-the-thread-reply-trigger-mode, andgitlab#source-code-reading→#overview. The links live in seven docs pages (restamped) and three changelog entries.Fourth pass: integration procedures as shared partials (review feedback). The Reference > Integrations pages were mostly procedures, so each connection procedure now lives in one MDX partial and is embedded where readers need it. Partials use Starlight and Astro's standard mechanism: import an MDX file as a component. ADR 0007 records the decision.
src/partials/integrations/)github-connect.mdxgithub-read-only-connect.mdxgitlab-connect.mdxslack-connect.mdxmicrosoft-teams-connect.mdxatlassian-connect.mdxlinear-connect.mdxlaunchdarkly-connect.mdxvercel-connect.mdxsidebar.hiddenwould also have dropped them from search, the sitemap, andllms.txt. Each integration page embeds the same partial in place of its own steps.src/lib/mdx-partials.tsinlines partials for the two raw-source readers: the/<page>.mdendpoint and the MCPget_pageindex (newtransformContentoption).tests/unit/mdx-partials.spec.tscovers it.@partials/*is aliased intsconfig.jsonand the Vite config.#installationon the integration pages, and#setup-instructionson the GitHub issues, GitLab projects, and context-source pages. One changelog link toslack#when-admin-approval-is-requirednow points toslack-messages#connect-slack.verify. The page now includes the Slack setup steps and passes.Fifth pass: no
type: referenceoutside the reference sections (review feedback). 35 pages outsidedocs/for-docs/reference/anddocs/governance/reference/change type. Only thetype:line changes, except on the two pages below that this PR had already brought to passing.how-to(26): the context-source pages (Confluence, Google Drive, Jira, Linear, Notion, Slite), GitHub repos, GitLab projects, the API, GitHub issues, Jira, LaunchDarkly, MCP, and Schedule triggers, Referral program, Environment variables, Single sign-on, Starport analytics, Configure Starport, Starport connections, the governance Compute and sizing, Model providers, Networking and identity, Object storage, and PostgreSQL pages, and Marketing images.concept(9): Access and permissions, Compliance and certifications, Data handling and classification, How Promptless uses AI, Network architecture, Privacy policy, Secrets and sensitive data, What's included in Starport, and Trust and data model.type: referenceoutside a reference section, because each is a lookup page:governance/deploy-the-worker/configuration-reference.mdx,governance/deploy-the-worker/manual-helm-reference.mdx,security/subprocessors.mdx,media-kit.mdx, andinternal/component-fixtures.mdx. Each needs a decision: move it into a reference section (new URL and redirect) or keep it where it is.type:line on these pages. 17 open suggestions edit 13 of them elsewhere, so the merges should be clean.Sixth pass: remove the Linear Google sign-in screenshot (review feedback).
public/assets/linear-auth.pngshowed a Promptless employee's email address and profile photo. This PR deletes it and removes it fromlinear-connect.mdx. The Linear sign-in screenshot (linear-signin.png) stays. PR #1180 removes the same image frommainso it leaves the live site without waiting on this PR. If #1180 merges first, resolve thereference/integrations/linear.mdxconflict here by keeping this PR's version.Merge from
main(#1180). The merge commit keeps this PR'sreference/integrations/linear.mdx, and manni 4.12.2 misreads a merge like that as an uncommitted body change, sovalidatefailed. A follow-up commit touches the page and keepslast-updated: 2026-10-19, so manni traces the page's history correctly andvalidatepasses.Seventh pass: manni 4.13.0 and the next five pages (dashboard task).
@hawkeyexl/mannigoes from 4.12.2 to 4.13.0. Each structure finding now names the template section it breaks and what that section is for, andnpx manni lint templates show <template>lists every section with its purpose. AGENTS.md points authors to it. The upgrade doesn't change any counts: 250 findings across 120 pages before this pass.meta validatepasses on all 132 pages.for-docs/reference/configuration-reference.mdx(9 findings): every H2 now opens with a table: file sections, doc collection fields,filterentries, context source types, trigger fields, built-in triggers, policy sections, channel inheritance, rule matching, error-marker parts, common errors, and what a rename updates. "Example configuration" and "Migration from projects" become H3s and keep their anchors. Fixes: the context source example'sgoogle_drive:key is invalid (keys are kebab-case, sogoogle-drive:);hostis invalid only forgithubandgithub_oss; a repository rename also rewritesdoc_collectionin policy rules. Removed anchors with no inbound links:#fields,#available-sources,#repository-renames(now#repository-and-channel-renames).governance/deploy-the-worker/observability.mdx(6): staystroubleshooting, now in the template's shape. The intro keeps the stage table (with a column linking each stage to its symptom), log commands, and data-preservation caution. Six Symptom sections follow, each with Cause and Solution. The Datadog and Sentry details move to the Helm reference, and this page links there. No inbound links pointed at the removed anchors.governance/deploy-the-worker/manual-helm-reference.mdx(5): tables of key, default, and meaning for service account, database TLS, image, probes, Datadog, and Sentry values. Checked against the published 0.3.6 chart (Promptless/pig-deploy). Fixes: the service-account example setmigrationJob.serviceAccountName, which the 0.3.6 schema rejects (both workloads useserviceAccount.name); load-balancer health checks point at/healthz, matching the deploy guides; adds the missingDD_TRACE_ANALYTICS_ENABLED. Anchors:#enable-datadog→#datadog-tracing-values(its one inbound link is updated),#enable-sentry→#sentry-error-reporting-values,#validate-a-configuration-change→#apply-a-configuration-change. The page keeps its path andtype: reference.for-docs/reference/account-management.mdx(5): staysreference. Tables for roles, admin-only configuration, enrollment modes, security features, Billing sections, and Current plan fields. Procedures are short numbered steps with the dashboard's current labels (checked against the pinned Clerk localization). "Need help?" becomes See also. Fixes: Manage opens the organization's management page, not a modal; the retired agent behavior settings are removed.#billingand its H3 anchors are unchanged.for-docs/connect/connection-health.mdx(5): intro with the card health labels, six Symptom sections with Cause and Solution, and For more information. Fixes: the repository picker's empty message is "No connected repository matches that.", and the picker covers GitHub or GitLab; Promptless notifies the escalation channel, if one is set, when a connection needs reconnecting or stays degraded for 24 hours.repository_sha), account management (free trial), and connection health (Jira service account). Whichever merges second needs a rebase.Eighth pass: every remaining page, with each
typere-assessed (dashboard task). The 117 pages that the earlier passes didn't restructure. Each now follows its type's template and has a clarity edit, and site-widemanni lint structuregoes from 220 findings across 115 pages to 0 across 132. ADR 0006 is updated to match.for-docs/reference/faq.mdx,governance/reference/faq.mdx) become Question | Answer tables per topic, and the integration pages'<details>FAQs become problem, cause, and fix tables. Redundant passages, marketing tone, and "Need help?" footers are cut.intent, its section's job in the IA, and the personas and journeys indocs.metadata.yaml. 12 pages change type, and 105 keep theirs:reference→how-to: the eight remaining Reference > Integrations pages (Atlassian, GitHub, GitHub read-only, LaunchDarkly, Linear, Microsoft Teams, Slack, Vercel). Each is a connect-and-manage task, like the GitLab and GitHub Enterprise pages.concept→reference:reference/integrations.mdx, a lookup in the Reference section. It's now tables of integrations and what each provides, health labels, notification timing, and card actions.how-to→concept:connect/source-control.mdx(helps a reader choose a connection and scope its access; the steps live on the integration pages) andstarport/agent-ready.mdx(describes what a Starport site ships; no task).concept→how-to:governance/deploy-the-worker/plan-your-deployment.mdx(checking requirements, choosing a path, and registering an analyzer are setup tasks).type: referencein place until the placement question is answered.microsoft-teams#reading-files-you-share→#choose-which-shared-files-promptless-can-read, whose one link (in the Teams partial) is updated.pig-deployandpig-toolchainrepos (citations are on the PR):google-drive:. The Notion tools table is replaced (Promptless reads Notion through its CLI now). The Connect Notion, Connect Slite, and Connect Atlassian labels are current, and Slite connects with an API key, not OAuth. The GitLab project picker is pick-only. GitHub issue mentions work in the title, description, or a comment. The schedule trigger button is Add an automatic or scheduled trigger.files:writeand diff files and addsfiles:read. Atlassian addsmanage:jira-webhookand follows the current Jira identity rules: an attached service account does all Jira work, and without one Promptless writes as the connecting account only with explicit permission. Teams adds two permissions and the SharePoint site-grant steps. GitHub's owner-approval flow completes on its own after approval.how-promptless-uses-ai.mdxnow says GitLab has no read-only option.llms.txtlinks tollms-full.txtandllms-small.txt. The assistant is labeled Ask Assistant. Deployed settings go in the hosting provider's environment, not.env. PostHog reporting needs a project key.pig init --orgis required. A deployed analyzer gets repository tokens from the Promptless GitHub App, not a configured token. PostgreSQL accepts onlysslmode=verify-full, with a pool of up to eight connections. The manual Helm upgrade scalesdeployment/pig-trace-analyzer. GKE Standard needs anodeSelector, now in the GCP guide and both references. The Azure and GCP Terraform input names are fixed.manni lint structurepasses all 132 pages,manni meta validatepasses all 132 (afternpx manni meta derive --fields last-updatedon the changed pages), remark-lint is clean, and Vale reports no new or remaining errors on the changed files. Locally, the build, typecheck, markdown, MCP, search, search-quality, and smoke tests pass.Merge from
main(#1172). PR #1172 (Jira service-account identity, write permission, and reply behavior) conflicted with five restructured pages. Merge commit e03d0f2 resolved them by keeping this PR's structure and carrying #1172's facts into it. A follow-up commit adds two #1172 changes that the merge had missed, onreference/integrations/atlassian.mdxandconnect/triggers/jira.mdx:connect/triggers/jira.mdx: "Reply on the ticket" is docs: Document Jira service-account identity, write permission, and reply behavior #1172's table of what Promptless posts, based on how the session started. It's followed by "Which account Promptless uses in Jira". The trigger-output paragraph, service account section, and Example follow docs: Document Jira service-account identity, write permission, and reply behavior #1172. The Overview now points to "Reply on the ticket", because a label or configured-trigger session posts nothing when there's no documentation change.connect/triggers/jira-automation.mdx,reference/configuration-reference.mdx: docs: Document Jira service-account identity, write permission, and reply behavior #1172's identity and reply wording.connect/connection-health.mdx: a second cause and solution under "A Jira reply or comment from Promptless didn't post", for a missing write permission.reference/integrations/atlassian.mdx: thewrite:jira-workscope row, the service account's project permissions, issue-creation permission, and the confidential-projects row follow docs: Document Jira service-account identity, write permission, and reply behavior #1172.Ninth pass: follow-ups on the points to check (dashboard task).
migrate/why-docs-as-code.mdx: FrameMaker works "through a MIF intermediary" (was "MIP").why-docs-as-code.mdxdrops the "hard prerequisite" callout, and "Why Promptless requires it" becomes "How Promptless works with docs-as-code". The page's description, intent, and sample question match.choose-a-platform.mdxandmigrate-to-a-new-platform.mdxdrop the "Promptless needs" wording. All three now say Promptless also publishes to Heretto CCMS folders, as Heretto suggestions, which matches theherettodoc collection platform.security/self-hosting/kubernetes-helm.mdx, hidden) is deleted. Its four redirects (/self-hosting/kubernetes-helm,/docs/self-hosting/kubernetes-helm,/docs/security/self-hosting/kubernetes-helm, and the page's own URL) now go to the self-hosting overview. Itsdocs.metadata.yamlentry, frozen-route fixture rows, and sitemap test assertion are removed, and the route manifest is regenerated. The self-hosting overview (also hidden) loses the chart's description, its supported-platforms table, and the link card. A short "Deployment options" section says the Promptless team plans each deployment with you.get-the-most-out/pay-down-docs-debt.mdx, and the docs-as-code page's Open Graph image is regenerated for its new description. The overall comments screenshot was already removed fromwork-the-queue/giving-feedback.mdxin the eighth pass.connect/triggers.mdxand to the quickstart. Those mentions are removed, following docs: Remove Bitbucket from the docs #1034, which took Bitbucket out of the docs because it isn't wired up.manni lint structureandmanni meta validatepass all 131 pages. remark-lint is clean. Vale reports no collection errors on the changed files. Locally,npm run checkpasses on Node 24: typecheck, markdown, MCP, search, the build, and search quality.Tenth pass: one "Overview" in "On this page",
<Steps>for every procedure, and the MCP skill rename (dashboard task).## Overviewheading, now on 89 pages, added a second one. A Starlight route middleware (src/starlightRouteData.ts, logic insrc/lib/toc-overview.ts, unit test intests/unit/toc-overview.spec.tsrun bytest:markdown) drops the heading's entry when it repeats the top entry. The list shows "Overview" once, linking to the top of the page. Headings, anchors, and the structure lint are unchanged, and ADR 0006 records the tradeoff.<Steps>: 141 numbered procedures on 67 pages are now wrapped in Starlight's<Steps>, withStepsadded to each page's import. The integration partials already used<Steps>. Eight numbered lists describe what Promptless does rather than steps a reader takes, so they stay plain lists: the Doc Detective failure follow-up, Vale enforcement, trigger processing, the analytics and inbound-review workflow outcomes, the read-only fork flow, the GitLab merge request flow, and the three filtering points. Items inside<Steps>are separated by blank lines so Vale reads each step as its own paragraph. Five sentences that Vale then flagged as too long are split.suggestion-triageis renamedtriage-suggestionsinconnect/triggers/mcp.mdx(five places), following Promptless/promptless#5530. PR docs: Rename the MCP suggestion-triage skill to triage-suggestions #1182 makes the same change onmain, so whichever merges second has a smallmcp.mdxconflict. Keeptriage-suggestionseither way.Checklist
Review feedback in this update
"This should be a how-to" (five threads: GitHub commits, GitHub PRs, GitLab merge requests, Slack messages, GitLab integration): applied. Each page is now
type: how-toand passesmanni lint structure. The GitLab integration page keeps the how-to shape, and its connection steps now come from the shared GitLab partial."Extract the integration procedures into shared snippets … and remove them from the TOC": applied, with two changes. The GitHub Enterprise procedure stays on its own page because of its size. The integration pages leave the nav but aren't
sidebar.hidden, so they stay in search, the sitemap, andllms.txt."Make sure that nothing outside of the reference section is labelled as type: reference": applied to 35 pages. Five lookup pages keep
type: referenceuntil someone decides whether to move them into a reference section.CI
verifyfailure (search-quality test "slack setup"): fixed. A localnpm run checkpasses."Remove the screenshot please" (dashboard task, about
linear-auth.png): applied. The image and its reference inlinear-connect.mdxare removed."Update to the newest version of manni … then start on the next highest priority pages" (dashboard task): applied. manni is pinned to 4.13.0, and the configuration reference, observability, manual Helm reference, account management, and connection health pages are restructured (seventh pass).
"Handle every other page in the doc set, additionally re-assessing each
type…" (dashboard task): applied to the remaining 117 pages (eighth pass). All 132 pages now passmanni lint structure; 12 pages change type, none move."For points to check: … correct MIP to MIF; revise to remove references that docs as code is required; remove the unused chart; remove 'temporary outage', remove out-of-date screenshots" (dashboard task): applied (ninth pass). Points 1 and 2 (context source scope, Voice Match) and the other unverified items in point 3 are left as they are.
"Many pages have a doubled 'Overview' in the side nav. Figure out why and fix it." (dashboard task): applied (tenth pass).
"Procedures should consistently be using ." (dashboard task): applied to 141 procedures on 67 pages (tenth pass).