Skip to content

Commit 298bd17

Browse files
ethanpalmethanpalm
authored
Migration guide update (#961)
* Update migration.mdx * copyedit * add section header * update manual steps
1 parent 71fc218 commit 298bd17

File tree

1 file changed

+83
-35
lines changed

1 file changed

+83
-35
lines changed

‎guides/migration.mdx

Lines changed: 83 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,31 @@
11
---
22
title: "Migrations"
3-
description: "How to migrate documentation from your existing provider"
3+
description: "How to migrate documentation from your current platform"
44
icon: "import"
55
---
66

7-
Use our [public packages](https://www.npmjs.com/package/@mintlify/scraping) to convert your existing documentation to Mintlify.
7+
This guide helps you move your existing documentation to Mintlify. Choose automated migration for supported platforms or manual migration for complete control over the process.
88

9-
We currently support automated migration for:
9+
## Choose your migration path
1010

1111
<CardGroup cols="2">
12+
<Card title="Automated migration" icon="wand-sparkles">
13+
If you are migrating from Docusaurus, ReadMe, or GitBook, use our tools to automate your migration.
14+
</Card>
15+
16+
<Card title="Manual migration" icon="pencil-ruler">
17+
If you are migrating from any other platform, follow our guide to migrate your content.
18+
</Card>
19+
</CardGroup>
20+
21+
<Tabs>
22+
<Tab title="Automated migration">
23+
24+
Migrate your documentation using the [@mintlify/scraping package](https://www.npmjs.com/package/@mintlify/scraping). The package scrapes your content and converts it to use Mintlify components.
25+
26+
### Supported Platforms
27+
28+
<Columns cols="3">
1229
<Card title="Docusaurus" icon={<svg className="h-6 w-6" width="36" height="36" viewBox="0 -19 256 256" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid">
1330
<g>
1431
<rect fill="#FFFFFF" x="126.030769" y="45.9487179" width="110.276923" height="44.6358974">
@@ -78,57 +95,88 @@ We currently support automated migration for:
7895

7996
</path>
8097
</g>
81-
</svg>} horizontal>
82-
83-
</Card>
98+
</svg>} horizontal />
8499
<Card title="ReadMe" icon={<svg fill="#177fc4" className="h-6 w-6" width="36" height="36" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
85100
<path d="M29.35 4.361h-7.767c-2.672 0-4.994 1.85-5.578 4.461-0.589-2.611-2.906-4.461-5.578-4.461h-7.761c-1.472 0-2.667 1.194-2.667 2.667v13.656c0 1.472 1.194 2.667 2.667 2.667h4.983c5.678 0 7.372 1.355 8.183 4.167 0.039 0.156 0.289 0.156 0.333 0 0.817-2.811 2.511-4.167 8.183-4.167h4.983c1.472 0 2.667-1.194 2.667-2.667v-13.65c0-1.467-1.183-2.661-2.65-2.672zM13.444 19.105c0 0.106-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.105 0 0.194 0.083 0.194 0.194v1.272zM13.444 15.722c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.106 0.083-0.194 0.194-0.194h8.911c0.105 0 0.194 0.083 0.194 0.194v1.272zM13.444 12.339c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.105 0 0.194 0.083 0.194 0.194v1.272zM27.85 19.1c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.106 0 0.194 0.083 0.194 0.194v1.272zM27.85 15.717c0 0.106-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.272c0-0.105 0.083-0.194 0.194-0.194h8.911c0.106 0 0.194 0.083 0.194 0.194v1.272zM27.85 12.333c0 0.105-0.083 0.194-0.194 0.194h-8.906c-0.105 0-0.194-0.083-0.194-0.194v-1.267c0-0.105 0.083-0.194 0.194-0.194h8.911c0.106 0 0.194 0.083 0.194 0.194v1.267z"/>
86-
</svg>} horizontal>
87-
88-
</Card>
89-
</CardGroup>
101+
</svg>} horizontal />
102+
<Card title="GitBook (beta)" icon={<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" height="24" width="24">
103+
<path d="M12.513 1.097c-0.645 0 -1.233 0.34 -2.407 1.017L3.675 5.82A7.233 7.233 0 0 0 0 12.063v0.236a7.233 7.233 0 0 0 3.667 6.238L7.69 20.86c2.354 1.36 3.531 2.042 4.824 2.042 1.292 0.001 2.47 -0.678 4.825 -2.038l4.251 -2.453c1.177 -0.68 1.764 -1.02 2.087 -1.579 0.323 -0.56 0.324 -1.24 0.323 -2.6v-2.63a1.04 1.04 0 0 0 -1.558 -0.903l-8.728 5.024c-0.587 0.337 -0.88 0.507 -1.201 0.507 -0.323 0 -0.616 -0.168 -1.204 -0.506l-5.904 -3.393c-0.297 -0.171 -0.446 -0.256 -0.565 -0.271a0.603 0.603 0 0 0 -0.634 0.368c-0.045 0.111 -0.045 0.282 -0.043 0.625 0.002 0.252 0 0.378 0.025 0.494 0.053 0.259 0.189 0.493 0.387 0.667 0.089 0.077 0.198 0.14 0.416 0.266l6.315 3.65c0.589 0.34 0.884 0.51 1.207 0.51 0.324 0 0.617 -0.17 1.206 -0.509l7.74 -4.469c0.202 -0.116 0.302 -0.172 0.377 -0.13 0.075 0.044 0.075 0.16 0.075 0.392v1.193c0 0.34 0.001 0.51 -0.08 0.649 -0.08 0.14 -0.227 0.224 -0.522 0.394l-6.382 3.685c-1.178 0.68 -1.767 1.02 -2.413 1.02 -0.646 0 -1.236 -0.34 -2.412 -1.022l-5.97 -3.452 -0.043 -0.025a4.106 4.106 0 0 1 -2.031 -3.52V11.7c0 -0.801 0.427 -1.541 1.12 -1.944a1.979 1.979 0 0 1 1.982 -0.001l4.946 2.858c1.174 0.679 1.762 1.019 2.407 1.02 0.645 0 1.233 -0.34 2.41 -1.017l7.482 -4.306a1.091 1.091 0 0 0 0 -1.891L14.92 2.11c-1.175 -0.675 -1.762 -1.013 -2.406 -1.013Z" fill="#currentColor" stroke-width="1"></path>
104+
</svg>} horizontal />
105+
</Columns>
90106

91-
Don't see your documentation provider or have a custom system? We can still help! Please [contact support](/contact-support).
107+
If your documentation is hosted on another platform, see the manual migration steps.
92108

93-
## Commands
109+
### Installing the scraper
94110

95-
- `mintlify-scrape section [url]` - Scrapes multiple pages in a site.
96-
- `mintlify-scrape page [url]` - Scrapes a single page in a site.
111+
Install the `@mintlify/scraping` package to get started.
97112

98-
The commands automatically detect the framework.
113+
```bash
114+
npm install @mintlify/scraping@latest -g
115+
```
99116

100-
## Installation
117+
### Scraping pages and sections
101118

102-
You can install the package globally or for one-time use.
119+
The migration tool automatically detects your documentation platform and converts your content. Prepared files are stored locally in `./docs` by default.
103120

104-
### Global installation
121+
For large documentation sites, migrate smaller sections at a time rather than the entire site at once.
105122

123+
**Migrate entire sections:**
106124
```bash
107-
npm install @mintlify/scraping@latest -g
125+
mintlify-scrape section https://your-docs-site.com/docs
108126
```
109127

110-
### One-time use
111-
112-
<CodeGroup>
128+
**Migrate single pages:**
129+
```bash
130+
mintlify-scrape page https://your-docs-site.com/docs/getting-started
131+
```
113132

114-
```bash Section
115-
npx @mintlify/scraping@latest section [url]
133+
**Migrate OpenAPI specifications:**
134+
```bash
135+
mintlify-scrape openapi-file [openApiFilename]
116136
```
117137

138+
### Add prepared content to your Mintlify project
118139

119-
```bash Page
120-
npx @mintlify/scraping@latest page [url]
121-
```
140+
After scraping your existing documentation platform, you are ready to build your docs on Mintlify.
122141

123-
</CodeGroup>
142+
Confirm that all of your pages have been migrated then add these files to the documentation repository that you created during the onboarding process. This is usually a GitHub repository.
143+
</Tab>
144+
<Tab title="Manual migration">
124145

125-
## OpenAPI migration
146+
Migrate your documentation from any platform with full control over the process.
126147

127-
Provide the relative path or URL to the OpenAPI file to generate frontmatter files for each endpoint.
148+
### Content migration
128149

129-
```bash
130-
mintlify-scrape openapi-file [openApiFilename]
150+
To migrate your content to Mintlify, you will need:
131151

132-
-w, --writeFiles Whether or not to write the frontmatter files [boolean] [default: true]
133-
-o, --outDir The folder in which to write any created frontmatter files [string]
134-
```
152+
- A valid `docs.json` for your site settings and navigation. See [Global settings](/settings) and [Navigation](/navigation) for more information.
153+
- An `MDX` file for each page of your documentation. See [Pages](/pages) for more information.
154+
- (Optional) An OpenAPI specification for your API endpoint pages. See [OpenAPI setup](/api-playground/openapi-setup) for more information.
155+
156+
1. If your content is already in `MDX` format, copy the pages to your Mintlify project. Otherwise, convert your content to `MDX` format.
157+
2. Create your `docs.json` referencing the paths to your `MDX` pages.
158+
3. If you have OpenAPI specifications, add them to your `docs.json` and configure the API playground.
159+
160+
### Asset migration
161+
162+
1. Copy assets to your repository's `images/` directory.
163+
2. Update references in your `MDX` files:
164+
```mdx
165+
![Alt text](/images/screenshot.png)
166+
```
167+
168+
</Tab>
169+
</Tabs>
170+
171+
## Post-migration checklist
172+
173+
After completing your migration (automated or manual), we recommend checking:
174+
175+
- All pages render
176+
- Navigation works as intended
177+
- Internal links resolve properly
178+
- Images and assets load correctly
179+
- Code blocks display with proper syntax highlighting
180+
- Search functionality works
181+
- Deployment is configured
182+
- Custom domain is set up

0 commit comments

Comments
 (0)