upstream-twenty/packages/twenty-docs

Twenty Documentation

Official documentation for Twenty CRM, powered by Mintlify.

🌐 Live Site

Visit the documentation at docs.twenty.com

📚 Content

This repository contains:

• User Guide (46 pages) - Complete guide for Twenty users
• Developers (24 pages) - Technical documentation for developers
• UI Library - Guides, primitives, and components

🚀 Local Development

To run the documentation locally:

# From the twenty monorepo root
npx nx run twenty-docs:dev

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

📝 Editing Content

Adding/Editing Pages

1. Edit MDX files in the appropriate directory:

   • user-guide/ - User documentation
   • developers/ - Developer documentation
   • ui/ - UI library guides, with primitive references under ui/primitives/ and app building blocks under ui/components/

2. Update navigation/base-structure.json if you need to change the tab/group hierarchy or add/remove pages. This file stays in the repo and is not uploaded to Crowdin.

3. Keep the translation template (navigation/navigation.template.json) in sync by running yarn docs:generate-navigation-template after editing the base structure. This template is the only file that should be pushed to Crowdin.

4. For each translated locale pulled from Crowdin, ensure a packages/twenty-docs/l/<language>/navigation.json file exists. These files contain labels only; page slugs always come from the base structure.

5. Run yarn docs:generate to rebuild docs.json from the base structure + translated labels.

MDX Format

All documentation pages use MDX format with frontmatter:

---
title: Page Title
description: Page description
image: /images/path/to/image.png
---

Your content here...

Adding Images

1. Place images in the /images/ directory
2. Reference them in MDX: ![Alt text](/images/your-image.png)
3. Or use Mintlify Frame component:

<Frame>
  <img src="/images/your-image.png" alt="Description" />
</Frame>

🔧 Configuration

• navigation/base-structure.json - Source of truth for tabs, groups, icons, and page slugs (English source labels, not sent to Crowdin).
• navigation/navigation.template.json - Generated translation template (labels only) that is uploaded to Crowdin.
• l/<language>/navigation.json - Locale-specific label files pulled from Crowdin.
• docs.json - Generated Mintlify configuration (always run yarn docs:generate after modifying navigation files).
• package.json - Package dependencies and scripts (docs:generate, docs:generate-navigation-template, …).
• project.json - Nx workspace configuration

📦 Validation

# Validate the documentation build
npx nx run twenty-docs:validate

UI reference generation

Run npx nx generate:ui twenty-docs after changing documented component props or theme tokens. Run npx nx check:ui twenty-docs to check generated references and compile the UI guide examples against the public entry points. Hand-written pages live under ui/; generated snippets live under snippets/ui/generated/.

UI guides, component pages, and navigation labels use the existing Crowdin translation workflow. Translated pages appear in their locale’s navigation once the corresponding files exist. Generated API and token snippets are shared across locales and maintained by the reference generator.

🔗 Links

• Twenty Website
• GitHub Repository
• Mintlify Documentation

🤝 Contributing

To contribute to the documentation:

1. Fork the repository
2. Make your changes in the packages/twenty-docs directory
3. Test locally with npx nx run twenty-docs:dev
4. Submit a pull request

📄 License

This documentation is part of the Twenty project and is licensed under AGPL-3.0.