From c66104b1628d65f78af60d3e928445ef7205cd71 Mon Sep 17 00:00:00 2001 From: carlssonk Date: Sat, 13 Jun 2026 00:33:48 +0200 Subject: [PATCH] Add contributor docs and clean up boilerplate - Replace the default Fumadocs README with one describing the project, repo layout, local dev, and CI checks - Add CONTRIBUTING.md covering workflow, checks, and writing guidelines - Remove leftover Fumadocs demo page (test.mdx) - Restore missing intro sentence on the getting-started guide --- CONTRIBUTING.md | 44 ++++++++++++++++ README.md | 59 ++++++++++------------ content/docs/integrate/getting-started.mdx | 2 +- content/docs/test.mdx | 17 ------- 4 files changed, 73 insertions(+), 49 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 content/docs/test.mdx diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1c5ba53 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing to Kaspa Docs + +Thanks for helping improve the Kaspa documentation. Contributions of all sizes are welcome - fixing a typo, clarifying a guide, adding code examples, or writing a missing page. + +## Finding something to work on + +- The [open issues](https://github.com/kaspanet/docs/issues) track missing and desired documentation. +- If you want to write about something that has no issue yet, open one first so the scope can be discussed. + +## Making changes + +1. Fork the repository and create a branch. +2. Documentation pages live in `content/docs/` as MDX files. Each section has a `meta.json` that controls page ordering and titles in the sidebar - add new pages there. +3. Code examples that accompany guides live in `examples/`. If a guide shows code, prefer keeping a matching runnable example there so it can be tested. +4. Preview your changes locally: + + ```bash + npm install + npm run dev + ``` + +5. Run the same checks CI will run: + + ```bash + npm run lint + npm run format:check + npm run types:check + npm run build + ``` + + `npm run format` fixes formatting automatically. + +6. Open a pull request against `main` describing what the change improves. + +## Writing guidelines + +- Write for a developer new to Kaspa: spell out prerequisites, ports, and flags rather than assuming them. +- Keep code examples runnable end to end - a reader should be able to copy, paste, and see output. +- When referencing Rusty Kaspa releases or versions, prefer links that stay current (e.g. `releases/latest`) over hardcoded version tags. + +## Content that doesn't belong here + +- `legacy/` is the archived pre-2026 documentation and is not maintained - improvements should go to `content/docs/` instead. +- Changes to the SDKs themselves belong in [kaspanet/rusty-kaspa](https://github.com/kaspanet/rusty-kaspa) (Rust/WASM) or [kaspanet/kaspa-python-sdk](https://github.com/kaspanet/kaspa-python-sdk) (Python). diff --git a/README.md b/README.md index 34af419..33fe6f5 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,41 @@ # Kaspa Docs -This is a Next.js application generated with -[Create Fumadocs](https://github.com/fuma-nama/fumadocs). +Source for the Kaspa documentation site - guides for integrating with Kaspa (SDK setup, wallets, transactions, running a node) and documentation of upcoming programmability features. -Run development server: +The site is a [Next.js](https://nextjs.org) app built with [Fumadocs](https://fumadocs.dev). Content is written in MDX. -```bash -npm run dev -# or -pnpm dev -# or -yarn dev -``` - -Open http://localhost:3000 with your browser to see the result. - -## Explore +## Repository layout -In the project, you can see: +| Path | Description | +| --------------- | ---------------------------------------------------------------------------------------- | +| `content/docs/` | The documentation pages (MDX). This is where most contributions land. | +| `examples/` | Runnable code examples (Node.js, browser, Rust, Java) backing the integration guides. | +| `app/` | Next.js app routes and layout. | +| `components/` | React components used by the site and MDX content. | +| `lib/` | Content source adapter and shared layout options. | +| `legacy/` | The previous markdown-only documentation, kept for reference. Not published on the site. | +| `Reference/` | Research material (papers, LaTeX sources). Not published on the site. | -- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content. -- `lib/layout.shared.tsx`: Shared options for layouts, optional but preferred to keep. +## Local development -| Route | Description | -| ------------------------- | ---------------------------------------------------- | -| `app/[[...slug]]` | The documentation layout and pages at the site root. | -| `app/api/search/route.ts` | The Route Handler for search. | +```bash +npm install +npm run dev +``` -### Fumadocs MDX +Open http://localhost:3000 to see the site. -A `source.config.ts` config file has been included, you can customise different options like frontmatter schema. +## Checks -Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details. +CI runs these on every pull request - run them locally before pushing: -## Learn More +```bash +npm run lint +npm run format:check +npm run types:check +npm run build +``` -To learn more about Next.js and Fumadocs, take a look at the following -resources: +## Contributing -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js - features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. -- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs +Contributions are welcome - see [CONTRIBUTING.md](CONTRIBUTING.md). Missing documentation is tracked in the [issues](https://github.com/kaspanet/docs/issues). diff --git a/content/docs/integrate/getting-started.mdx b/content/docs/integrate/getting-started.mdx index 309c9cd..4bb3d1b 100644 --- a/content/docs/integrate/getting-started.mdx +++ b/content/docs/integrate/getting-started.mdx @@ -3,7 +3,7 @@ title: Getting started description: Install the SDK, connect to a Kaspa node over RPC, and log DAG data in JavaScript, Rust, or Python. --- -Once that works, move to [Wallet](/integrate/wallet) for wallet creation, account management, and sending transactions or move to [Accepted Transactions](/integrate/accepted-transactions) if you're only interested into reacting to network events. +This guide walks you through installing the SDK for your language, connecting to a Kaspa node over RPC, and reading live DAG data. Once that works, move to [Wallet](/integrate/wallet) for wallet creation, account management, and sending transactions, or move to [Accepted Transactions](/integrate/accepted-transactions) if you're only interested in reacting to network events. > [!NOTE] > Full runnable examples for this guide live in [`/examples`](https://github.com/kaspanet/docs/tree/main/examples). diff --git a/content/docs/test.mdx b/content/docs/test.mdx deleted file mode 100644 index 0d4cb9a..0000000 --- a/content/docs/test.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Components -description: Components ---- - -## Code Block - -```js -console.log("Hello World"); -``` - -## Cards - - - - -