Restructure the Guides section into journey-ordered story pages - #1134
Closed
oduameh wants to merge 20 commits into
Closed
Restructure the Guides section into journey-ordered story pages#1134oduameh wants to merge 20 commits into
oduameh wants to merge 20 commits into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Summary
Errors per inputErrors in docs/examples/_bboard/local-testing.mdx
Errors in docs/getting-started/quickstart.mdx
Errors in docs/guides/acquire-tokens.mdx
Errors in docs/guides/connect-wallet-frontend.mdx
Errors in docs/guides/development-environment.mdx
Errors in docs/guides/generating-dust-programmatically.mdx
Errors in docs/guides/local-to-testnet.mdx
Errors in docs/guides/making-decision-on-contract-updatability.mdx
Errors in docs/guides/work-with-compiled-contract.mdx
Errors in docs/nodes/node-endpoints.mdx
Errors in docs/tokens/overview.mdx
Errors in docs/tutorials/bboard/bboard-cli-implementation.mdx
Errors in docs/tutorials/zk-loan/attestation-api.mdx
Errors in docs/tutorials/zk-loan/cli.mdx
Errors in sdks/community/wallets/integration.mdx
Errors in sdks/community/wallets/reference.mdx
Errors in sdks/community/wallets/wallets-overview.mdx
Errors in sdks/official/midnight-js.mdx
Errors in sdks/troubleshoot/index.mdx
Redirects per inputRedirects in docs/examples/_bboard/local-testing.mdxRedirects in docs/getting-started/quickstart.mdx
Redirects in docs/guides/acquire-tokens.mdxRedirects in docs/guides/connect-wallet-frontend.mdxRedirects in docs/guides/development-environment.mdxRedirects in docs/guides/index.mdxRedirects in docs/guides/local-to-testnet.mdxRedirects in docs/guides/making-decision-on-contract-updatability.mdxRedirects in docs/guides/run-proof-server.mdxRedirects in docs/guides/work-with-compiled-contract.mdxRedirects in docs/tokens/overview.mdxRedirects in docs/tutorials/bboard/bboard-cli-implementation.mdxRedirects in docs/tutorials/zk-loan/attestation-api.mdxRedirects in docs/tutorials/zk-loan/cli.mdxRedirects in sdks/community/wallets/integration.mdxRedirects in sdks/community/wallets/reference.mdxRedirects in sdks/community/wallets/wallets-overview.mdxRedirects in sdks/official/midnight-js.mdx |
… guide Combine windows-compact-setup, install-bun-runtime-midnight, and run-proof-server into a single guide covering platform setup (macOS/ Linux and Windows WSL tabs), the Compact compiler, the VS Code extension, the proof server, and an optional Bun section. Fixes riding along: - correct the Compact install dir to $HOME/.compact/bin (matches the developer-tools release notes and blog post) - correct the Bun PATH fallback to $HOME/.bun/bin - fix a trailing curly quote in the Bun PATH export - align compact check output with the current 0.31.1 toolchain - standardize the proof server image on the :latest tag with a compatibility-matrix pointer - drop externally hosted screenshots (dev.to / github user-attachments) - retarget inbound links (quickstart, 1010 troubleshoot, proof-server release notes, zk-loan attestation) to the new page
…-testnet Combine midnight-local-network, configure-providers, and deploy-mn-app into a single journey page: run a local network, configure the Midnight.js providers, then deploy to Preprod and Preview. Anchors from the retired pages (notably #fund-wallets and the provider IDs) are preserved as explicit heading IDs. Fixes riding along: - refresh the Docker image and Wallet SDK version tables against the current midnight-local-dev repository pins (node 0.22.5, indexer 4.0.2, wallet-sdk 1.0.0, midnight-js 4.1.1) - fix the double colon in the prerequisites lead-in - deduplicate the faucet walkthrough into a link to acquire-tokens - insert the previously unused Lace Undeployed screenshots into the invalid-wallet-address troubleshooting entry - retarget inbound links (bboard and zk-loan tutorials, acquire-tokens, contract-updatability) to the new page
…ntract Combine compact-javascript-runtime (how the JavaScript implementation is generated and structured) and use-compact-javascript-implementation (import, witnesses, circuits, unit tests) into one page, since the two were an explicit part-1/part-2 sequence. Fixes riding along: - update checkRuntimeVersion example to the current 0.16.0 runtime - swap the two retired slugs in the Compact navbar-logo route patterns for the new work-with-compiled-contract slug Known remaining inbound link: docs/compact/test-and-debug.mdx still points at the retired slug; that file is owned by the Compact team and the vercel.json redirect covers visitors.
Combine react-wallet-connect and nextjs-wallet-connect, which were near-duplicates, into connect-wallet-frontend with a Vite + React tab and a Next.js tab sharing one intro, troubleshooting section, and reference list. Per-tab headings carry explicit IDs so deep links from the retired pages keep resolving. Fixes riding along: - port the selectWallet enumeration helper into the Next.js flow, replacing the fragile hardcoded window.midnight.mnLace lookup (wallets inject their Initial API under a UUID key) - fix the always-truthy getConnectionStatus() check in the Next.js example to test status === 'connected' - update the DApp Connector API version note to 4.0.1 - drop the inert redirects: frontmatter field (real redirects live in vercel.json) and a link to a personal example repository
- retitle acquire-tokens to "Fund your wallet", add explicit #get-tnight / #delegate-tdust anchors, an intro that follows on from environment setup, a cross-link to the programmatic DUST guide, and a next-steps handoff to local-to-testnet; soften the unverified claim that the legacy HEX faucet format will be dropped, and fix curly quotes in the rate-limit error sample - generating-dust: cut the 400-line duplicated full-script details block in favor of a one-line pointer, link the faucet path for readers who only need the Lace UI flow, point the proof-server step at the canonical section, bump the compose pin to proof-server 8.1.0, and replace the hardcoded production URL with a relative link - contract updatability: sidebar label "Plan for contract updatability" - renumber sidebar positions to the new journey order (2, 3, 7) - tokens/overview: update link text to the new page title
The guide taught raw @polkadot/api block subscription without mentioning the indexer GraphQL API, which is the recommended query path for DApps, and nodes/node-endpoints already covers RPC access. Salvage its one unique piece, the subscribe-to-new-blocks snippet, into node-endpoints with the missing newline escapes fixed, plus a pointer to indexerPublicDataProvider for contract-state queries.
Replace the generated-index category page with an index doc modeled on the tutorials landing page: a short framing paragraph plus PersonaTiles for the seven guides in journey order. Add a client-side redirect from /category/guides to /guides so local and preview builds match the Vercel redirect.
docs/guides/_lace-wallet.mdx was unrouted (underscore-prefixed) and nothing imports it; /guides/lace-wallet traffic already redirects to /getting-started/installation. Repoint the two stale links in the (also unrouted) bboard local-testing partial: the lace-wallet.mdx file link that no longer resolves and the retired run-proof-server guide.
- retarget the 11 existing rules whose destinations were retired guide slugs, so they point straight at the merged pages (single hop) - add a labeled block redirecting every retired slug, plus the generated-index /category/guides URL, to its merged destination - add per-slug rules above the three :path* catch-alls that rewrite into /guides/, so historical paths like /next/how-to/react-wallet- connect resolve in one hop instead of chaining - verified: no duplicate sources, and no new redirect chains (the five pre-existing chains on unrelated routes are untouched) 229 rules before, 275 after, well under Vercel's 1,024 limit.
The sdks/ section and packages/tests/pipelines-urls.json live outside docs/ and were missed by the first inbound-link sweep. Point the wallet-connect, proof-server, and local-network references at the merged guides, refresh the visual-regression/Lighthouse URL list to the new section layout, and swap two absolute lace-wallet links for their long-standing redirect destination.
oduameh
force-pushed
the
docs/guides-user-story-restructure
branch
from
July 16, 2026 16:29
f8da8f6 to
2a174a9
Compare
The guides restructure introduces explicit heading anchors ({#id}), which
Docusaurus supports natively but mdx2vast cannot parse as MDX expressions,
crashing the Vale job. TokenIgnores strips them before conversion.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit
vale
docs/guides/work-with-compiled-contract.mdx|512 col 93| [Midnight.DeveloperVoice] Avoid marketing language in developer documentation.
docs/guides/work-with-compiled-contract.mdx|520 col 162| [Midnight.Readability] 'is encoded' should be in the active voice.
docs/guides/work-with-compiled-contract.mdx|550 col 12| [Midnight.Readability] 'being locked' should be in the active voice.
docs/guides/work-with-compiled-contract.mdx|560 col 62| [Midnight.Readability] 'is generated' should be in the active voice.
docs/guides/local-to-testnet.mdx|1 col 1| [Midnight.FleschReadabilityGradeLevel] Try to keep the Flesch-Kincaid grade level (8.01) below 8.
docs/guides/local-to-testnet.mdx|3 col 393| [Midnight.Readability] 'is distributed' should be in the active voice.
docs/guides/local-to-testnet.mdx|73 col 138| [Midnight.Readability] 'are pinned' should be in the active voice.
docs/guides/local-to-testnet.mdx|98 col 15| [Midnight.DeveloperVoice] Avoid marketing language in developer documentation.
docs/guides/local-to-testnet.mdx|142 col 17| [Midnight.Readability] 'is provided' should be in the active voice.
docs/guides/local-to-testnet.mdx|150 col 5| [Midnight.Readability] 'are prompted' should be in the active voice.
docs/guides/local-to-testnet.mdx|165 col 5| [Midnight.Readability] 'are prompted' should be in the active voice.
docs/guides/local-to-testnet.mdx|255 col 5| [Midnight.HeadingSentenceCase] 'Set the network ID' should be in sentence case.
docs/guides/local-to-testnet.mdx|475 col 20| [Midnight.Readability] 'is initialized' should be in the active voice.
docs/guides/local-to-testnet.mdx|670 col 4| [Midnight.HeadingSentenceCase] 'Deploy to Preview' should be in sentence case.
docs/guides/local-to-testnet.mdx|715 col 13| [Midnight.DeveloperVoice] Avoid marketing language in developer documentation.
docs/guides/local-to-testnet.mdx|746 col 206| [Midnight.Readability] 'is confirmed' should be in the active voice.
Points the Docker, Discord, and Node.js links at their final destinations flagged by the link checker.
🚀 Preview Deployment✅ Deployment Ready 🔗 Preview URL: https://pr-1134-midnight-docs.vercel.app 📝 Latest commit: This preview updates automatically when you push new commits to this PR. |
Verified against the installer script and a live install: the curl installer places the compact CLI in $HOME/.local/bin (cargo-dist fallback chain), while compact update populates $HOME/.compact with toolchain versions. The troubleshooting PATH export now points at the directory that actually contains the binary.
oduameh
commented
Jul 16, 2026
Rewrites every actionable Vale finding on the PR: passive voice to active, marketing words removed, second-person fixes, and the landing page journey list restructured to satisfy the Oxford comma rule. Also applies the peer review frontmatter suggestions: descriptions into the 120 to 160 character range, five or more lowercase tags. Left as is: SPDX license boilerplate (repo-standard legal text), file-level readability scores, and sentence-case heading flags that are proper-noun false positives (macOS, Preview, network ID).
|
Deployment failed with the following error: |
| @@ -0,0 +1,621 @@ | |||
| --- | |||
There was a problem hiding this comment.
[Midnight.FleschReadabilityGradeLevel] Try to keep the Flesch-Kincaid grade level (9.17) below 8.
| @@ -0,0 +1,638 @@ | |||
| --- | |||
There was a problem hiding this comment.
[Midnight.FleschReadabilityGradeLevel] Try to keep the Flesch-Kincaid grade level (8.11) below 8.
| @@ -0,0 +1,63 @@ | |||
| --- | |||
There was a problem hiding this comment.
[Midnight.FleschReadabilityGradeLevel] Try to keep the Flesch-Kincaid grade level (9.30) below 8.
| @@ -0,0 +1,763 @@ | |||
| --- | |||
There was a problem hiding this comment.
[Midnight.FleschReadabilityGradeLevel] Try to keep the Flesch-Kincaid grade level (8.02) below 8.
nstanford5
requested changes
Jul 17, 2026
Contributor
There was a problem hiding this comment.
This is a massive PR with no context in the description. I started commenting on files that were being deleted, only to discover through inference what your intentions are. Rather than me guessing what you are trying to achieve here, please provide a detailed description of your intentions in the PR description, so that I don't spend time going down the rabbit hole of 42 file changes to discover the intent myself.
Review feedback from nstanford5: the Docker image and Wallet SDK version tables duplicated pins that live in midnight-local-dev's standalone.yml and package.json, creating a second place to maintain them. Point at the owning files instead.
…om/midnightntwrk/midnight-docs into docs/guides-user-story-restructure
| @@ -0,0 +1,751 @@ | |||
| --- | |||
There was a problem hiding this comment.
[Midnight.FleschReadabilityGradeLevel] Try to keep the Flesch-Kincaid grade level (8.04) below 8.
Review feedback from nstanford5: run-proof-server serves DApp users (not builders) who need a Docker proof server for private dapp interaction, a distinct audience from the developer setup inside development-environment. Restored at its original URL: the four redirect rules for that slug are removed, relnotes links point back at it, and the guides landing page gains a matching tile. The developer-focused proof server section in development-environment stays.
Contributor
Author
|
@nstanford5 thanks for the review. Addressed:
CI is green apart from the native Vercel check that fails on every PR in this repo. Ready for another look. |
nstanford5
approved these changes
Jul 18, 2026
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
2 participants
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.
Summary
Intent
The Guides section held 15 small pages with heavy overlap (proof server setup explained in 5 places, React and Next.js wallet connection near-duplicates, a two-part Compact JS sequence split across pages) and no reading order. This PR consolidates them into 7 pages that follow one developer journey (set up, get funded, build and deploy, connect a frontend, plan for the long term) plus a tiled landing page. Almost nothing is deleted: pages are merged, and every heading that had inbound links keeps its anchor on the destination page.
Where every page went
Every old URL 308-redirects to its new home in a single hop (verified on the preview, 36 spot-checks).
/guides/:path*(229 -> 275 rules). Anchors that existed on retired pages carry explicit IDs on the merged pages so deep links keep resolving (#fund-wallets,#run-the-proof-server, provider IDs, deploy step IDs).$HOME/.compact/bin(matches the developer-tools blog post), Bun PATH fallback corrected to$HOME/.bun/bin, curly-quote in a PATH export,checkRuntimeVersion('0.16.0'), compact 0.31.1 output sample, proof-server pins normalized (:latestfor docker run, 8.1.0 for compose), midnight-local-dev version tables refreshed against that repo's actual pins (node 0.22.5, indexer 4.0.2, wallet-sdk 1.0.0), DApp Connector note bumped to 4.0.1, the fragile hardcodedwindow.midnight.mnLacelookup in the Next.js flow replaced with the enumeration helper (wallets inject under UUID keys per the v4 connector typings), an always-truthygetConnectionStatus()check fixed, a 400-line duplicated "full script" block cut, externally hosted screenshots (dev.to / github user-attachments) dropped, and two previously unused Lace Undeployed screenshots finally wired into the troubleshooting entry they were made for.Type of Change
Related Links