Skip to content

The open alternative to Salesforce, designed for AI.

4.5 KB
Raw Blame

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/<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.
  • <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 UI guides, documented component props, theme tokens, or the UI package version. 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/.

The same generation and check commands maintain the committed packages/twenty-server/src/engine/metadata-modules/ai/ai-front-component/constants/generated/ui-documentation.json asset. The AI component documentation tool reads it locally; server builds copy it with the other Nest assets.

Follow the twenty-ui documentation guidelines for story roles, complete usage examples, state ownership, and composition. Run npx nx check:ui-stories twenty-docs to validate preview titles, story references, the first Display, and the absence of automated interactions in embedded stories.

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

🀝 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.