Restructure tutorials section sidebar for clarity
- 主要语言
- TypeScript
- 星标
- 10
- 派生
- 50
- 平均合并
- 22 天 23 小时
- 30 天内合并 PR
- 1
描述
## Summary
This issue proposes a tutorials section restructure to close the Quick Start to Miden Bank funnel, make MASM visible by name in the sidebar, and resolve a handful of label inconsistencies.
## Background
The current Tutorials section deploys as:
```
Tutorials
├── Miden Bank (10 parts, Rust compiler walkthrough)
├── Recipes
│ ├── Rust (12 pages)
│ └── Web / TypeScript (8 pages)
├── Development helpers (3 pages: testing, debugging, pitfalls)
└── Miden Node Setup (single leaf)
```
Three problems with this:
1. **The Tutorials landing is a menu, not a path.** Three cards (Miden Bank, Recipes, Miden Node Setup) with no recommended order. Quick Start's last page (`docs/builder/get-started/your-first-smart-contract/test.md:301-311`) sends to "the Tutorials section" without a specific commit. New builders finish Quick Start and have to guess what to do next.
2. **MASM is hidden under a "Rust" label.** Of the 12 pages in `Recipes > Rust`, 8 author custom MASM contracts and 4 use only standard MASM components (BasicWallet, P2ID) via the Rust client. A reader searching the sidebar for MASM finds nothing.
3. **The Helpers cluster has three different labels** for the same node: folder name `helpers/`, `_category_.json` label `Guides`, `sidebars.ts` override `Development helpers`. Three labels for one node is a strong signal of unsettled IA.
Plus a smaller issue: `miden_node_setup.md` sits inside Tutorials but is operator content (6 bash blocks to run a local node), not a tutorial.
## Proposed Tutorials sidebar
Deltas marked: `↺` rewritten copy, `+` added, `−` removed.
```
Tutorials
├── ↺ Introduction (landing rewritten: CardGrid leads with Miden Bank as recommended;
│ "Two authoring paths" callout owned at the Tutorials layer)
├── Miden Bank (unchanged content; explicitly designated post-Quick-Start canonical
│ next step via the landing CardGrid eyebrow and a terminal Quick Start link)
├── Recipes
│ ├── + Rust (NEW empty placeholder for Rust-compiler recipes; index page only today,
│ │ reserved for AMM, vault, etc. when written)
│ ├── ↺ MASM (RENAMED from "Rust"; today's MASM-authoring pages live here)
│ └── ↺ Web / TypeScript (intro rewritten for explicit Web SDK / React SDK framing;
│ bridging tutorial joins from [#297](https://github.com/0xMiden/docs/pull/297) + [0xMiden/tutorials#199](https://github.com/0xMiden/tutorials/pull/199))
├── ↺ Helpers (RENAMED from "Development helpers"; folder, `_category_.json`, and
│ `sidebars.ts` override all agree on this label)
└── − Miden Node Setup (REMOVED from Tutorials, moved to Tools)
```
Quick Start side: `your-first-smart-contract/test.md` gets a single terminal link to Miden Bank instead of the current generic "Visit the Tutorials section" pointer.
Tools side: `miden_node_setup.md` joins `clients/local-node-testing.md` under Tools.
## Rationale
### **Quick Start to Miden Bank: one coherent path**
Today the last Quick Start page ends with a generic CardGrid pointing into the Tutorials section. New builders see three cards with no recommendation. Most peer protocols I checked (Aptos, Sui, Starknet, NEAR) commit to one explicit next step out of Quick Start.
Proposal: rewrite the terminal "Next Steps" section to a single "Next: Build the Miden Bank" link, with one sentence on why. The Tutorials landing CardGrid eyebrows make the same commit ("Start here · Rust compiler" on the Miden Bank card).
### **Rename `Recipes > Rust` to `Recipes > MASM`**
Of the 12 pages in `Recipes > Rust`, 8 ship custom MASM contracts:
- `counter_contract`, `creating_notes_in_masm`, `custom_note_how_to`, `mappings_in_masm`, `public_account_interaction`, `foreign_procedure_invocation`, `oracle`, `network_transactions`
4 use only standard MASM components (BasicWallet, P2ID notes) via the Rust client without authoring custom MASM:
- `create_deploy`, `mint_consume_create`, `unauthenticated_note_how_to`, `delegated_proving`
The "Rust" label hides what the majority of the cluster actually teaches. Renaming makes MASM visible by name. The 4 SDK-only recipes need a home; see Open Question 1.
### **Reserve `Recipes > Rust` for Rust-compiler recipes**
Today the only pure-Rust-compiler tutorial in the docs is Miden Bank (10 parts). When Rust-compiler recipes are written, they'd need a clear slot. A new `Recipes > Rust` placeholder reserves it. For now we can skip that, but I just want to surface that so that we can keep that in mind ofr the future once we create Rust compiler recipes."
### **Two authoring paths callout at tutorials docs**
The Tutorials landing is where a new builder has to choose between Rust compiler and MASM. The choice belongs on the page where it has to happen, not deferred to Reference. Draft copy:
> Miden lets you write smart contracts in two ways:
>
> - **MASM** (Miden Assembly) is the language Miden's VM executes natively. You get full control and the smallest proof footprint. MASM is the path production projects use today. The recipes under [Recipes → MASM](./recipes/masm/) show how to build, deploy, and drive MASM contracts from a Rust client.
> - **The Rust compiler** translates Rust into MASM for you. It's the fastest way to a working contract: Quick Start and the [Miden Bank](./miden-bank/) walkthrough teach this path. The Rust compiler is the right starting point for most new builders. It's still adding features; projects that need control beyond what the compiler currently emits should reach for MASM.
This wording does not say "the Rust compiler is not production-ready" (off-limits for public docs) but does name MASM as "the path production projects use today" so the production-readiness signal stays honest.
### **Move `miden_node_setup.md` to Tools**
The page is operator content (6 bash blocks to run a local node). It sits next to `clients/local-node-testing.md` in Tools naturally. One workflow change in `.github/workflows/deploy-docs.yml`, one redirect rule in `docusaurus.config.ts`, one sidebar entry move.
### **Resolve the Helpers label inconsistency**
Today: folder name `helpers/`, `_category_.json` label `Guides`, `sidebars.ts` override `Development helpers`. Three labels for one node. Pick `Helpers` everywhere.
## Bridging and PSM tutorial placement
The bridging tutorial (from [#297](https://github.com/0xMiden/docs/pull/297) + [`0xMiden/tutorials#199`](https://github.com/0xMiden/tutorials/pull/199)) currently lands under `Recipes > Web / TypeScript`. I think it should be promoted to a top-level `Tutorials > Bridging` slot, sibling of Miden Bank. Same for PSM tutorials (Guardian, Private Multisig) when they're written.
Major capabilities deserve their own discoverable Tutorials home. Bridging already gets a top-level `Tools > Bridging` slot ([#299](https://github.com/0xMiden/docs/issues/299) / [#300](https://github.com/0xMiden/docs/pull/300)); Guardian and Multisig already get top-level Solutions sections. Burying their tutorial walkthroughs under a generic Recipes cluster doesn't match the weight of the capability and makes them harder to find on the post-Quick-Start journey.
[#297](https://github.com/0xMiden/docs/pull/297) would need a sidebar update; [`0xMiden/tutorials#199`](https://github.com/0xMiden/tutorials/pull/199) would either need the source file moved (out of `docs/src/web-client/`) or a new workflow ingest rule.
贡献指南
评估
这个 Issue 还没有评估数据。