Skip to main content

Docusaurus Setup Guide

This guide will help you set up and run the Docusaurus documentation site for Synq Digital.

Prerequisites​

  • Node.js version 16.14 or above
  • npm or yarn package manager

Installation​

  1. Install Docusaurus dependencies:
npm install --save-dev @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest
npm install --save-dev prism-react-renderer

Or using yarn:

yarn add --dev @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest
yarn add --dev prism-react-renderer

Running the Documentation Site​

Development Server​

Start the development server:

npm run docs:dev

Or:

yarn docs:dev

The site will be available at http://localhost:3000

Build for Production​

Build the static site:

npm run docs:build

Or:

yarn docs:build

The built files will be in the build directory.

Serve Production Build​

Preview the production build locally:

npm run docs:serve

Or:

yarn docs:serve

Adding Screenshots​

  1. Create screenshots following the descriptions in docs/README.md
  2. Save images to static/img/ directory
  3. Update markdown files to reference images:
![Description](./static/img/filename.png)

Configuration​

Main configuration is in docusaurus.config.js. Key settings:

  • Title: Site title
  • URL: Base URL for deployment
  • Sidebar: Configured in sidebars.js

Deployment​

GitHub Pages​

  1. Set url and baseUrl in docusaurus.config.js
  2. Set organizationName and projectName
  3. Run build and deploy:
npm run docs:build
# Deploy to GitHub Pages

Other Platforms​

Docusaurus can be deployed to:

  • Netlify
  • Vercel
  • AWS S3
  • Any static hosting service

Troubleshooting​

Port Already in Use​

If port 3000 is in use:

npm run docs:dev -- --port 3001

Build Errors​

Clear cache and rebuild:

rm -rf .docusaurus
npm run docs:build

Next Steps​

  1. Add screenshots to static/img/ directory
  2. Update image references in markdown files
  3. Customize theme colors in src/css/custom.css
  4. Update footer and navbar links in docusaurus.config.js
  5. Deploy to your hosting platform