filecoin-project · nijoe1 · Dec 1, 2025 · Dec 1, 2025 · Dec 2, 2025 · Dec 5, 2025
diff --git a/.gitignore b/.gitignore
@@ -10,3 +10,8 @@ Thumbs.db
 :Zone.Identifier
 **/:Zone.Identifier
 lychee*
+_book/
+_book_temp/
+node_modules/
+package-lock.json
+.gitbook/cli/
diff --git a/README.md b/README.md
@@ -11,6 +11,7 @@
 
 - [About this repo](#about-this-repo)
 - [Contributing](#contributing)
+  - [Local Development](#local-development)
   - [Link checking](#link-checking)
 - [Issues](#issues)
   - [Backlog](#backlog)
@@ -32,6 +33,47 @@ PRs also generate preview links so one can preview the site before merging.  Per
 
 Want to help out? Pull requests (PRs) are always welcome! If you want to help out but aren't sure where to start, check out the [issues board](https://github.com/filecoin-project/filecoin-docs/issues).
 
+### Local Development
+
+You can build and preview the documentation locally using the custom CLI wrapper. This setup automatically manages the legacy Node.js v10 environment required by GitBook.
+
+#### Prerequisites
+
+- [nvm](https://github.com/nvm-sh/nvm) (Node Version Manager)
+
+  **macOS/Linux:**
+
+  ```bash
+  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+  ```
+
+  **Windows:** Use [nvm-windows](https://github.com/coreybutler/nvm-windows) or WSL
+
+#### Quick Start
+
+1. **Setup**: Installs dependencies and prepares the environment.
+
+   ```bash
+   npm run setup
+   ```
+
+2. **Develop**: Builds and serves the site with live reload.
+   ```bash
+   npm run dev
+   ```
+
+#### Commands
+
+| Command           | Description                                                                                           |
+| ----------------- | ----------------------------------------------------------------------------------------------------- |
+| `npm run setup`   | Installs dependencies and configures the legacy GitBook environment (runs automatically on first use) |
+| `npm run dev`     | Builds and serves the documentation with live reload (default port: 4003)                             |
+| `npm run build`   | Builds the static site to the `_book/` directory                                                      |
+| `npm run preview` | Serves the existing `_book/` directory without rebuilding                                             |
+| `npm run stop`    | Stops any running GitBook server instances                                                            |
+| `npm run clean`   | Removes build artifacts and dependencies                                                              |
+
+
 ### Link checking
 
 Links are checked using [lychee-action](https://github.com/lycheeverse/lychee-action) as configured by [check-external-links.yml](.github/workflows/check-external-links.yml).  Working links are required before merging.  If you have a link that should be excluded from checking:

diff --git a/book.json b/book.json
@@ -0,0 +1,4 @@
+{
+  "gitbook": "3.2.3",
+  "plugins": ["local"]
+}
diff --git a/gitbook-plugins/.gitignore b/gitbook-plugins/.gitignore
@@ -0,0 +1,2 @@
+dist/
+node_modules/
diff --git a/gitbook-plugins/assets/embed.css b/gitbook-plugins/assets/embed.css
@@ -0,0 +1,38 @@
+.embed-container {
+    margin: 1.5em 0;
+}
+
+.embed-container.youtube {
+    position: relative;
+    padding-bottom: 56.25%; /* 16:9 aspect ratio */
+    height: 0;
+    overflow: hidden;
+    max-width: 100%;
+}
+
+.embed-container.youtube iframe {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+}
+
+.embed-container.generic {
+    padding: 1em;
+    background: #f5f5f5;
+    border-radius: 4px;
+    border: 1px solid #e8e8e8;
+}
+
+.embed-container.generic a {
+    word-break: break-all;
+}
+
+.embed-caption {
+    margin-top: 0.5em;
+    font-size: 0.9em;
+    color: #666;
+    text-align: center;
+    font-style: italic;
+}
diff --git a/gitbook-plugins/assets/hints.css b/gitbook-plugins/assets/hints.css
@@ -0,0 +1,119 @@
+/* Modern hint/callout styling */
+.hint {
+    display: flex;
+    margin: 1.5em 0;
+    padding: 1em 1.25em;
+    border-radius: 8px;
+    border-left: 4px solid;
+    background: linear-gradient(135deg, rgba(255,255,255,0.9) 0%, rgba(255,255,255,0.7) 100%);
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
+}
+
+.hint-icon {
+    flex-shrink: 0;
+    font-size: 1.4em;
+    line-height: 1;
+    margin-right: 1em;
+    margin-top: 0.1em;
+}
+
+.hint-content {
+    flex: 1;
+    min-width: 0;
+}
+
+.hint-title {
+    font-weight: 600;
+    font-size: 0.9em;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    margin-bottom: 0.5em;
+}
+
+.hint-content p {
+    margin: 0;
+    line-height: 1.6;
+}
+
+.hint-content p + p {
+    margin-top: 0.75em;
+}
+
+/* Info - Blue */
+.hint-info {
+    border-left-color: #0969da;
+    background: linear-gradient(135deg, #f0f7ff 0%, #e8f2fc 100%);
+}
+
+.hint-info .hint-icon {
+    color: #0969da;
+}
+
+.hint-info .hint-title {
+    color: #0550ae;
+}
+
+/* Warning - Yellow/Orange */
+.hint-warning {
+    border-left-color: #d4a72c;
+    background: linear-gradient(135deg, #fff8e6 0%, #fef3cd 100%);
+}
+
+.hint-warning .hint-icon {
+    color: #d4a72c;
+}
+
+.hint-warning .hint-title {
+    color: #9a6700;
+}
+
+/* Danger - Red */
+.hint-danger {
+    border-left-color: #cf222e;
+    background: linear-gradient(135deg, #fff0f0 0%, #ffeaea 100%);
+}
+
+.hint-danger .hint-icon {
+    color: #cf222e;
+}
+
+.hint-danger .hint-title {
+    color: #a40e26;
+}
+
+/* Success - Green */
+.hint-success {
+    border-left-color: #1a7f37;
+    background: linear-gradient(135deg, #f0fff4 0%, #dafbe1 100%);
+}
+
+.hint-success .hint-icon {
+    color: #1a7f37;
+}
+
+.hint-success .hint-title {
+    color: #116329;
+}
+
+/* Dark mode support */
+@media (prefers-color-scheme: dark) {
+    .hint {
+        background: rgba(255, 255, 255, 0.05);
+    }
+
+    .hint-info {
+        background: rgba(9, 105, 218, 0.1);
+    }
+
+    .hint-warning {
+        background: rgba(212, 167, 44, 0.1);
+    }
+
+    .hint-danger {
+        background: rgba(207, 34, 46, 0.1);
+    }
+
+    .hint-success {
+        background: rgba(26, 127, 55, 0.1);
+    }
+}
diff --git a/gitbook-plugins/assets/tabs.css b/gitbook-plugins/assets/tabs.css
@@ -0,0 +1,42 @@
+.tabs-container {
+    margin: 1em 0;
+    border: 1px solid #e8e8e8;
+    border-radius: 4px;
+}
+
+.tabs-header {
+    display: flex;
+    flex-wrap: wrap;
+    background: #f5f5f5;
+    border-bottom: 1px solid #e8e8e8;
+}
+
+.tabs-header .tab {
+    padding: 10px 20px;
+    cursor: pointer;
+    border-bottom: 2px solid transparent;
+    margin-bottom: -1px;
+    transition: all 0.2s ease;
+}
+
+.tabs-header .tab:hover {
+    background: #eaeaea;
+}
+
+.tabs-header .tab.active {
+    background: #fff;
+    border-bottom: 2px solid #3498db;
+    font-weight: 600;
+}
+
+.tabs-body {
+    padding: 15px;
+}
+
+.tabs-body .tab-content {
+    display: none;
+}
+
+.tabs-body .tab-content.active {
+    display: block;
+}
diff --git a/gitbook-plugins/assets/tabs.js b/gitbook-plugins/assets/tabs.js
@@ -0,0 +1,34 @@
+require(["gitbook"], function (gitbook) {
+  var initTabs = function () {
+    var containers = document.querySelectorAll(".tabs-container");
+
+    containers.forEach(function (container) {
+      var headerTabs = container.querySelectorAll(".tabs-header .tab");
+      var contentTabs = container.querySelectorAll(".tabs-body .tab-content");
+
+      headerTabs.forEach(function (tab) {
+        tab.addEventListener("click", function () {
+          var tabIndex = this.getAttribute("data-tab");
+
+          // Remove active from all tabs in this container
+          headerTabs.forEach(function (t) {
+            t.classList.remove("active");
+          });
+          contentTabs.forEach(function (c) {
+            c.classList.remove("active");
+          });
+
+          // Add active to clicked tab
+          this.classList.add("active");
+          container
+            .querySelector(
+              '.tabs-body .tab-content[data-tab="' + tabIndex + '"]'
+            )
+            .classList.add("active");
+        });
+      });
+    });
+  };
+
+  gitbook.events.bind("page.change", initTabs);
+});
diff --git a/gitbook-plugins/package.json b/gitbook-plugins/package.json
@@ -0,0 +1,30 @@
+{
+  "name": "gitbook-plugin-local",
+  "version": "1.0.0",
+  "description": "GitBook.com compatibility plugin for gitbook-cli (tabs, embed, hints)",
+  "main": "dist/plugin/index.js",
+  "bin": {
+    "gitbook-cli": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "npm run build:cli && npm run build:plugin && npm run copy-assets && npm run postbuild",
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "build:plugin": "tsc -p tsconfig.plugin.json",
+    "build:watch": "tsc -p tsconfig.cli.json --watch & tsc -p tsconfig.plugin.json --watch",
+    "copy-assets": "cp -r assets dist/plugin/",
+    "postbuild": "chmod +x dist/cli/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "gitbook": ">=3.0.0"
+  },
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "ora": "5.4.1",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.25",
+    "typescript": "^4.9.5"
+  }
+}