docs: v2 docs & landing

.gitignore

@@ -25,3 +25,4 @@ docker-target
 test-keypair.json
 tsconfig.tsbuildinfo
 .vscode
+*.stackdump

README.md

@@ -1,52 +1,90 @@
 <div align="center">
-  <img height="170x" src="https://pbs.twimg.com/media/FVUVaO9XEAAulvK?format=png&name=small" />
 
-  <h1>Anchor</h1>
+  #  <picture><source media="(prefers-color-scheme: dark)" srcset="docs-v2/src/assets/wordmark-dark.svg" /><img alt="Anchor" src="docs-v2/src/assets/wordmark-light.svg" height="60" /></picture>
 
-  <p>
-    <strong>Solana Program Framework</strong>
-  </p>
-
-  <p>
-    <a href="https://github.com/solana-foundation/anchor/actions"><img alt="Build Status" src="https://github.com/solana-foundation/anchor/actions/workflows/tests.yaml/badge.svg" /></a>
-    <a href="https://anchor-lang.com"><img alt="Tutorials" src="https://img.shields.io/badge/docs-tutorials-blueviolet" /></a>
-    <a href="https://discord.gg/NHHGSXAnXk"><img alt="Discord Chat" src="https://img.shields.io/discord/889577356681945098?color=blueviolet" /></a>
-    <a href="https://opensource.org/licenses/Apache-2.0"><img alt="License" src="https://img.shields.io/github/license/solana-foundation/anchor?color=blueviolet" /></a>
-  </p>
+[![Build Status][Build Status Badge]][Build Status]
+[![Tutorials][Tutorials Badge]][Documentation]
+[![Discord Chat][Discord Badge]][Discord]
+[![License][License Badge]][Apache 2.0 Spec]
 </div>
 
-[Anchor](https://www.anchor-lang.com/) is a framework for Solana programs: a Rust eDSL, an [IDL](https://en.wikipedia.org/wiki/Interface_description_language) spec, a TypeScript client generated from that IDL, and a CLI + workspace tool for driving the whole loop.
+---
 
-## v2 in progress
+Anchor is a framework for writing Solana programs in Rust. Solana's native program model gives you fine-grained control over accounts and instruction bytes, but very little structure. Anchor handles the parts that most programs need to do the same way. It validates accounts, checks ownership, serializes data, and dispatches instructions into your handler functions. You write what is specific to your program and let Anchor handle the rest.
 
-[`anchor-lang-v2`](./lang-v2/) is the next-generation runtime, built on [pinocchio](https://github.com/anza-xyz/pinocchio) and `#![no_std]` by default. It produces an order of magnitude smaller binaries and fewer CU per instruction than v1. Alpha — see [`lang-v2/README.md`](./lang-v2/README.md) for quick-start, bench numbers, and caveats. The v1 (`lang/`) code in this repo remains the stable, published path.
+The project ships four pieces that work together:
 
-## Getting started
+- `anchor-lang`, the Rust crate you use to write programs.
+- An [IDL][IDL] format that describes a program's surface once and generates clients from it.
+- `@anchor-lang/core`, a TypeScript package for calling deployed programs from a browser or a script.
+- The `anchor` CLI that scaffolds workspaces, builds, runs tests, deploys to a cluster, and manages on-chain IDLs.
 
-See the [Anchor book](https://book.anchor-lang.com), the [docs site](https://anchor-lang.com), and the [examples](https://github.com/solana-foundation/anchor/tree/master/examples). Rust API on [docs.rs](https://docs.rs/anchor-lang), TypeScript API in the [typedoc](https://www.anchor-lang.com/docs/clients/typescript).
+> [!IMPORTANT]
+> [`anchor-lang-v2`][Anchor Lang v2] is the next-generation runtime. It is built on [pinocchio][Pinocchio] and `#![no_std]` by default, and produces orders-of-magnitude smaller binaries and fewer CU per instruction than v1. See [`lang-v2/README.md`][Anchor Lang v2 README] for the quick-start, bench numbers, and caveats. Note that the v2 path is alpha.
 
-## Packages
+## Getting started
 
-| Package                 | Description                                              | Version                                                                                                                          | Docs                                                                                                            |
-| :---------------------- | :------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
-| `anchor-lang`           | Rust primitives for writing programs on Solana           | [![Crates.io](https://img.shields.io/crates/v/anchor-lang?color=blue)](https://crates.io/crates/anchor-lang)                     | [![Docs.rs](https://docs.rs/anchor-lang/badge.svg)](https://docs.rs/anchor-lang)                                |
-| `anchor-spl`            | CPI clients for SPL programs on Solana                   | [![crates](https://img.shields.io/crates/v/anchor-spl?color=blue)](https://crates.io/crates/anchor-spl)                          | [![Docs.rs](https://docs.rs/anchor-spl/badge.svg)](https://docs.rs/anchor-spl)                                  |
-| `anchor-client`         | Rust client for Anchor programs                          | [![crates](https://img.shields.io/crates/v/anchor-client?color=blue)](https://crates.io/crates/anchor-client)                    | [![Docs.rs](https://docs.rs/anchor-client/badge.svg)](https://docs.rs/anchor-client)                            |
-| `@anchor-lang/core`     | TypeScript client for Anchor programs                    | [![npm](https://img.shields.io/npm/v/@anchor-lang/core.svg?color=blue)](https://www.npmjs.com/package/@anchor-lang/core)         | [![Docs](https://img.shields.io/badge/docs-typedoc-blue)](https://solana-foundation.github.io/anchor/ts/index.html)     |
-| `@anchor-lang/cli`      | CLI for building and managing an Anchor workspace        | [![npm](https://img.shields.io/npm/v/@anchor-lang/cli.svg?color=blue)](https://www.npmjs.com/package/@anchor-lang/cli)           | [![Docs](https://img.shields.io/badge/docs-typedoc-blue)](https://www.anchor-lang.com/docs/references/cli)      |
+- Read the [documentation][Documentation] for a guided tutorial and full reference.
+- Explore the [examples][Examples] and [tests][Tests] directories for runnable code.
+- Look up Rust types on [docs.rs][Anchor Lang Docs] and TypeScript types in [TypeDoc][TypeDoc].
 
-## Notes
+## Packages
 
-- **APIs are subject to change** — Anchor is under active development.
+| Package | Description | Version | Docs |
+| :--- | :--- | :--- | :--- |
+| `anchor-lang` | Rust primitives for writing programs on Solana | [![Crates.io][Anchor Lang Crates Badge]][Anchor Lang Crates] | [![Docs.rs][Anchor Lang Docs Badge]][Anchor Lang Docs] |
+| `anchor-spl` | CPI clients for SPL programs on Solana | [![crates][Anchor SPL Crates Badge]][Anchor SPL Crates] | [![Docs.rs][Anchor SPL Docs Badge]][Anchor SPL Docs] |
+| `anchor-client` | Rust client for Anchor programs | [![crates][Anchor Client Crates Badge]][Anchor Client Crates] | [![Docs.rs][Anchor Client Docs Badge]][Anchor Client Docs] |
+| `@anchor-lang/core` | TypeScript client for Anchor programs | [![npm][Anchor Core NPM Badge]][Anchor Core NPM] | [![Docs][Anchor Core Docs Badge]][Anchor Core Docs] |
+| `@anchor-lang/cli` | CLI for building and managing an Anchor workspace | [![npm][Anchor CLI NPM Badge]][Anchor CLI NPM] | [![Docs][Anchor CLI Docs Badge]][Anchor CLI Docs] |
 
 ## License
 
-Anchor is licensed under [Apache 2.0](./LICENSE). Contributions are accepted under the same license unless you explicitly state otherwise.
+Anchor is licensed under [Apache 2.0][License]. Contributions are accepted under the same license unless you explicitly state otherwise. See [CONTRIBUTING.md][Contributing] for guidelines.
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines.
+&nbsp;
 
 <div align="center">
   <a href="https://github.com/solana-foundation/anchor/graphs/contributors">
     <img src="https://contrib.rocks/image?repo=solana-foundation/anchor" width="100%" />
   </a>
+
 </div>
+
+[Build Status]: https://github.com/solana-foundation/anchor/actions
+[Build Status Badge]: https://img.shields.io/github/actions/workflow/status/solana-foundation/anchor/tests.yaml?color=6c7086&label=build
+[Documentation]: https://anchor-lang.com
+[Tutorials Badge]: https://img.shields.io/badge/docs-tutorials-7f849c
+[Discord]: https://discord.gg/NHHGSXAnXk
+[Discord Badge]: https://img.shields.io/discord/889577356681945098?color=9399b2&label=discord
+[Apache 2.0 Spec]: https://opensource.org/licenses/Apache-2.0
+[License Badge]: https://img.shields.io/github/license/solana-foundation/anchor?color=a6adc8
+[IDL]: https://en.wikipedia.org/wiki/Interface_description_language
+[Anchor Lang v2]: ./lang-v2/
+[Pinocchio]: https://github.com/anza-xyz/pinocchio
+[Anchor Lang v2 README]: ./lang-v2/README.md
+[Examples]: ./examples/
+[Tests]: ./tests/
+[Anchor Lang Docs]: https://docs.rs/anchor-lang
+[TypeDoc]: https://www.anchor-lang.com/docs/clients/typescript
+[Anchor Lang Crates]: https://crates.io/crates/anchor-lang
+[Anchor Lang Crates Badge]: https://img.shields.io/crates/v/anchor-lang?color=9399b2
+[Anchor Lang Docs Badge]: https://img.shields.io/docsrs/anchor-lang?color=a6adc8&label=docs
+[Anchor SPL Crates]: https://crates.io/crates/anchor-spl
+[Anchor SPL Crates Badge]: https://img.shields.io/crates/v/anchor-spl?color=9399b2
+[Anchor SPL Docs]: https://docs.rs/anchor-spl
+[Anchor SPL Docs Badge]: https://img.shields.io/docsrs/anchor-spl?color=a6adc8&label=docs
+[Anchor Client Crates]: https://crates.io/crates/anchor-client
+[Anchor Client Crates Badge]: https://img.shields.io/crates/v/anchor-client?color=9399b2
+[Anchor Client Docs]: https://docs.rs/anchor-client
+[Anchor Client Docs Badge]: https://img.shields.io/docsrs/anchor-client?color=a6adc8&label=docs
+[Anchor Core NPM]: https://www.npmjs.com/package/@anchor-lang/core
+[Anchor Core NPM Badge]: https://img.shields.io/npm/v/@anchor-lang/core.svg?color=9399b2
+[Anchor Core Docs]: https://solana-foundation.github.io/anchor/ts/index.html
+[Anchor Core Docs Badge]: https://img.shields.io/badge/docs-typedoc-a6adc8
+[Anchor CLI NPM]: https://www.npmjs.com/package/@anchor-lang/cli
+[Anchor CLI NPM Badge]: https://img.shields.io/npm/v/@anchor-lang/cli.svg?color=9399b2
+[Anchor CLI Docs]: https://www.anchor-lang.com/docs/references/cli
+[Anchor CLI Docs Badge]: https://img.shields.io/badge/docs-cli-a6adc8
+[License]: ./LICENSE
+[Contributing]: ./CONTRIBUTING.md

docs-v2/.gitattributes

@@ -0,0 +1 @@
+*.mdx linguist-vendored

docs-v2/.gitignore

@@ -0,0 +1,13 @@
+dist/
+.astro/
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.env
+.env.production
+.DS_Store
+.idea/
+teaser.pptx
+~$teaser.pptx

docs-v2/README.md

@@ -0,0 +1,12 @@
+## Anchor docs
+
+Astro site that builds the v1 and v2 Anchor documentation.
+
+### Develop
+
+```bash
+bun install
+bun run dev
+```
+
+The dev server is on `http://localhost:4321/docs/`.

docs-v2/astro.config.ts

@@ -0,0 +1,152 @@
+import { rehypeHeadingIds } from '@astrojs/markdown-remark'
+import mdx from '@astrojs/mdx'
+import react from '@astrojs/react'
+import sitemap from '@astrojs/sitemap'
+import rehypeShiki from '@shikijs/rehype'
+import tailwindcss from '@tailwindcss/vite'
+import pagefind from 'astro-pagefind'
+import { defineConfig } from 'astro/config'
+import { readFile } from 'node:fs/promises'
+import { extname, isAbsolute, relative, resolve } from 'node:path'
+import rehypeAutolinkHeadings from 'rehype-autolink-headings'
+import rehypeExpressiveCode from 'rehype-expressive-code'
+import rehypeExternalLinks from 'rehype-external-links'
+import rehypeKatex from 'rehype-katex'
+import remarkEmoji from 'remark-emoji'
+import remarkMath from 'remark-math'
+import { expressiveCodeOptions } from './src/lib/expressive-code-config'
+import { rehypeCodeAnnotations } from './src/lib/rehype-code-annotations'
+import { rehypeCodePathHints, rehypeCodePathIcons } from './src/lib/rehype-code-paths'
+import { rehypeCopyableShellCommands } from './src/lib/rehype-copyable-shell-commands'
+import { rehypeLinkIcons } from './src/lib/rehype-link-icons'
+import { rehypeTableWrappers } from './src/lib/rehype-table-wrappers'
+import { darkTheme, lightTheme } from './src/lib/shiki-themes'
+
+type DevMiddleware = (
+  req: { url?: string },
+  res: { setHeader(name: string, value: string): void; end(data: Uint8Array): void },
+  next: () => void,
+) => void | Promise<void>
+
+type DevServer = {
+  middlewares: {
+    use(path: string, handler: DevMiddleware): void
+  }
+}
+
+const DOCS_BASE = '/docs'
+const PAGEFIND_DIST_DIR = resolve(process.cwd(), 'dist', 'docs', 'pagefind')
+
+function pagefindDevServer() {
+  const mime: Record<string, string> = {
+    js: 'application/javascript',
+    mjs: 'application/javascript',
+    css: 'text/css',
+    json: 'application/json',
+    wasm: 'application/wasm',
+  }
+
+  return {
+    name: 'pagefind-dev-server',
+    enforce: 'pre' as const,
+    apply: 'serve' as const,
+    configureServer(server: DevServer) {
+      server.middlewares.use('/pagefind', async (req, res, next) => {
+        const filePath = resolvePagefindAsset(req.url ?? '/')
+        if (!filePath) return next()
+
+        try {
+          const data = await readFile(filePath)
+          const ext = extname(filePath).slice(1)
+          if (mime[ext]) res.setHeader('Content-Type', mime[ext])
+          res.end(data)
+        } catch {
+          next()
+        }
+      })
+    },
+  }
+}
+
+function resolvePagefindAsset(url: string): string | null {
+  let pathname: string
+  try {
+    pathname = decodeURIComponent(url.split('?')[0] ?? '/')
+  } catch {
+    return null
+  }
+
+  if (!pathname || pathname === '/') return null
+
+  const filePath = resolve(PAGEFIND_DIST_DIR, `.${pathname}`)
+  const relativePath = relative(PAGEFIND_DIST_DIR, filePath)
+
+  if (relativePath.startsWith('..') || isAbsolute(relativePath)) return null
+
+  return filePath
+}
+
+export default defineConfig({
+  site: 'https://www.anchor-lang.com',
+  base: DOCS_BASE,
+  trailingSlash: 'always',
+  outDir: './dist/docs',
+  integrations: [mdx(), react(), sitemap(), pagefind()],
+  vite: {
+    plugins: [tailwindcss(), pagefindDevServer()],
+  },
+  server: {
+    port: 4321,
+    host: true,
+  },
+  devToolbar: {
+    enabled: false,
+  },
+  markdown: {
+    syntaxHighlight: false,
+    rehypePlugins: [
+      [
+        rehypeExternalLinks,
+        {
+          target: '_blank',
+          rel: ['nofollow', 'noreferrer', 'noopener'],
+        },
+      ],
+      rehypeTableWrappers,
+      rehypeKatex,
+      [rehypeExpressiveCode, { themes: [lightTheme, darkTheme], ...expressiveCodeOptions }],
+      rehypeCodePathHints,
+      [
+        rehypeShiki,
+        {
+          themes: { light: lightTheme, dark: darkTheme },
+          inline: 'tailing-curly-colon',
+        },
+      ],
+      rehypeCopyableShellCommands,
+      rehypeCodeAnnotations,
+      rehypeCodePathIcons,
+      rehypeLinkIcons,
+      rehypeHeadingIds,
+      [
+        rehypeAutolinkHeadings,
+        {
+          behavior: 'append',
+          properties: {
+            className: ['heading-anchor'],
+            'aria-label': 'Link to section',
+            tabindex: -1,
+            'data-pagefind-ignore': '',
+          },
+          content: {
+            type: 'text',
+            value: '#',
+          },
+          test: (node: { tagName: string }) =>
+            ['h2', 'h3', 'h4', 'h5', 'h6'].includes(node.tagName),
+        },
+      ],
+    ],
+    remarkPlugins: [remarkMath, remarkEmoji],
+  },
+})