mirror of
https://github.com/twentyhq/twenty.git
synced 2026-06-13 02:19:02 -04:00
f9a24072b7
## Summary Restructures the apps Getting Started doc around the three things a developer actually has to do, so the mental model is visible upfront and discoverable when something goes wrong. **Why this matters:** the previous flow read as one continuous list of bash commands and prompts, which made it easy to miss that scaffolding, running a Twenty server, and live-syncing changes are three separate concepts. When the user hits a failure (Docker not running, server not up, auth not authorized), they have no mental map for which step they're in — so they end up retrying `yarn twenty dev`, which is the only command they remember. ## What changes **[getting-started.mdx](https://github.com/twentyhq/twenty/blob/docs/restructure-getting-started-three-phases/packages/twenty-docs/developers/extend/apps/getting-started.mdx):** - New summary table at the top showing the three-phase arc: | Phase | What you do | Tool | Result | |---|---|---|---| | **1. Scaffold** | Generate the app's source code | `npx create-twenty-app` | A TypeScript project on disk | | **2. Run a server** | Start a Twenty server to sync into | Docker + `yarn twenty server` | A running Twenty instance | | **3. Sync** | Live-sync your code to the server | `yarn twenty dev` | Your changes appear in the UI | - Three top-level sections, one per phase, each ending with **"After this phase: you have X"** so users can self-diagnose where they got stuck. - Phase 2 leads with the sentence that was missing before: *"Your app needs a Twenty server to sync into. The server is a full Twenty instance — UI, GraphQL API, PostgreSQL — running locally in Docker."* This is the concept new users were missing. - Removed the standalone *What are apps?* section — that's what the Core Concepts page is for. Don't duplicate. - Tightened wording throughout; same screenshots, same callouts, same content depth. **[core-concepts/apps.mdx](https://github.com/twentyhq/twenty/blob/docs/restructure-getting-started-three-phases/packages/twenty-docs/getting-started/core-concepts/apps.mdx):** - Removed the install snippet (`npx create-twenty-app`, `cd`, `yarn twenty dev`) — it duplicated Getting Started and the two examples used different directory names. - Updated the link card to reflect the new three-phase structure. ## Out of scope (mentioned for context, not done here) - The "Docker is not running" message rewrite: separate PR ([#20280](https://github.com/twentyhq/twenty/pull/20280)). - A `yarn twenty start` one-command bootstrap that auto-starts the server before `dev`. Worth doing — keeping it out of this docs PR. - Auto-offering to start the server when `yarn twenty dev` finds no running one. Same. - An "agent path" doc (single-page, imperative, for AI assistants) — separate effort. ## Test plan - [x] `npx nx lint twenty-docs` passes (no new warnings) - [x] All `<Note>`, `<Warning>`, `<Card>`, image refs preserved - [ ] Render and click through both pages once merged and previewed Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
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
- Twenty UI (25 pages) - UI component library documentation
🚀 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
-
Edit MDX files in the appropriate directory:
user-guide/- User documentationdevelopers/- Developer documentationtwenty-ui/- Component documentation
-
Update
navigation/base-structure.jsonif you need to change the tab/group hierarchy or add/remove pages. This file stays in the repo and is not uploaded to Crowdin. -
Keep the translation template (
navigation/navigation.template.json) in sync by runningyarn docs:generate-navigation-templateafter editing the base structure. This template is the only file that should be pushed to Crowdin. -
For each translated locale pulled from Crowdin, ensure a
packages/twenty-docs/l/<language>/navigation.jsonfile exists. These files contain labels only; page slugs always come from the base structure. -
Run
yarn docs:generateto rebuilddocs.jsonfrom 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
- Place images in the
/images/directory - Reference them in MDX:
 - 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 only, 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 runyarn docs:generateafter modifying navigation files).package.json- Package dependencies and scripts (docs:generate,docs:generate-navigation-template, …).project.json- Nx workspace configuration
📦 Building
# Build the documentation
npx nx run twenty-docs:build
🔗 Links
🤝 Contributing
To contribute to the documentation:
- Fork the repository
- Make your changes in the
packages/twenty-docsdirectory - Test locally with
npx nx run twenty-docs:dev - Submit a pull request
📄 License
This documentation is part of the Twenty project and is licensed under AGPL-3.0.