Skip to content

Commit ff2f0c9

Browse files
jonathanprozzijonathanprozzi
committed
Merge branch 'main' of github.com:0xIntuition/published-docs
2 parents c148ebb + 94babde commit ff2f0c9

File tree

4 files changed

+328
-20
lines changed

4 files changed

+328
-20
lines changed

‎README.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,74 @@
1+
# Intuition Documentation Site
12

3+
This repository contains the source code for Intuition's technical documentation site, built using [Docusaurus](https://docusaurus.io/) and integrated with Notion for content management. Implementation details on the document publishing pipeline can be found in `doc-publishing-process.md`.
4+
5+
## Overview
6+
7+
The documentation is organized into three main sections:
8+
- **Concepts**: Core concepts and general documentation
9+
- **Contracts**: Smart contract documentation and protocol specifications
10+
- **Dev Tools**: Developer tools and integration guides
11+
12+
## Architecture
13+
14+
The site uses a hybrid approach for documentation management:
15+
- Content is authored and maintained in Notion
16+
- GitHub Actions automatically sync Notion content to the repository
17+
- Docusaurus builds and serves the documentation site
18+
19+
### Key Components
20+
21+
- **Docusaurus Configuration**: Multi-instance setup with three documentation sections
22+
- **Notion Integration**: Using `@sillsdev/docu-notion` for Notion-to-Markdown conversion
23+
- **GitHub Actions**: Automated workflow for content syncing and deployment
24+
25+
## Local Development
26+
27+
1. Install dependencies:
28+
```bash
29+
yarn install
30+
```
31+
32+
2. Pull content from Notion (requires proper environment variables):
33+
```bash
34+
yarn pull:all
35+
```
36+
37+
3. Deploy to localhost:
38+
```bash
39+
yarn start
40+
```
41+
42+
## Environment Variables
43+
44+
The following environment variables are required for Notion integration:
45+
- `DOCU_NOTION_INTEGRATION_TOKEN`: Notion API integration token
46+
- `DOCU_NOTION_CONCEPT_ROOT_PAGE`: Root page ID for Concepts section
47+
- `DOCU_NOTION_DEV_ROOT_PAGE`: Root page ID for Dev Tools section
48+
- `DOCU_NOTION_CONTRACTS_ROOT_PAGE`: Root page ID for Contracts section
49+
50+
## Documentation Structure
51+
52+
```
53+
docs/
54+
├── concepts/ # Main documentation
55+
├── dev/ # Developer tools documentation
56+
└── contracts/ # Smart contract documentation
57+
```
58+
59+
## Deployment
60+
61+
The documentation is automatically deployed through GitHub Actions when changes are pushed to the main branch. The workflow:
62+
1. Pulls content from Notion
63+
2. Converts to Markdown
64+
3. Commits to the gh-pages branch
65+
4. Deploys to GitHub Pages
66+
67+
## Contributing
68+
**Functional changes:**
69+
1. Create a new branch from `main`
70+
2. Make your changes
71+
3. Submit a pull request
72+
73+
**Content changes:**
74+
For content changes, please open an issue with the suggested content and a team member will make updates to Notion if the change is approved.

‎doc-publishing-process.md

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# Documentation Publishing Process
2+
3+
This document explains the inner workings of how our documentation is published when the GitHub Actions workflow is triggered.
4+
5+
## Overview
6+
7+
Our documentation publishing process uses a combination of Notion, GitHub Actions, and Docusaurus to create a seamless documentation pipeline. Here's a detailed breakdown of how it works.
8+
9+
## The Publishing Pipeline
10+
11+
### 1. Content Creation in Notion
12+
13+
- Content is authored and maintained in three separate Notion workspaces:
14+
- Concepts documentation (main docs)
15+
- Dev Tools documentation
16+
- Contracts documentation
17+
- Each workspace has its own root page ID stored in GitHub Secrets:
18+
- `DOCU_NOTION_CONCEPT_ROOT_PAGE`
19+
- `DOCU_NOTION_DEV_ROOT_PAGE`
20+
- `DOCU_NOTION_CONTRACTS_ROOT_PAGE`
21+
22+
### 2. GitHub Actions Workflow Trigger
23+
24+
The workflow (`release.yml`) is triggered by either:
25+
- A push to the `main` branch
26+
- Manual trigger through GitHub Actions UI
27+
28+
### 3. Content Synchronization Process
29+
30+
1. **Environment Setup**
31+
- Checkout repository
32+
- Setup Node.js
33+
- Install dependencies
34+
35+
2. **Notion Content Pull**
36+
- Clears all previously committed doc files (can remove this step if we want to preserve previously published pages)
37+
- Creates directory structure (`docs/concepts`, `docs/dev`, `docs/contracts`)
38+
- Uses `@sillsdev/docu-notion` to pull content from Notion
39+
- Converts Notion pages to Markdown files
40+
- Downloads and processes any images
41+
42+
4. **File Organization**
43+
- Markdown files are generated with proper frontmatter
44+
- Images are stored in `static/notion_imgs`
45+
- Directory hierarchy is preserved from respective 'Outline' pages within each Notion workspace
46+
47+
### 4. Git Operations
48+
49+
1. **Staging Changes**
50+
- All Markdown files are staged using `git add`
51+
- Changes are committed with message "Apply changes from docu-notion"
52+
53+
2. **Building the Site**
54+
- Docusaurus builds the site using the new content
55+
- Output is generated in the `build` directory
56+
57+
3. **Deployment to gh-pages**
58+
- The built site is deployed to the `gh-pages` branch
59+
- This branch contains:
60+
- The compiled static site
61+
- The raw Markdown files
62+
- All assets and images
63+
64+
## Important Implementation Details
65+
The site uses three documentation instances by running `@sillsdev/docu-notion` on each of the Notion workspaces and directing page downloads to specific folders within the directory when the workflow is ran.
66+
67+
### Package.json Scripts
68+
69+
The following scripts in `package.json` handle pulling content from Notion:
70+
71+
```javascript
72+
{
73+
"scripts": {
74+
"clear-docs": "rimraf ./docs/",
75+
"pull:concepts": "cross-var yarn docu-notion -n $DOCU_NOTION_INTEGRATION_TOKEN -r $DOCU_NOTION_CONCEPT_ROOT_PAGE -m ./docs/concepts -i ./static/notion_imgs -p /notion_imgs/",
76+
"pull:dev": "cross-var yarn docu-notion -n $DOCU_NOTION_INTEGRATION_TOKEN -r $DOCU_NOTION_DEV_ROOT_PAGE -m ./docs/dev -i ./static/notion_imgs -p /notion_imgs/",
77+
"pull:contracts": "cross-var yarn docu-notion -n $DOCU_NOTION_INTEGRATION_TOKEN -r $DOCU_NOTION_CONTRACTS_ROOT_PAGE -m ./docs/contracts -i ./static/notion_imgs -p /notion_imgs/",
78+
"pull:all": "yarn clear-docs && yarn pull:concepts && yarn pull:dev && yarn pull:contracts"
79+
}
80+
}
81+
```
82+
83+
Each script:
84+
- Uses `cross-var` for cross-platform environment variable support
85+
- Specifies target directory for markdown files (`-m`)
86+
- Configures image storage location (`-i`) and public path (`-p`)
87+
88+
### Docu-notion Configuration
89+
90+
The `.docu-notion.json` file controls how content is pulled from Notion and organized in the documentation:
91+
92+
```javascript
93+
{
94+
"sections": [
95+
{
96+
"rootPage": "DOCU_NOTION_CONCEPT_ROOT_PAGE",
97+
"targetDirectory": "docs/concepts",
98+
"title": "Concepts",
99+
"preserveHierarchy": true
100+
},
101+
{
102+
"rootPage": "DOCU_NOTION_DEV_ROOT_PAGE",
103+
"targetDirectory": "docs/dev",
104+
"title": "Dev Tools",
105+
"preserveHierarchy": true
106+
},
107+
{
108+
"rootPage": "DOCU_NOTION_CONTRACTS_ROOT_PAGE",
109+
"targetDirectory": "docs/contracts",
110+
"title": "Contracts",
111+
"preserveHierarchy": true
112+
}
113+
],
114+
"cleanUrls": true,
115+
"downloadImages": true,
116+
"customTransformers": [],
117+
"debug": true
118+
}
119+
```
120+
121+
This configuration:
122+
- **Sections**: Defines multiple documentation sections, each with:
123+
- `rootPage`: Environment variable for the Notion root page ID
124+
- `targetDirectory`: Where markdown files will be generated
125+
- `title`: Section title used in navigation
126+
- `preserveHierarchy`: Maintains Notion's page structure in the output
127+
128+
- **Global Settings**:
129+
- `cleanUrls`: Generates URL-friendly filenames
130+
- `downloadImages`: Automatically downloads and processes Notion images
131+
- `debug`: Enables detailed logging during content pulling
132+
- `customTransformers`: Array for custom content transformation rules
133+
134+
### Sidebar Configuration
135+
136+
The `sidebars.js` file is configured to handle all three documentation sections:
137+
138+
```javascript
139+
const sidebars = {
140+
docs: [
141+
{
142+
type: 'autogenerated',
143+
dirName: '.'
144+
}
145+
],
146+
devSidebar: [
147+
{
148+
type: 'autogenerated',
149+
dirName: '.'
150+
}
151+
],
152+
contractsSidebar: [
153+
{
154+
type: 'autogenerated',
155+
dirName: '.'
156+
}
157+
]
158+
};
159+
160+
module.exports = sidebars;
161+
```
162+
163+
This configuration:
164+
- Uses `autogenerated` type to automatically create sidebars from directory structure
165+
- `docs` sidebar for main concepts documentation
166+
- `devSidebar` for developer tools documentation
167+
- `contractsSidebar` for contracts documentation
168+
- Each sidebar uses `dirName: '.'` to reference its root directory as configured in the Docusaurus plugins
169+
170+
171+
### Docusaurus Configuration
172+
173+
1. **Main Docs (Concepts)**
174+
```javascript
175+
docs: {
176+
path: 'docs/concepts',
177+
routeBasePath: '/',
178+
sidebarPath: require.resolve('./sidebars.js'),
179+
}
180+
```
181+
182+
2. **Dev Tools**
183+
```javascript
184+
{
185+
id: 'dev',
186+
path: 'docs/dev',
187+
routeBasePath: 'dev',
188+
}
189+
```
190+
191+
3. **Contracts**
192+
```javascript
193+
{
194+
id: 'contracts',
195+
path: 'docs/contracts',
196+
routeBasePath: 'contracts',
197+
}
198+
```
199+
200+
### Branch Structure
201+
202+
- `main` branch: Contains source code and configuration
203+
- `gh-pages` branch: Contains:
204+
- Built static site in root
205+
- Raw Markdown files in respective directories
206+
- Static assets and images
207+
208+
## Troubleshooting Common Issues
209+
210+
1. **Missing Content**
211+
- Check Notion page permissions
212+
- Verify environment variables are set correctly
213+
- Review GitHub Actions logs for pull errors
214+
215+
2. **Broken Links**
216+
- Ensure Notion links are properly formatted
217+
- Check for case sensitivity in file paths
218+
- Verify route configuration in `docusaurus.config.js`
219+
220+
3. **Sidebar Issues**
221+
- Confirm sidebar IDs match plugin IDs
222+
- Check directory structure matches configuration
223+
- Verify frontmatter in Markdown files
224+
225+
## Best Practices
226+
227+
1. **Content Management**
228+
- Make all content changes in Notion - future builds will overwrite any content changes made in Github
229+
- Use consistent page hierarchy
230+
- Follow Notion formatting guidelines
231+
232+
2. **Development**
233+
- Test changes locally before pushing
234+
- Monitor GitHub Actions logs
235+
- Keep configuration files in sync
236+
237+
3. **Deployment**
238+
- Review built content before merging to main
239+
- Monitor deployment logs
240+
- Verify changes on the live site

‎docusaurus.config.js

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@ const config = {
3131
require.resolve('./css/gifplayer.css'),
3232
],
3333
},
34+
gtag: {
35+
trackingID: 'G-PZPB85CM46',
36+
anonymizeIP: false,
37+
},
3438
},
3539
],
3640
],
@@ -109,22 +113,24 @@ const config = {
109113
},
110114
items: [
111115
{
112-
to: '/',
113-
label: 'Concepts',
116+
type: 'doc',
117+
docId: 'Introduction',
114118
position: 'left',
115-
className: 'V3_active',
119+
label: 'Concepts',
116120
},
117121
{
118-
to: '/contracts/protocol-overview',
119-
label: 'Contracts',
122+
type: 'doc',
123+
docId: 'protocol-overview',
124+
docsPluginId: 'contracts',
120125
position: 'left',
121-
className: 'V3_active',
126+
label: 'Contracts',
122127
},
123128
{
124-
to: '/dev/overview',
125-
label: 'Dev Tools',
129+
type: 'doc',
130+
docId: 'overview',
131+
docsPluginId: 'dev',
126132
position: 'left',
127-
className: 'V3_active',
133+
label: 'Dev Tools',
128134
},
129135
{
130136
to: 'https://github.com/0xIntuition',

‎sidebars.js

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,3 @@
1-
/**
2-
* Creating a sidebar enables you to:
3-
- create an ordered group of docs
4-
- render a sidebar for each doc of that group
5-
- provide next/previous navigation
6-
7-
The sidebars can be generated from the filesystem, or explicitly defined here.
8-
9-
Create as many sidebars as you want.
10-
*/
11-
121
// @ts-check
132

143
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */

0 commit comments

Comments
 (0)