Rework documentation

Signed-off-by: Yuki Kishimoto <yukikishimoto@protonmail.com>

Author: yukibtc

.github/workflows/ci.yml

@@ -2,104 +2,112 @@ name: CI
 
 on:
   push:
-    branches: [ master ]
+    branches: [master]
   pull_request:
-    branches: [ master ]
+    branches: [master]
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
 
 jobs:
   check-book:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Setup just
         uses: extractions/setup-just@v3
 
-      - name: Rust Cache
-        uses: Swatinem/rust-cache@v2.7.8
+      - name: Cache Rust tools
+        uses: Swatinem/rust-cache@v2.9.1
 
-      - name: Check
+      - name: Build book and check links
         run: just build
 
-      - name: Upload built book
-        uses: actions/upload-artifact@v4
+      - name: Upload Pages artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v4
         with:
-          name: built-book
-          path: ./output/html
+          path: output/html
 
   check-rust:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
-      - name: Rust Cache
-        uses: Swatinem/rust-cache@v2.7.8
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2.9.1
+        with:
+          workspaces: snippets/rust
 
       - name: Check
         working-directory: snippets/rust
-        run: cargo build
+        run: cargo check --all-targets
 
   check-python:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
-          python-version: "3.12"
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: snippets/python/requirements.txt
 
       - name: Check
         working-directory: snippets/python
         run: bash check.sh
 
   check-js:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        runtime: [node, web, react-native]
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        working-directory: snippets/js/${{ matrix.runtime }}
+        run: npm install --legacy-peer-deps
 
       - name: Check
-        working-directory: snippets/js
-        run: bash check.sh
+        working-directory: snippets/js/${{ matrix.runtime }}
+        run: npm run check
 
   check-kotlin:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
-      # Required for kotlin snippets
-      - name: Set up Java 17
-        uses: actions/setup-java@v2
+      - name: Setup Java 17
+        uses: actions/setup-java@v5
         with:
-          distribution: "temurin"
-          java-version: 17
+          distribution: temurin
+          java-version: '17'
+          cache: gradle
 
       - name: Check
         working-directory: snippets/kotlin
-        run: ./gradlew build
+        run: ./gradlew build --no-daemon
 
   check-swift:
     runs-on: macos-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
       - name: Check
         working-directory: snippets/swift
@@ -109,10 +117,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
 
-      - name: Setup dotnet
-        uses: actions/setup-dotnet@v4
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v6
         with:
           dotnet-version: '10.0.x'
 
@@ -122,27 +130,26 @@ jobs:
 
   deploy:
     name: Deploy book
-    needs: [check-book, check-rust, check-python, check-js, check-kotlin, check-swift, check-csharp]
-    if: github.ref == 'refs/heads/master'
+    needs:
+      - check-book
+      - check-rust
+      - check-python
+      - check-js
+      - check-kotlin
+      - check-swift
+      - check-csharp
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    concurrency:
+      group: pages
+      cancel-in-progress: false
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Download built book
-        uses: actions/download-artifact@v4
-        with:
-          name: built-book
-          path: ./output/html
-
-      - name: Upload pages artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: './output/html'
-
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

README.md

@@ -1,19 +1,30 @@
-# Rust Nostr Book
+# Nostr Dev Kit Book
 
-## Developers
+This repository contains the source for the Nostr Dev Kit onboarding guide.
 
-### Requirements
+## Requirements
 
-* [Just](https://github.com/casey/just): install with `cargo install just`
+- [Rust](https://www.rust-lang.org/tools/install)
+- [just](https://github.com/casey/just)
+- The toolchains for any binding snippets you want to check
 
-Serve the book with:
+Install the pinned mdBook tools and serve the book:
 
 ```bash
+just init
 just serve
 ```
 
-To test all the snippets:
+Run the book build, link checker, and all locally supported snippet checks with:
 
 ```bash
-just test
+just check
 ```
+
+Swift snippets are compiled by CI on macOS. The generated site is written to
+`output/html`.
+
+## Updating the SDK release
+
+Update the SDK pins in the snippet manifests and installation examples. Run `just build` and the snippet checks supported
+by the local toolchains; CI runs the complete language matrix.

RELEASE.md

@@ -1,10 +1,11 @@
-# Release steps
+# Release checklist
 
-## Bump versions
+1. Update the SDK pins in the snippet manifests and installation examples.
+2. Update examples and platform requirements affected by the release.
+3. Run `just build` and the snippet checks supported by the local toolchains.
+4. Review the rendered book in `output/html`.
+5. Open a pull request and wait for every CI job, including the macOS Swift build.
+6. Merge to `master`; deployment starts only after the complete CI matrix passes.
 
-- Bump versions in `src/sdk/install.md`
-- Bump versions in snippets (`rust/Cargo.toml`, `python/requirements.txt`, ...)
-
-## Bump supported platforms
-
-Update the supported platforms and requirements, according to the last bindings changed.
+API reference links intentionally target the current documentation instead of a pinned release. Only installation
+examples and validation manifests are versioned.

book.toml

@@ -1,24 +1,29 @@
 [book]
-title = "Nostr Dev Kit Book"
-description = ""
+title = "Nostr Dev Kit"
+description = "A practical introduction to the Nostr Dev Kit libraries and native bindings."
 authors = ["Yuki Kishimoto <yukikishimoto@protonmail.com>", "Nostr Dev Kit Developers"]
 language = "en"
 src = "src"
 
 [build]
 build-dir = "output"
+create-missing = false
 
 [output.html]
-theme="theme"
-default-theme = "ayu"
+default-theme = "auto"
 preferred-dark-theme = "ayu"
-additional-js = ["./tabs.js"]
-git-repository-url = "https://github.com/nostrdevkit"
-
-# This line change the path of the main book build from `book/` to `book/html`.
-# If this line will be removed, the deploy book CI must be updated.
-[output.linkcheck]
-command = "mdbook-linkcheck2"
+additional-js = ["tabs.js"]
+git-repository-url = "https://github.com/nostrdevkit/book"
+site-url = "/"
+cname = "doc.nostrdevkit.org"
+input-404 = "404.md"
+sidebar-header-nav = false
 
 [preprocessor.snippets]
 after = ["links"]
+
+[output.html.playground]
+runnable = false
+
+[output.linkcheck]
+command = "mdbook-linkcheck2"

contrib/content-tabs-template.md

@@ -3,42 +3,64 @@
 <div slot="title">Rust</div>
 <section>
 
-TODO
+<!-- Rust example -->
 
 </section>
 
 <div slot="title">Python</div>
 <section>
 
-TODO
+<!-- Python example -->
 
 </section>
 
 <div slot="title">JavaScript</div>
 <section>
 
-TODO
+<custom-tabs category="javascript-runtime">
+
+<div slot="title">Node.js</div>
+<section>
+
+<!-- Node.js example -->
+
+</section>
+
+<div slot="title">Web</div>
+<section>
+
+<!-- Web example -->
+
+</section>
+
+<div slot="title">React Native</div>
+<section>
+
+<!-- React Native example -->
+
+</section>
+</custom-tabs>
 
 </section>
 
 <div slot="title">Kotlin</div>
 <section>
 
-TODO
+<!-- Kotlin example -->
 
 </section>
 
 <div slot="title">Swift</div>
 <section>
 
-TODO
+<!-- Swift example -->
 
 </section>
 
 <div slot="title">C#</div>
 <section>
 
-TODO
+<!-- C# example -->
 
 </section>
 </custom-tabs>