Skip to content

Commit 2eebaee

Browse files
vibhathavibhatha
committed
fix: adding guideline
1 parent 3efded7 commit 2eebaee

30 files changed

Lines changed: 209 additions & 5051 deletions

‎docs/DOCS_GUIDELINE.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Docusaurus Setup & Deployment Guide
2+
3+
This guide provides a standardized approach to setting up, configuring, and deploying Docusaurus documentation sites to GitHub Pages, based on best practices and lessons learned from the OpenGIN project.
4+
5+
## 1. Prerequisites & Environment
6+
* **Node.js Version**: Docusaurus 3.x requires Node.js **>= 18.0**. We recommend enforcing **Node.js 20 (LTS)** or higher in the project to avoid version mismatches.
7+
* **Package Manager**: `npm` is standard, key dependencies must be locked.
8+
9+
### Recommended Configuration
10+
Add or update the `engines` field in your `package.json` to enforce the Node version:
11+
12+
```json
13+
"engines": {
14+
"node": ">=20.0"
15+
}
16+
```
17+
18+
Create a `.nvmrc` file in the root of your docs directory:
19+
```text
20+
20
21+
```
22+
23+
## 2. Configuration (`docusaurus.config.js`)
24+
25+
### Essential GitHub Pages Settings
26+
Configuring `url` and `baseUrl` correctly is critical for assets to load on GitHub Pages.
27+
28+
```javascript
29+
// docusaurus.config.js
30+
const config = {
31+
// ...
32+
url: 'https://<ORG_NAME>.github.io', // Your GitHub Pages domain
33+
baseUrl: '/<REPO_NAME>/', // The name of your repository with slashes
34+
35+
// GitHub Deployment Config
36+
organizationName: '<ORG_NAME>',
37+
projectName: '<REPO_NAME>',
38+
39+
// Handling Broken Links
40+
onBrokenLinks: 'throw', // Recommended: Break build on broken links
41+
onBrokenMarkdownLinks: 'warn',
42+
43+
// ...
44+
};
45+
```
46+
47+
### Dynamic Base URL (Optional but Recommended)
48+
For PR previews or local testing where the path might differ, you can make `baseUrl` dynamic:
49+
50+
```javascript
51+
baseUrl: process.env.BASE_URL || '/<REPO_NAME>/',
52+
```
53+
54+
## 3. GitHub Actions Workflows
55+
56+
We use two primary workflows: one for **production deployment** (on push to main) and one for **PR previews**.
57+
58+
### A. Production Deployment (`.github/workflows/deploy-docs.yml`)
59+
60+
<details>
61+
<summary>Click to see template</summary>
62+
63+
```yaml
64+
name: Deploy to GitHub Pages
65+
66+
on:
67+
push:
68+
branches:
69+
- main
70+
paths:
71+
- 'docs/**' # specific directory trigger
72+
workflow_dispatch:
73+
74+
permissions:
75+
contents: write # REQUIRED for pushing to gh-pages branch
76+
77+
jobs:
78+
deploy:
79+
runs-on: ubuntu-latest
80+
defaults:
81+
run:
82+
working-directory: docs # Set if docs are in a subdir
83+
steps:
84+
- uses: actions/checkout@v4
85+
86+
- uses: actions/setup-node@v4
87+
with:
88+
node-version: 20
89+
cache: npm
90+
cache-dependency-path: docs/package-lock.json
91+
92+
- name: Install dependencies
93+
run: npm ci
94+
95+
- name: Build website
96+
run: npm run build
97+
98+
- name: Deploy to GitHub Pages
99+
uses: peaceiris/actions-gh-pages@v3
100+
with:
101+
github_token: ${{ secrets.GITHUB_TOKEN }}
102+
publish_dir: ./docs/build
103+
```
104+
</details>
105+
106+
### B. PR Preview (`.github/workflows/preview-docs.yml`)
107+
108+
<details>
109+
<summary>Click to see template</summary>
110+
111+
```yaml
112+
name: Deploy PR Preview
113+
114+
on:
115+
pull_request_target:
116+
types: [opened, reopened, synchronize, closed]
117+
paths: ['docs/**']
118+
119+
permissions:
120+
contents: write
121+
pull-requests: write
122+
issues: write
123+
124+
jobs:
125+
deploy-preview:
126+
runs-on: ubuntu-latest
127+
defaults:
128+
run:
129+
working-directory: docs
130+
steps:
131+
- uses: actions/checkout@v4
132+
with:
133+
ref: ${{ github.event.pull_request.head.sha }} # Checkout PR code
134+
135+
- uses: actions/setup-node@v4
136+
with:
137+
node-version: 20
138+
cache: npm
139+
cache-dependency-path: docs/package-lock.json
140+
141+
- name: Install dependencies
142+
run: npm ci
143+
144+
- name: Deploy preview
145+
uses: rossjrw/pr-preview-action@v1
146+
with:
147+
source_dir: docs/build
148+
preview_branch: gh-pages
149+
umbrella_dir: pr-preview
150+
action: auto
151+
build_script: npm run build
152+
env:
153+
# Crucial for assets to load in the preview sub-path
154+
BASE_URL: /<REPO_NAME>/pr-preview/${{ github.event.number }}/
155+
```
156+
</details>
157+
158+
## 4. Common Pitfalls & Solutions
159+
160+
### "Remote Rejected ... Repository Rule Violations"
161+
**Cause:** The `gh-pages` branch (used for deployment) has "Branch Protection Rules" enabled that prevent the GitHub Actions bot from pushing.
162+
**Fix:**
163+
1. Go to Repo Settings -> Rules -> Rulesets (or Branches).
164+
2. Add a bypass for the `github-actions` app on the `gh-pages` branch.
165+
3. Alternatively, disable "Require pull request before merging" for `gh-pages`.
166+
167+
### "Exit Code 1" during Build (Node Version)
168+
**Cause:** Docusaurus 3.x failing on Node 16 or 18.
169+
**Fix:** Ensure `actions/setup-node` uses `node-version: 20` and `package.json` engines are set.
170+
171+
## 5. Master Prompt for AI Agents
172+
Use the following prompt to instruct an AI assistant to set this up for a new project.
173+
174+
---
175+
176+
**Copy & Paste this Prompt:**
177+
178+
> I need to set up Docusaurus documentation for this project with automatic deployment to GitHub Pages. Please follow these specific guidelines based on our organization's standards:
179+
>
180+
> 1. **Project Structure**:
181+
> * Initialize a new Docusaurus project in a `docs/` subdirectory if one doesn't exist.
182+
> * Use `npm` for package management.
183+
> * Ensure `package.json` enforces `engines: { "node": ">=20.0" }`.
184+
> * Create an `.nvmrc` file with `20`.
185+
>
186+
> 2. **Configuration (`docusaurus.config.js`)**:
187+
> * Set `url` to `https://<ORG_NAME>.github.io`.
188+
> * Set `baseUrl` to `/<REPO_NAME>/` but allow it to be overridden by `process.env.BASE_URL` (for PR previews).
189+
> * Set `onBrokenLinks` to `'throw'` and `onBrokenMarkdownLinks` to `'warn'`.
190+
> * Ensure `organizationName` and `projectName` are set correctly.
191+
>
192+
> 3. **CI/CD Workflows (GitHub Actions)**:
193+
> * Create `.github/workflows/deploy-docs.yml`:
194+
> * Trigger on `push` to `main` (filtered to `docs/` path).
195+
> * Use `permissions: contents: write`.
196+
> * Use `actions/setup-node@v4` with version `20`.
197+
> * Use `peaceiris/actions-gh-pages@v3` for deployment.
198+
> * Create `.github/workflows/preview-docs.yml` (Optional):
199+
> * Trigger on `pull_request` to `main`.
200+
> * Use `rossjrw/pr-preview-action@v1`.
201+
> * Pass the correct `BASE_URL` environment variable to the build script to ensure assets load in the preview sub-path.
202+
>
203+
> 4. **Verification**:
204+
> * Remind me to check "Branch Protection Rules" for the `gh-pages` branch if the push fails.
205+
> * Verify that the build command (`npm run build`) succeeds locally with Node 20.
206+
>
207+
> Please analyze the current repository structure and generate the necessary files and changes.
208+
209+
---

‎docs_deprecated/appendix/data-type-detection-patterns.md‎

Lines changed: 0 additions & 72 deletions
This file was deleted.

0 commit comments

Comments
 (0)