Skip to main content

RecoApp Docs Installation

The recoapp-docs is the internal technical documentation site built with Docusaurus v3, intended for developers and RecoApp staff.

Prerequisites​

Installation Steps​

1. Clone the repository​

git clone git@github.com:craftapplied/recoapp-docs.git
cd recoapp-docs

2. Install dependencies​

pnpm install

3. Start the development server​

pnpm run start

The documentation site will be available at http://localhost:3003 with live reload enabled.

Development Workflow​

Building the documentation​

Generate the static site:

pnpm run build

This creates a production-ready build in the build/ directory.

Serving the built site​

Test the production build locally:

pnpm run serve

Type checking​

Run TypeScript type checking:

pnpm run typecheck

Clearing cache​

If you encounter caching issues:

pnpm run clear

Generate heading IDs​

Auto-generate heading IDs for documentation files:

pnpm run write-heading-ids

Project Structure​

recoapp-docs/
├── docs/                      # Documentation content (MDX/Markdown)
├── blog/                      # Blog posts (currently disabled)
├── src/
│   ├── components/            # Custom React components
│   ├── css/                   # Custom CSS styles
│   └── pages/                 # Custom pages (homepage, etc.)
├── static/                    # Static assets (images, icons)
├── docusaurus.config.ts       # Main configuration
├── sidebars.ts               # Sidebar navigation structure
└── package.json              # Dependencies and scripts

Writing Documentation​

Creating a new page​

  1. Create a new .md or .mdx file in the docs/ directory
  2. Add front matter:
---
sidebar_position: 2
title: Your Page Title
---

# Your Page Title

Content here...
  1. Test locally with pnpm run start
  2. Verify the build: pnpm run build

Using MDX​

Docusaurus supports MDX, allowing JSX in Markdown:

---
sidebar_position: 1
---

# Page Title

Regular markdown content here.

import MyComponent from "@site/src/components/MyComponent";

<MyComponent />

## Code Examples

\`\`\`typescript
// Use British English in comments
const initialiseApp = () => {
return { behaviour: 'default' };
};
\`\`\`

Organising documentation​

  • Use subdirectories in docs/ to organise by topic
  • Update sidebars.ts for custom sidebar organisation
  • Use sidebar_position in front matter to control page order
  • Keep file names lowercase with hyphens (e.g., api-reference.md)

Documentation Standards​

Language and tone​

  • Always use British English spelling (e.g., "behaviour", "colour", "organised", "analyse")
  • Assume technical audience (developers and staff)
  • Keep tone professional and concise
  • Focus on technical details and implementation

Content guidelines​

  • This is internal technical documentation (not public-facing)
  • Target audience: RecoApp developers and staff
  • Document architecture, APIs, workflows, and development processes
  • Include code examples and technical diagrams where appropriate

Configuration Files​

docusaurus.config.ts​

Main site configuration including:

  • Site metadata
  • Navbar and footer
  • Theme configuration
  • Plugin settings
  • Dev server runs on port 3003 (not default 3000)

sidebars.ts​

Controls documentation sidebar:

  • Navigation hierarchy
  • Auto-generates from docs folder by default
  • Can be manually configured for custom structure

src/pages/index.tsx​

Homepage component:

  • Hero banner
  • Feature cards
  • Links to documentation

Important Notes​

  • Port 3003: Development server runs on port 3003 (configured in package.json)
  • Blog disabled: Blog feature is currently disabled in configuration
  • React 19: Project uses React 19 and Docusaurus 3.9.2
  • TypeScript: All custom code uses TypeScript
  • No emoji: Don't add emoji to documentation unless explicitly requested
  • British English: Always use British spelling throughout

Troubleshooting​

Build fails​

  • Clear the cache: pnpm run clear
  • Delete node_modules/ and reinstall: rm -rf node_modules/ && pnpm install
  • Check for TypeScript errors: pnpm run typecheck
  • Review the build output for specific error messages

Changes not appearing​

  • Clear the Docusaurus cache: pnpm run clear
  • Hard refresh your browser (Cmd+Shift+R on macOS)
  • Restart the dev server

Port 3003 already in use​

  • Stop other services using port 3003
  • Or change the port in package.json scripts:
"start": "docusaurus start --port 3004"

TypeScript errors​

  • Run pnpm run typecheck to see detailed error messages
  • Ensure all custom components have proper type definitions
  • Check tsconfig.json for configuration issues

Deployment​

To deploy the documentation site:

pnpm run deploy

This will deploy to the configured hosting platform (e.g., GitHub Pages, Netlify).

Ensure deployment configuration is set up in docusaurus.config.ts before running this command.

Next Steps​

  • Review recoapp-docs/CLAUDE.md for detailed documentation standards
  • Explore existing documentation pages to understand the format
  • Add custom React components in src/components/ if needed
  • Customise styles in src/css/custom.css
  • Review Docusaurus documentation: https://docusaurus.io/docs