KAI Documentation Site Deployment
This guide explains how to deploy the KAI documentation as a website with a sidebar navigation to https://github.com/Basilakis/kai-readme.github.io.
Overview
The deployment process:
- Converts all markdown files in the
/readme/
folder to Docusaurus-compatible format - Organizes them into categories for the sidebar
- Builds a Docusaurus site
- Deploys the site to GitHub Pages
Setup Instructions
Manual Deployment
To manually deploy the documentation site:
- Make sure you have Node.js 20 or later installed
- Run the deployment script:
# Make the script executable
chmod +x deploy-readme-site.sh
# Run the script
./deploy-readme-site.sh
-
The script will:
- Create a temporary Docusaurus site
- Process all markdown files from the
/readme/
folder - Build the site
- Provide instructions for deployment
-
To test the site locally:
cd kai-docs-temp
npm run start
Automated Deployment with GitHub Actions
The repository includes a GitHub Actions workflow that automatically deploys the documentation site whenever changes are made to the /readme/
folder.
To set up automated deployment:
- Push this repository to GitHub
- The built-in GITHUB_TOKEN should have sufficient permissions for deployment
- The workflow will automatically run when changes are pushed to the
/readme/
folder - You can also manually trigger the workflow from the Actions tab
Customization
Modifying Categories
The documentation is organized into categories in the process-readme-files.js
script. To modify the categories:
- Edit the
categories
object inprocess-readme-files.js
- Add or remove files from each category
- Run the deployment script again
Customizing the Site
To customize the Docusaurus site:
- Edit the
docusaurus.config.js
file in thekai-docs-temp
directory - Modify the theme, navigation, or other settings
- Run the deployment script again
Technology Stack
The documentation site is built using:
- Docusaurus 3.7 - The latest version of Docusaurus, providing modern features and improved performance
- React 18 - For interactive UI components
- Node.js 20 - For optimal compatibility with modern JavaScript features
- Yarn - For dependency management
Troubleshooting
If you encounter issues with the deployment:
- Check that all dependencies are installed
- Verify that the GitHub token has the correct permissions
- Check the GitHub Actions logs for any errors
- Ensure the repository settings allow GitHub Pages deployment
Common Issues
EUNSUPPORTEDPROTOCOL Error
If you see an error like npm error code EUNSUPPORTEDPROTOCOL
or Unsupported URL Type "workspace:"
, this is because some Docusaurus templates use workspace protocol references in the package.json file. Our solution avoids this issue by:
- Creating a custom Docusaurus setup from scratch instead of using the default template
- Using ES modules syntax instead of CommonJS
- Using Yarn instead of npm for installation when available
This approach completely avoids the workspace protocol issue and provides a modern, stable deployment process.
Requirements
- Node.js 20 or higher
- Git
- GitHub account with permissions to create repositories