Docusaurus Documentation Module Manager
A specialized skill for managing and maintaining Docusaurus-based documentation sites, specifically designed for the Codomyrmex project's documentation module.
What This Skill Does
This skill helps you work with a Docusaurus documentation site by:
Managing documentation structure and contentConfiguring Docusaurus settings and navigationMaintaining consistent formatting across documentationAdding new modules and updating sidebarsTesting and validating documentation changesInstructions
1. Understanding the Documentation Structure
Before making any changes:
Review `documentation/README.md` for the documentation hub overviewExamine `docusaurus.config.js` for site metadata, theme, plugins, navbar, and footer configurationCheck `sidebars.js` to understand the navigation hierarchyFamiliarize yourself with the `docs/` directory structure: - `docs/intro.md` - Landing page
- `docs/modules/` - Module-specific documentation
- `docs/project/` - Project-wide documents
2. Creating or Modifying Documentation Content
When working with documentation files:
**Use consistent Markdown formatting** with proper frontmatter: ```markdown
---
sidebar_label: Display Name
title: Page Title
slug: /url-slug
id: unique-id
---
```
**Ensure clarity and accuracy** - Documentation must be easy to understand and technically correct**Follow the established structure** for module documentation: - Overview
- API documentation
- MCP (Model Context Protocol) details
- Changelog
- Security considerations
- Usage examples
- Detailed documentation/tutorials
**Verify all links** - Use relative links for internal documentation, verify external links are accessible3. Adding a New Module to Documentation
When documenting a new Codomyrmex module:
1. Create a subdirectory under `docs/modules/[module-name]/`
2. Add the module's documentation files following the standard structure
3. Update `sidebars.js` to include the new module in navigation
4. Reference the tutorial at `documentation/docs/modules/documentation/docs/tutorials/example_tutorial.md`
5. Test navigation to ensure the module appears correctly in the sidebar
4. Configuring Docusaurus
When modifying `docusaurus.config.js`:
**Understand the impact** - Changes affect the entire site**Key configuration areas**: - Site metadata (title, tagline, url, baseUrl)
- Theme configuration
- Plugin settings
- Navbar items
- Footer links
**Always test** after making configuration changesWhen updating `sidebars.js`:
Ensure correct document IDs match the `id` in frontmatterUse accurate file paths relative to the `docs/` directoryMaintain logical grouping and hierarchyTest navigation after changes5. Adding Custom Components
If creating custom React components for Docusaurus:
Place components in `src/components/`Follow React best practicesTest components thoroughly before integrationDocument component usage for other contributorsEnsure components are accessible and responsive6. Styling the Documentation Site
When modifying styles:
Edit `src/css/custom.css` for custom stylingFollow existing CSS conventionsTest styling across different viewport sizesEnsure color contrast meets accessibility standardsAvoid overriding core Docusaurus styles unless necessary7. Testing Documentation Changes
Always perform these validation steps:
1. **Run the development server**:
```bash
cd documentation
npm run start
# or
yarn start
```
2. **Navigate through affected sections**:
- Check page rendering
- Verify all links work correctly
- Test sidebar navigation
- Confirm frontmatter displays properly
3. **Build the production site**:
```bash
npm run build
# or
yarn build
```
- Ensure the build completes without errors
- Fix any warnings or broken links
4. **Preview the production build**:
```bash
npm run serve
# or
yarn serve
```
8. Managing Meta-Documentation
The `documentation/docs/modules/documentation/` directory contains documentation about the documentation module itself:
Keep this meta-documentation currentUpdate technical overviews when making significant changesMaintain tutorials for managing the doc siteDocument any custom workflows or processes9. Static Assets
When adding images or other static files:
Place files in the `static/` directoryUse descriptive filenamesReference assets using `/img/filename.ext` in MarkdownOptimize images for web (appropriate size and format)Add alt text for all images10. Final Checklist
Before committing documentation changes:
[ ] Docusaurus site builds successfully (`npm run build`)[ ] Development server runs without errors (`npm run start`)[ ] All navigation links work correctly[ ] New content follows established formatting standards[ ] Sidebar navigation is logical and complete[ ] Internal links use correct relative paths[ ] External links are valid and accessible[ ] Frontmatter is properly configured on all pages[ ] Documentation for all modules is consistently presented[ ] Meta-documentation is updated if the documentation structure changedExample Usage
**Adding a new module:**
```markdown
1. Create docs/modules/new-module/overview.md
2. Add module entry to sidebars.js
3. Test: npm run start
4. Verify navigation and rendering
5. Build: npm run build
```
**Updating configuration:**
```markdown
1. Edit docusaurus.config.js
2. Test: npm run start
3. Check navbar/footer changes
4. Build: npm run build
5. Verify no warnings
```
Important Notes
These rules supplement `general.cursorrules` - always follow general rules unless explicitly overridden hereChanges to `docusaurus.config.js` and `sidebars.js` affect the entire site - test thoroughlyDocumentation accuracy is critical - verify technical details before publishingMaintain consistency across all module documentationAlways preview changes locally before committing