docs: add documentation site (docs.lumensblock.dev)#48
Merged
Conversation
Closes #[docs issue] — Write documentation site (docs.lumensblock.dev)
## What was done
Added a full documentation site under /docs using Nextra (Next.js-based
static site generator) covering all five required sections.
## Why Nextra
Docusaurus 3.x has a known incompatibility with Node 22 (webpack
ProgressPlugin schema validation error). Nextra is built on Next.js 14
which runs cleanly on Node 22 and matches the stack already used in the
frontend, keeping the toolchain consistent.
## Files added
### docs/
- package.json — Nextra + nextra-theme-docs + Next.js 14 dependencies
- next.config.js — Nextra wrapper with static export (output: 'export')
so the built /out directory can be deployed to GitHub Pages or Vercel
- theme.config.jsx — Nextra docs theme: site title, GitHub link, footer,
edit-on-GitHub URL pointing to main branch
- pages/_meta.json — sidebar order: Getting Started, Block Reference,
Deployment Guide, Contributing
- pages/_document.jsx — minimal Next.js document wrapper
- public/logo.svg — inline SVG logo (blue rounded square with block grid)
- .gitignore — excludes node_modules, .next/, out/
### docs/pages/ (content)
1. index.md — Getting Started
- Prerequisites table (Node 18+, Rust, wasm32 target, Freighter)
- Install steps: clone, frontend npm install + dev, optional backend
- Step-by-step first contract walkthrough using the Token Transfer
template: open editor → load template → connect wallet → deploy
- Testnet Friendbot note for funding
- Links to all other pages
2. block-reference.md — Block Reference
Documents all 6 block types sourced directly from schema.ts and
codegen.ts:
- Start (default) — entry point, no params, no emitted code
- Auth — caller.require_auth(), derived caller: Address param
- Transfer — token::Client::new(&env,&token).transfer(), all 4 params
- Storage — env.storage().instance().set(), storageKey config field
with sanitisation rules (max 9 chars, alphanumeric)
- Condition — if !release { panic_with_error! }, release: bool param
- Event — env.events().publish(), event_name + from/to/amount params
Each block includes: config fields table, generated parameters table,
exact generated Rust code snippet, and an example use case with a
block chain diagram.
Also documents the 3 built-in templates (Token Transfer, Simple Escrow,
Access-Controlled Storage) and all graph limits (100 nodes, 200 edges,
256 KiB payload, 9-char storageKey).
3. deployment-guide.md — Deployment Guide
- How deployment works (graph → compile API → WASM → fee estimate →
Freighter sign → submit)
- Testnet: Freighter setup, Friendbot funding, full 7-step deploy flow
- Mainnet: warning callout, Freighter network switch, deploy steps
- Fee estimation table (upload WASM + deploy contract operations)
- Troubleshooting section covering all known error states from
DeployButton.tsx (wallet not connected, insufficient balance, failing
tests override, Freighter rejection, WASM compile errors)
4. contributing.md — Contributing Guide
Expands the README contributing section with full developer detail:
- Fork/clone, frontend dev loop (npm test + tsc + lint), backend cargo
check/run, contracts cargo build --target wasm32
- Full project structure map with key files table
- Branch naming conventions, conventional commit message formats
- PR checklist (tests, types, lint, docs sync items for block types,
templates, deployment changes, no secrets)
- Step-by-step guide for adding a new block type (6 steps from
schema.ts through codegen.ts, validate.ts, tests, and docs)
- Step-by-step guide for adding a new template (3 steps)
- Bug report and feature request guidance
### .github/workflows/docs.yml
GitHub Actions workflow that builds the Nextra static site and deploys
to GitHub Pages on every push to main that touches the docs/ directory.
Uses actions/upload-pages-artifact and actions/deploy-pages.
## Verification
Build output confirmed clean:
Route (pages) Size
○ / 3.13 kB
○ /block-reference 3.97 kB
○ /contributing 4.78 kB
○ /deployment-guide 3.50 kB
All 6 static pages generated successfully (next build, Node 22.22.2).
Pvsaint
approved these changes
Jun 20, 2026
10 tasks
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.
Closes #29
Sets up a Nextra docs site under
/docswith four pages:Includes a GitHub Actions workflow (
.github/workflows/docs.yml) that builds and deploys to GitHub Pages on push tomain.