mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
56 lines
3.8 KiB
Plaintext
56 lines
3.8 KiB
Plaintext
---
|
|
title: "Generate docs from source repositories"
|
|
description: "Use Mintlify onboarding to generate a documentation site from an existing GitHub repository while keeping your source code read-only."
|
|
keywords: ["generate documentation", "source repository", "GitHub", "onboarding", "import documentation", "AI documentation"]
|
|
---
|
|
|
|
Mintlify can use an existing GitHub repository as read-only context when it generates your documentation. Use this workflow when your product or code lives in one repository and your documentation should live in another.
|
|
|
|
Mintlify reads your source repository but does not write to it. Mintlify writes generated pages into your documentation workspace, which you can review and publish from the web editor.
|
|
|
|
## Before you begin
|
|
|
|
- Make sure you can access the GitHub repository that contains the product or code you want to document.
|
|
- Connect a documentation repository during onboarding, or let Mintlify create a documentation repository for you.
|
|
- If the source repository is private, be ready to authorize Mintlify's GitHub App when onboarding asks for access.
|
|
|
|
## Generate documentation from a repository
|
|
|
|
1. Open [Mintlify onboarding](https://mintlify.com/start).
|
|
1. Add the URL of the GitHub repository that contains your source material. You can add more than one source repository.
|
|
1. If Mintlify cannot access a private repository, click **Authorize** and complete the GitHub authorization flow. Public repositories can be used as read-only sources without write access.
|
|
1. Click **Deploy** to start generation.
|
|
|
|
The import step also accepts an existing website as source material. Add a website URL instead of a repository URL when you want Mintlify to use published content as context.
|
|
|
|
The onboarding flow also attempts to find brand context for the generated site. Mintlify checks the domain from the first source URL, then the homepage of a connected GitHub repository, and finally the company name. When brand data is available, the generation agent uses its colors for the `docs.json` primary, light, and dark colors and selects suitable logo and favicon URLs. Brand lookup does not block generation. If no brand data is found, generation continues without these assets.
|
|
|
|
## Review generated pages
|
|
|
|
The generated documentation uses the following workflow:
|
|
|
|
1. Mintlify reads the source repositories as research context.
|
|
1. Mintlify writes documentation pages to the writable documentation workspace.
|
|
1. New pages appear in the editor navigation as they are written. Mintlify creates sidebar groups from the page path when a matching group does not exist.
|
|
1. Mintlify completes the navigation configuration after the pages are written. The final `docs.json` controls the page order and sidebar structure.
|
|
|
|
Every generated page needs complete YAML frontmatter. During generation, the `title`, `sidebarTitle`, and `description` values in the frontmatter synchronize with the page's navigation metadata when the generation agent writes or edits the page.
|
|
|
|
```mdx
|
|
---
|
|
title: "Authenticate API requests"
|
|
sidebarTitle: "Authentication"
|
|
description: "Learn how to authenticate requests to the API."
|
|
---
|
|
|
|
Explain how readers authenticate their requests.
|
|
```
|
|
|
|
Use `title` for the page title, `sidebarTitle` for a shorter navigation label, and `description` for the page description. If a field is omitted, Mintlify preserves the existing navigation value. If a page has no useful navigation title, Mintlify derives one from the page path.
|
|
|
|
## Publish your documentation
|
|
|
|
Open the generated site in the [web editor](/editor/index) to review the pages, navigation, and frontmatter. When your changes are ready, click **Publish**. You can then continue editing with the [web editor](/editor/pages) or your connected Git repository.
|
|
|
|
For a manual setup without source-repository generation, see the [quickstart](/quickstart).
|