From c66104b1628d65f78af60d3e928445ef7205cd71 Mon Sep 17 00:00:00 2001 From: carlssonk Date: Sat, 13 Jun 2026 00:33:48 +0200 Subject: [PATCH 1/2] 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 - - - - - From 4d36627f91f326e87e851aeb550294b4df23533b Mon Sep 17 00:00:00 2001 From: carlssonk Date: Sat, 20 Jun 2026 22:04:34 +0200 Subject: [PATCH 2/2] Address review feedback on contributor docs --- CONTRIBUTING.md | 15 ++++++++++++--- README.md | 2 +- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c5ba53..bf5b136 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,12 +4,21 @@ Thanks for helping improve the Kaspa documentation. Contributions of all sizes a ## 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. +The [open issues](https://github.com/kaspanet/docs/issues) track missing and desired documentation, and are a good place to start. + +- Small changes (typo fixes, clarifications, broken links) can be sent as a pull request directly - no issue needed. +- For larger changes, it's worth opening an issue first so the scope can be discussed. You can still PR directly, but there's more risk of it not being merged if it turns out to be out of scope. ## Making changes -1. Fork the repository and create a branch. +1. [Fork the repository](https://github.com/kaspanet/docs/fork), then clone your fork and create a branch ([install Git](https://git-scm.com/downloads) if you don't have it): + + ```bash + git clone https://github.com//docs.git + cd docs + git switch -c my-change + ``` + 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: diff --git a/README.md b/README.md index 33fe6f5..822f85a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Kaspa Docs -Source for the Kaspa documentation site - guides for integrating with Kaspa (SDK setup, wallets, transactions, running a node) and documentation of upcoming programmability features. +Source for the Kaspa documentation site - guides for integrating with and building on Kaspa. The site is a [Next.js](https://nextjs.org) app built with [Fumadocs](https://fumadocs.dev). Content is written in MDX.