Skip to content

Commit 84a0011

Browse files
nijoe1nijoe1
committed
feat: implements local development workflow with custom gitbook-cli wrapper
- Replaces legacy gitbook-cli with a custom local wrapper - Automatically manages Node v10 via nvm for GitBook compatibility - Adds live reload/watch mode
1 parent 8dad654 commit 84a0011

25 files changed

+1626
-2
lines changed

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,7 @@ Thumbs.db
1010
:Zone.Identifier
1111
**/:Zone.Identifier
1212
lychee*
13+
_book/
14+
_book_temp/
15+
node_modules/
16+
package-lock.json

‎README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111

1212
- [About this repo](#about-this-repo)
1313
- [Contributing](#contributing)
14+
- [Local Development](#local-development)
1415
- [Link checking](#link-checking)
1516
- [Issues](#issues)
1617
- [Backlog](#backlog)
@@ -32,6 +33,47 @@ PRs also generate preview links so one can preview the site before merging. Per
3233

3334
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).
3435

36+
### Local Development
37+
38+
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.
39+
40+
#### Prerequisites
41+
42+
- [nvm](https://github.com/nvm-sh/nvm) (Node Version Manager)
43+
44+
**macOS/Linux:**
45+
46+
```bash
47+
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
48+
```
49+
50+
**Windows:** Use [nvm-windows](https://github.com/coreybutler/nvm-windows) or WSL
51+
52+
#### Quick Start
53+
54+
1. **Setup**: Installs dependencies and prepares the environment.
55+
56+
```bash
57+
npm run setup
58+
```
59+
60+
2. **Develop**: Builds and serves the site with live reload at http://localhost:4003.
61+
```bash
62+
npm run dev
63+
```
64+
65+
#### Commands
66+
67+
| Command | Description |
68+
| ----------------- | ----------------------------------------------------------------------------------------------------- |
69+
| `npm run setup` | Installs dependencies and configures the legacy GitBook environment (runs automatically on first use) |
70+
| `npm run dev` | Builds and serves the documentation with live reload (default port: 4003) |
71+
| `npm run build` | Builds the static site to the `_book/` directory |
72+
| `npm run preview` | Serves the existing `_book/` directory without rebuilding |
73+
| `npm run stop` | Stops any running GitBook server instances |
74+
| `npm run clean` | Removes build artifacts and dependencies |
75+
76+
3577
### Link checking
3678

3779
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:

‎book.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"plugins": ["local"]
3+
}

‎gitbook-plugins/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
dist/
2+
node_modules/

‎gitbook-plugins/assets/embed.css‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
.embed-container {
2+
margin: 1.5em 0;
3+
}
4+
5+
.embed-container.youtube {
6+
position: relative;
7+
padding-bottom: 56.25%; /* 16:9 aspect ratio */
8+
height: 0;
9+
overflow: hidden;
10+
max-width: 100%;
11+
}
12+
13+
.embed-container.youtube iframe {
14+
position: absolute;
15+
top: 0;
16+
left: 0;
17+
width: 100%;
18+
height: 100%;
19+
}
20+
21+
.embed-container.generic {
22+
padding: 1em;
23+
background: #f5f5f5;
24+
border-radius: 4px;
25+
border: 1px solid #e8e8e8;
26+
}
27+
28+
.embed-container.generic a {
29+
word-break: break-all;
30+
}
31+
32+
.embed-caption {
33+
margin-top: 0.5em;
34+
font-size: 0.9em;
35+
color: #666;
36+
text-align: center;
37+
font-style: italic;
38+
}

‎gitbook-plugins/assets/hints.css‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
/* Modern hint/callout styling */
2+
.hint {
3+
display: flex;
4+
margin: 1.5em 0;
5+
padding: 1em 1.25em;
6+
border-radius: 8px;
7+
border-left: 4px solid;
8+
background: linear-gradient(135deg, rgba(255,255,255,0.9) 0%, rgba(255,255,255,0.7) 100%);
9+
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
10+
}
11+
12+
.hint-icon {
13+
flex-shrink: 0;
14+
font-size: 1.4em;
15+
line-height: 1;
16+
margin-right: 1em;
17+
margin-top: 0.1em;
18+
}
19+
20+
.hint-content {
21+
flex: 1;
22+
min-width: 0;
23+
}
24+
25+
.hint-title {
26+
font-weight: 600;
27+
font-size: 0.9em;
28+
text-transform: uppercase;
29+
letter-spacing: 0.5px;
30+
margin-bottom: 0.5em;
31+
}
32+
33+
.hint-content p {
34+
margin: 0;
35+
line-height: 1.6;
36+
}
37+
38+
.hint-content p + p {
39+
margin-top: 0.75em;
40+
}
41+
42+
/* Info - Blue */
43+
.hint-info {
44+
border-left-color: #0969da;
45+
background: linear-gradient(135deg, #f0f7ff 0%, #e8f2fc 100%);
46+
}
47+
48+
.hint-info .hint-icon {
49+
color: #0969da;
50+
}
51+
52+
.hint-info .hint-title {
53+
color: #0550ae;
54+
}
55+
56+
/* Warning - Yellow/Orange */
57+
.hint-warning {
58+
border-left-color: #d4a72c;
59+
background: linear-gradient(135deg, #fff8e6 0%, #fef3cd 100%);
60+
}
61+
62+
.hint-warning .hint-icon {
63+
color: #d4a72c;
64+
}
65+
66+
.hint-warning .hint-title {
67+
color: #9a6700;
68+
}
69+
70+
/* Danger - Red */
71+
.hint-danger {
72+
border-left-color: #cf222e;
73+
background: linear-gradient(135deg, #fff0f0 0%, #ffeaea 100%);
74+
}
75+
76+
.hint-danger .hint-icon {
77+
color: #cf222e;
78+
}
79+
80+
.hint-danger .hint-title {
81+
color: #a40e26;
82+
}
83+
84+
/* Success - Green */
85+
.hint-success {
86+
border-left-color: #1a7f37;
87+
background: linear-gradient(135deg, #f0fff4 0%, #dafbe1 100%);
88+
}
89+
90+
.hint-success .hint-icon {
91+
color: #1a7f37;
92+
}
93+
94+
.hint-success .hint-title {
95+
color: #116329;
96+
}
97+
98+
/* Dark mode support */
99+
@media (prefers-color-scheme: dark) {
100+
.hint {
101+
background: rgba(255, 255, 255, 0.05);
102+
}
103+
104+
.hint-info {
105+
background: rgba(9, 105, 218, 0.1);
106+
}
107+
108+
.hint-warning {
109+
background: rgba(212, 167, 44, 0.1);
110+
}
111+
112+
.hint-danger {
113+
background: rgba(207, 34, 46, 0.1);
114+
}
115+
116+
.hint-success {
117+
background: rgba(26, 127, 55, 0.1);
118+
}
119+
}

‎gitbook-plugins/assets/tabs.css‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
.tabs-container {
2+
margin: 1em 0;
3+
border: 1px solid #e8e8e8;
4+
border-radius: 4px;
5+
}
6+
7+
.tabs-header {
8+
display: flex;
9+
flex-wrap: wrap;
10+
background: #f5f5f5;
11+
border-bottom: 1px solid #e8e8e8;
12+
}
13+
14+
.tabs-header .tab {
15+
padding: 10px 20px;
16+
cursor: pointer;
17+
border-bottom: 2px solid transparent;
18+
margin-bottom: -1px;
19+
transition: all 0.2s ease;
20+
}
21+
22+
.tabs-header .tab:hover {
23+
background: #eaeaea;
24+
}
25+
26+
.tabs-header .tab.active {
27+
background: #fff;
28+
border-bottom: 2px solid #3498db;
29+
font-weight: 600;
30+
}
31+
32+
.tabs-body {
33+
padding: 15px;
34+
}
35+
36+
.tabs-body .tab-content {
37+
display: none;
38+
}
39+
40+
.tabs-body .tab-content.active {
41+
display: block;
42+
}

‎gitbook-plugins/assets/tabs.js‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
require(["gitbook"], function (gitbook) {
2+
var initTabs = function () {
3+
var containers = document.querySelectorAll(".tabs-container");
4+
5+
containers.forEach(function (container) {
6+
var headerTabs = container.querySelectorAll(".tabs-header .tab");
7+
var contentTabs = container.querySelectorAll(".tabs-body .tab-content");
8+
9+
headerTabs.forEach(function (tab) {
10+
tab.addEventListener("click", function () {
11+
var tabIndex = this.getAttribute("data-tab");
12+
13+
// Remove active from all tabs in this container
14+
headerTabs.forEach(function (t) {
15+
t.classList.remove("active");
16+
});
17+
contentTabs.forEach(function (c) {
18+
c.classList.remove("active");
19+
});
20+
21+
// Add active to clicked tab
22+
this.classList.add("active");
23+
container
24+
.querySelector(
25+
'.tabs-body .tab-content[data-tab="' + tabIndex + '"]'
26+
)
27+
.classList.add("active");
28+
});
29+
});
30+
});
31+
};
32+
33+
gitbook.events.bind("page.change", initTabs);
34+
});

‎gitbook-plugins/package.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"name": "gitbook-plugin-local",
3+
"version": "1.0.0",
4+
"description": "GitBook.com compatibility plugin for gitbook-cli (tabs, embed, hints)",
5+
"main": "dist/plugin/index.js",
6+
"bin": {
7+
"gitbook-cli": "./dist/cli/index.js"
8+
},
9+
"scripts": {
10+
"build": "npm run build:cli && npm run build:plugin && npm run copy-assets && npm run postbuild",
11+
"build:cli": "tsc -p tsconfig.cli.json",
12+
"build:plugin": "tsc -p tsconfig.plugin.json",
13+
"build:watch": "tsc -p tsconfig.cli.json --watch & tsc -p tsconfig.plugin.json --watch",
14+
"copy-assets": "cp -r assets dist/plugin/",
15+
"postbuild": "chmod +x dist/cli/index.js",
16+
"prepublishOnly": "npm run build"
17+
},
18+
"engines": {
19+
"gitbook": ">=3.0.0"
20+
},
21+
"dependencies": {
22+
"chokidar": "^3.6.0",
23+
"ora": "5.4.1",
24+
"picocolors": "^1.1.1"
25+
},
26+
"devDependencies": {
27+
"@types/node": "^20.19.25",
28+
"typescript": "^5.9.3"
29+
}
30+
}

0 commit comments

Comments
 (0)