Docs v15

README.md

@@ -1,54 +1,52 @@
-# Starlight Starter Kit: Basics
+# Charms documentation
 
-[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+The documentation site for [Charms](https://charms.dev) — programmable tokens on
+Bitcoin (and beyond). Built with [Astro](https://astro.build) +
+[Starlight](https://starlight.astro.build) and deployed to
+[charms.dev](https://charms.dev).
 
-```
-npm create astro@latest -- --template starlight
-```
-
-[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
-[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
-[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/withastro/starlight&create_from_path=examples/basics)
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs)
+This site documents **Charms v15**. The protocol source lives at
+[github.com/CharmsDev/charms](https://github.com/CharmsDev/charms).
 
-> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+## Structure
 
-## 🚀 Project Structure
+Content lives in `src/content/docs/` and is organized with the
+[Diátaxis](https://diataxis.fr) framework — four sections, each serving a
+distinct need:
 
-Inside of your Astro + Starlight project, you'll see the following folders and files:
-
-```
-.
-├── public/
-├── src/
-│   ├── assets/
-│   ├── content/
-│   │   ├── docs/
-│   └── content.config.ts
-├── astro.config.mjs
-├── package.json
-└── tsconfig.json
-```
+| Section | Directory | For |
+| --- | --- | --- |
+| **Concepts** | `concepts/` | Understanding the ideas behind Charms. |
+| **Tutorials** | `tutorials/` | Learning by doing (start here). |
+| **How-to guides** | `how-to/` | Accomplishing specific tasks. |
+| **Reference** | `reference/` | Looking up exact formats and APIs. |
 
-Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+The sidebar and redirects from old URLs are configured in `astro.config.mjs`.
+Each page is also served as raw Markdown at its `.md` URL (see
+`src/pages/[...slug].md.ts`).
 
-Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+## Develop
 
-Static assets, like favicons, can be placed in the `public/` directory.
-
-## 🧞 Commands
-
-All commands are run from the root of the project, from a terminal:
-
-| Command                   | Action                                           |
-| :------------------------ | :----------------------------------------------- |
-| `npm install`             | Installs dependencies                            |
-| `npm run dev`             | Starts local dev server at `localhost:4321`      |
-| `npm run build`           | Build your production site to `./dist/`          |
-| `npm run preview`         | Preview your build locally, before deploying     |
-| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
-| `npm run astro -- --help` | Get help using the Astro CLI                     |
-
-## 👀 Want to learn more?
+```sh
+npm install
+npm run dev        # local dev server at http://localhost:4321
+```
 
-Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
+| Command | Action |
+| --- | --- |
+| `npm install` | Install dependencies |
+| `npm run dev` | Start the dev server |
+| `npm run build` | Build the production site to `./dist/` |
+| `npm run preview` | Preview the production build locally |
+
+## Contributing
+
+- Put each page in the section that matches its *purpose*, not its topic — a
+  single topic (e.g. spells) legitimately appears across tutorials, how-to,
+  concepts, and reference.
+- Keep the types distinct: tutorials don't dwell on options, how-to guides don't
+  explain theory, reference stays factual, concepts avoid step-by-step
+  instructions.
+- Internal links are root-relative and omit the trailing slash
+  (`/reference/spell`), matching `trailingSlash: 'never'`.
+- Verify changes build with `npm run build` before opening a PR.

astro.config.mjs

@@ -4,6 +4,32 @@ import starlight from '@astrojs/starlight';
 
 // https://astro.build/config
 export default defineConfig({
+	site: 'https://charms.dev',
+	trailingSlash: 'never',
+	// Redirects from the pre-Diátaxis URLs to their new homes.
+	redirects: {
+		'/explanation': '/concepts',
+		'/explanation/why-charms': '/concepts/why-charms',
+		'/explanation/apps': '/concepts/apps',
+		'/explanation/spells': '/concepts/spells',
+		'/explanation/transactions': '/concepts/transactions',
+		'/explanation/beaming': '/concepts/beaming',
+		'/explanation/scrolls': '/concepts/scrolls',
+		'/concepts/why': '/concepts/why-charms',
+		'/guides/charms-apps/introduction': '/tutorials',
+		'/guides/charms-apps/pre-reqs': '/how-to/set-up-a-bitcoin-node',
+		'/guides/charms-apps/get-started': '/tutorials/build-a-charms-app',
+		'/guides/charms-apps/cast-spell': '/tutorials/cast-your-first-spell',
+		'/guides/wallet-integration/introduction': '/how-to/wallet-integration',
+		'/guides/wallet-integration/visualization': '/how-to/wallet-integration/display-charms',
+		'/guides/wallet-integration/transactions/overview': '/how-to/wallet-integration',
+		'/guides/wallet-integration/transactions/nft': '/how-to/wallet-integration/transfer-nfts',
+		'/guides/wallet-integration/transactions/token': '/how-to/wallet-integration/transfer-tokens',
+		'/guides/wallet-integration/transactions/prover-api': '/how-to/call-the-prover-api',
+		'/guides/wallet-integration/transactions/signing': '/how-to/wallet-integration/sign-and-broadcast',
+		'/guides/wallet-integration/transactions/broadcasting': '/how-to/wallet-integration/sign-and-broadcast',
+		'/references/spell-json': '/reference/spell',
+	},
 	integrations: [
 		starlight({
 			title: 'Charms',
@@ -39,79 +65,70 @@ export default defineConfig({
 					label: 'GitHub',
 				},
 			],
+			// The sidebar follows the Diátaxis framework (https://diataxis.fr):
+			// Concepts (understanding), Tutorials (learning), How-to guides
+			// (tasks), and Reference (information).
 			sidebar: [
 				{
 					label: 'Concepts',
-					autogenerate: { directory: 'concepts' },
+					items: [
+						{ label: 'Overview', link: '/concepts' },
+						{ label: 'Why Charms?', link: '/concepts/why-charms' },
+						{ label: 'Apps', link: '/concepts/apps' },
+						{ label: 'Spells', link: '/concepts/spells' },
+						{ label: 'Transactions', link: '/concepts/transactions' },
+						{ label: 'Beaming', link: '/concepts/beaming' },
+						{ label: 'Scrolls', link: '/concepts/scrolls' },
+					],
 				},
 				{
-					label: 'Guides',
+					label: 'Tutorials',
 					items: [
+						{ label: 'Overview', link: '/tutorials' },
+						{ label: 'Build a Charms app', link: '/tutorials/build-a-charms-app' },
+						{ label: 'Cast your first spell', link: '/tutorials/cast-your-first-spell' },
+					],
+				},
+				{
+					label: 'How-to guides',
+					items: [
+						{ label: 'Overview', link: '/how-to' },
+						{ label: 'Install Charms', link: '/how-to/install-charms' },
+						{ label: 'Set up a Bitcoin node', link: '/how-to/set-up-a-bitcoin-node' },
+						{ label: 'Write an app contract', link: '/how-to/write-an-app-contract' },
+						{ label: 'Manage app keys', link: '/how-to/manage-app-keys' },
+						{ label: 'Call the Prover API', link: '/how-to/call-the-prover-api' },
+						{ label: 'Run a prover server', link: '/how-to/run-a-prover-server' },
+						{ label: 'Beam charms across chains', link: '/how-to/beam-charms' },
+						{ label: 'Spend Scroll outputs', link: '/how-to/spend-scroll-outputs' },
 						{
-							label: 'Charms Apps',
-							collapsed: false,
-							autogenerate: { directory: 'guides/charms-apps' },
-						},
-						{
-							label: 'Wallet Integration',
-							collapsed: false,
+							label: 'Wallet integration',
 							items: [
-								{
-									label: 'Introduction',
-									link: '/guides/wallet-integration/introduction/',
-								},
-								{
-									label: 'Charms Visualization',
-									link: '/guides/wallet-integration/visualization/',
-								},
-								{
-									label: 'Charms Transactions',
-									collapsed: false,
-									items: [
-										{
-											label: 'Transactions Overview',
-											link: '/guides/wallet-integration/transactions/overview/',
-										},
-										{
-											label: 'NFT Transfers',
-											link: '/guides/wallet-integration/transactions/nft/',
-										},
-										{
-											label: 'Token Transfers',
-											link: '/guides/wallet-integration/transactions/token/',
-										},
-										{
-											label: 'Prover API',
-											link: '/guides/wallet-integration/transactions/prover-api/',
-										},
-										{
-											label: 'Signing Transactions',
-											link: '/guides/wallet-integration/transactions/signing/',
-										},
-										{
-											label: 'Broadcasting Transactions',
-											link: '/guides/wallet-integration/transactions/broadcasting/',
-										},
-									],
-								},
+								{ label: 'Overview', link: '/how-to/wallet-integration' },
+								{ label: 'Display charms', link: '/how-to/wallet-integration/display-charms' },
+								{ label: 'Transfer NFTs', link: '/how-to/wallet-integration/transfer-nfts' },
+								{ label: 'Transfer tokens', link: '/how-to/wallet-integration/transfer-tokens' },
+								{ label: 'Sign and broadcast', link: '/how-to/wallet-integration/sign-and-broadcast' },
 							],
 						},
 					],
 				},
 				{
-					label: 'References',
-					collapsed: false,
+					label: 'Reference',
 					items: [
-						{
-							label: 'Spell JSON Reference',
-							link: '/references/spell-json/',
-						},
+						{ label: 'Overview', link: '/reference' },
+						{ label: 'CLI', link: '/reference/cli' },
+						{ label: 'Spell structure', link: '/reference/spell' },
+						{ label: 'SDK', link: '/reference/sdk' },
+						{ label: 'Prover API', link: '/reference/prover-api' },
+						{ label: 'Scrolls canisters', link: '/reference/scrolls-canister' },
 					],
 				},
 				{
 					label: 'Whitepaper',
 					link: '/Charms-whitepaper.pdf',
-				}
+					attrs: { target: '_blank' },
+				},
 			],
 		}),
 	],