@mintlify/cli 4.0.1762 → 4.0.1764
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +18 -0
- package/__test__/agent-setup-config.test.ts +314 -0
- package/__test__/agent-setup.test.ts +207 -0
- package/__test__/migrate.test.ts +186 -0
- package/__test__/validateRules.test.ts +36 -0
- package/bin/agent-setup-config.js +141 -0
- package/bin/agent-setup.js +146 -0
- package/bin/cli.js +65 -0
- package/bin/migrate.js +54 -0
- package/bin/tsconfig.build.tsbuildinfo +1 -1
- package/bin/validate/files.js +16 -4
- package/bin/validate/mdx.js +1 -1
- package/bin/welcome.js +1 -0
- package/migrate/index.md +56 -0
- package/migrate/sources/confluence.md +120 -0
- package/migrate/sources/docsify.md +128 -0
- package/migrate/sources/document360.md +117 -0
- package/migrate/sources/docus.md +136 -0
- package/migrate/sources/docusaurus.md +143 -0
- package/migrate/sources/fern.md +130 -0
- package/migrate/sources/fumadocs.md +141 -0
- package/migrate/sources/gitbook.md +120 -0
- package/migrate/sources/github-wiki.md +90 -0
- package/migrate/sources/jekyll.md +104 -0
- package/migrate/sources/mdbook.md +98 -0
- package/migrate/sources/mkdocs.md +113 -0
- package/migrate/sources/nextra.md +144 -0
- package/migrate/sources/notion.md +99 -0
- package/migrate/sources/nuxt.md +113 -0
- package/migrate/sources/pdf.md +99 -0
- package/migrate/sources/readme.md +118 -0
- package/migrate/sources/redocly.md +114 -0
- package/migrate/sources/starlight.md +136 -0
- package/migrate/sources/vitepress.md +143 -0
- package/migrate/sources/vuepress.md +153 -0
- package/migrate/topics/api.md +76 -0
- package/migrate/topics/changelog.md +47 -0
- package/migrate/topics/conversion.md +194 -0
- package/migrate/topics/discovery.md +93 -0
- package/migrate/topics/navigation.md +82 -0
- package/migrate/topics/verify.md +58 -0
- package/package.json +12 -10
- package/src/agent-setup-config.ts +144 -0
- package/src/agent-setup.ts +165 -0
- package/src/cli.tsx +91 -0
- package/src/migrate.ts +76 -0
- package/src/validate/files.ts +23 -3
- package/src/validate/mdx.ts +1 -1
- package/src/welcome.ts +1 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Redocly
|
|
2
|
+
|
|
3
|
+
Covers Redocly projects built with Realm, Revel, Reef or Redoc.
|
|
4
|
+
|
|
5
|
+
## Detect
|
|
6
|
+
|
|
7
|
+
- Any of: `sidebars.yaml` or `<name>.sidebars.yaml`; `.md` pages with Markdoc tags (`{% admonition`, `{% tabs`, `{% partial`); `_partials/`, `@theme/` or `@l10n/` folders; `*.page.tsx`; `@redocly/realm`, `@redocly/revel`, `@redocly/reef` or `@redocly/redoc` in `package.json`. Projects built in Reunite may have no `package.json`.
|
|
8
|
+
- A `redocly.yaml` with only `extends`, `rules`, `decorators`, `preprocessors`, `plugins`, `apis`, `resolve` or `telemetry` is a Redocly CLI lint/bundle config, not a docs site. Leave it and migrate the framework that serves the docs.
|
|
9
|
+
- Legacy Developer Portal: `siteConfig.yaml`, `theme.ts`, `@redocly/developer-portal`, `.mdx` pages with `:::` admonitions. Navigation below applies; content is MDX, not Markdoc.
|
|
10
|
+
- Standalone Redoc embed (`redoc.standalone.js`, `<redoc spec-url>`, `redocly build-docs`): migrate only the OpenAPI file.
|
|
11
|
+
|
|
12
|
+
## Get the source
|
|
13
|
+
|
|
14
|
+
### From the repo
|
|
15
|
+
|
|
16
|
+
- File-based routing (https://redocly.com/docs/platform/content/project-structure): a file's path is its URL without the extension; `index.md` serves its folder. API description files render as references at their own path.
|
|
17
|
+
- Not published: partials folders (`_partials/`), `@theme/`, the root `README.md`, `ignore` globs. `static/` is copied as-is.
|
|
18
|
+
- Resolve `$ref` in `redocly.yaml` (for example `redirects: { $ref: ./redirects.yaml }`) and per-folder `redocly.yaml` files.
|
|
19
|
+
|
|
20
|
+
### From an export
|
|
21
|
+
|
|
22
|
+
Not covered yet. Use the repo or the live site.
|
|
23
|
+
|
|
24
|
+
### From the live site
|
|
25
|
+
|
|
26
|
+
Realm publishes `/llms.txt` with Markdown copies of pages unless `seo.llmstxt.hide` is set.
|
|
27
|
+
|
|
28
|
+
## Config → docs.json
|
|
29
|
+
|
|
30
|
+
| redocly.yaml | docs.json |
|
|
31
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
|
|
32
|
+
| `seo.title` / `seo.description` | `name` / `description` |
|
|
33
|
+
| `seo.meta`, `seo.keywords` | `seo.metatags` |
|
|
34
|
+
| `logo.image` / `logo.srcSet` (`"l.svg light, d.svg dark"`) / `logo.link` | `logo` / `logo.light` + `logo.dark` / `logo.href` |
|
|
35
|
+
| `logo.favicon` | `favicon` |
|
|
36
|
+
| `navbar.items` | Navigation below |
|
|
37
|
+
| `footer.items` columns, `copyrightText` | `footer.links`, `footer.socials`; report copyright |
|
|
38
|
+
| `redirects` | URLs below |
|
|
39
|
+
| `colorMode` with `ignoreDetection` and dark first | `appearance` (`default: "dark"`, `strict: true`) |
|
|
40
|
+
| `banner` | `banner` (first untargeted one) |
|
|
41
|
+
| `analytics.ga.trackingId`, `analytics.gtm.trackingId` | `integrations.ga4.measurementId`, `integrations.gtm.tagId` |
|
|
42
|
+
| `analytics.amplitude`, `segment`, `heap`, `adobe` | the matching `integrations.*` entry |
|
|
43
|
+
| `scripts`, `links` | `mint migrate --topic navigation`, Chrome |
|
|
44
|
+
| `markdown.lastUpdatedBlock` | `metadata.timestamp` |
|
|
45
|
+
| `products` | `navigation.products` |
|
|
46
|
+
| `apis`, `decorators` | keep in `redocly.yaml`; see Assets |
|
|
47
|
+
| `l10n` | `navigation.languages`, if the user migrates other languages |
|
|
48
|
+
| `seo.siteUrl` | none; its host is part of every old URL |
|
|
49
|
+
| `access`, `rbac`, `requiresLogin`, `sso`, catalog and scorecard keys, `mockServer`, `aiAssistant`, `mcp`, `feedback`, `search`, `breadcrumbs`, `codeSnippet`, `*.hide`, `@theme/` overrides | drop and report; report every RBAC-protected path |
|
|
50
|
+
|
|
51
|
+
Reference: https://redocly.com/docs/platform/config
|
|
52
|
+
|
|
53
|
+
## Navigation
|
|
54
|
+
|
|
55
|
+
Reference: https://redocly.com/docs/platform/navigation/sidebars
|
|
56
|
+
|
|
57
|
+
- No sidebar file: the file tree in natural sort order, `index` first.
|
|
58
|
+
- `sidebars.yaml` entries: `page` (+ `label`) → page; `group` + `items` → group (`page` → `root`; `expanded: true` or `always` → `expanded: true`); `directory` → that folder's pages in natural order; `href` → `navigation.global.anchors`; `$ref` → inline the referenced sidebar; `separator` → start a group named by its text; `separatorLine` → drop; `badges` → `tag`; `icon` → `icon`; `rbac`, `disconnect`, `additionalProps`, `external`, translation keys → drop.
|
|
59
|
+
- An API description listed as a `page` → a group with that spec's `openapi`.
|
|
60
|
+
- Top-level `tab:` entries (with `page`/`items` or `menu`) → tabs; a `menu` → tab `menu`. One `sidebars.yaml` per section folder, each linked from `navbar.items`, also means one tab per section.
|
|
61
|
+
- `navbar.items`: an item opening a section with its own sidebar → that section's tab; external `href` items → `navbar.links`; a sign-up button → `navbar.primary`.
|
|
62
|
+
- Sidebar labels default to the page's first heading.
|
|
63
|
+
|
|
64
|
+
## Content conversion
|
|
65
|
+
|
|
66
|
+
Every Markdoc tag must go (`mint migrate --topic conversion`, Template tags). Reference: https://redocly.com/docs/platform/content/markdoc-tags
|
|
67
|
+
|
|
68
|
+
| Markdoc | Mintlify |
|
|
69
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
|
|
70
|
+
| `{% admonition type="info\|warning\|success\|danger\|idea" name="T" %}` | `<Info>`, `<Warning>`, `<Check>`, `<Danger>`, `<Tip>`; `name` per `mint migrate --topic conversion`, Components |
|
|
71
|
+
| `{% tabs %}` / `{% tab label="X" %}` | `<Tabs>` / `<Tab>`; `<CodeGroup>` when every tab is one fence |
|
|
72
|
+
| `{% code-group %}` (`mode="dropdown"`) | `<CodeGroup>` (`dropdown`) |
|
|
73
|
+
| fence annotation ` ```js {% title="x" %} ` | fence title; report other annotation keys |
|
|
74
|
+
| `{% partial file="..." variables={...} /%}`; `{% $var %}` inside | `mint migrate --topic conversion`, Reusable content |
|
|
75
|
+
| `{% raw-partial file="..." /%}` | the file's text inline |
|
|
76
|
+
| `{% code-snippet file="..." title="..." /%}` (with `from`/`to`/`before`/`after`) | `mint migrate --topic conversion`, Code imports |
|
|
77
|
+
| `{% cards %}` / `{% card title to icon image %}` | `<Columns>` / `<Card title href icon img>` |
|
|
78
|
+
| `{% accordion-group %}` / `{% accordion title expanded %}` | `<AccordionGroup>` / `<Accordion defaultOpen>` |
|
|
79
|
+
| `{% numbered-list %}` / `{% numbered-item %}` | `<Steps>` / `<Step>` (the item's first heading as title) |
|
|
80
|
+
| `{% img src alt caption /%}` | image in `<Frame caption>` |
|
|
81
|
+
| `{% diagram type="mermaid" %}` | `mermaid` fence; export PlantUML and Excalidraw to SVG and report |
|
|
82
|
+
| `{% icon name /%}` | `<Icon>` |
|
|
83
|
+
| `{% table %}` | Markdown table, or HTML for `colspan`/`rowspan` |
|
|
84
|
+
| `{% if %}` / `{% else /%}` | the branch the public site shows; report, especially `$rbac` / `$user` conditions |
|
|
85
|
+
| `{% $frontmatter.x %}`, `{% $env.X %}` | `mint migrate --topic conversion`, Template tags |
|
|
86
|
+
| `{% json-schema %}`, `{% openapi-code-sample %}`, `{% openapi-response-sample %}`, `{% replay-openapi %}` | link to the endpoint page or a static example; report |
|
|
87
|
+
| `{% code-walkthrough %}`, `{% login-button %}`, `{% connect-mcp %}`, `{% markdoc-example %}`, `{% prompt %}`, custom tags in `@theme/markdoc/` | rewrite as prose or built-in components; report |
|
|
88
|
+
| `## Heading {% #id %}` / `{% .class %}` | `mint migrate --topic conversion`, Heading IDs / delete |
|
|
89
|
+
| frontmatter `excludeFromSearch: true` | `searchable: false` |
|
|
90
|
+
| frontmatter `seo.description` | `description` |
|
|
91
|
+
| frontmatter `slug`, `redirects` | URLs below |
|
|
92
|
+
| frontmatter `sidebar`, `template`, `navigation`, `markdown`, `metadata`, `navbar`, `footer`, `breadcrumbs`, `codeSnippet`, `feedback`, `banner`, `rbac`, `versionPicker` | drop |
|
|
93
|
+
|
|
94
|
+
## Assets
|
|
95
|
+
|
|
96
|
+
- Referenced images and files keep their paths; `static/` files keep their root paths.
|
|
97
|
+
- API decorators (`apis.<name>.decorators` or root `decorators`) change what readers see (`mint migrate --topic api`). `npx @redocly/cli bundle <api-name> --output <file>` writes a spec with them applied.
|
|
98
|
+
- Redoc vendor extensions: `x-codeSamples` carries over (`mint migrate --topic api`); `x-tagGroups`, `x-logo`, `x-traitTag`, `x-badges` do not (recreate tag grouping in navigation; report the rest).
|
|
99
|
+
|
|
100
|
+
## URLs and redirects
|
|
101
|
+
|
|
102
|
+
- Content pages keep their file paths. Frontmatter `slug` (string or list) overrides the path; extra slugs and frontmatter `redirects` become redirects.
|
|
103
|
+
- `redirects` (`'/from': { to: '/to', type: 301 }`) → a redirect each; `type` 302/307 → `permanent: false`; a trailing `/*` → `:slug*` on both sides (`mint migrate --topic navigation`, Redirects).
|
|
104
|
+
- API references sit at the spec's file path with operation pages beneath it. Take old operation URLs from `sitemap.xml` and keep them per `mint migrate --topic api`.
|
|
105
|
+
- Hash links into Redoc (`#tag/...`, `#operation/...`): rewrite in-content links (`mint migrate --topic navigation`, Redirects).
|
|
106
|
+
|
|
107
|
+
## Known gaps
|
|
108
|
+
|
|
109
|
+
- RBAC, login and SSO; role-based conditionals.
|
|
110
|
+
- Replay console, mock server, API catalog, scorecards.
|
|
111
|
+
- Code walkthroughs, custom Markdoc tags, `*.page.tsx` pages, theme overrides.
|
|
112
|
+
- Redoc vendor extensions without a Mintlify equivalent.
|
|
113
|
+
- `@l10n/` locales and `@<version>/` folders, unless the user migrates them.
|
|
114
|
+
- Heading anchors (`mint migrate --topic conversion`, Heading IDs).
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Starlight
|
|
2
|
+
|
|
3
|
+
Astro integration for docs. Pages are Markdown, MDX or Markdoc content-collection entries; config is the `starlight({...})` call inside the Astro config.
|
|
4
|
+
|
|
5
|
+
## Detect
|
|
6
|
+
|
|
7
|
+
- Repo: `astro.config.{mjs,ts,mts,js}` that imports `@astrojs/starlight` and calls `starlight({...})` in `integrations`; `@astrojs/starlight` in `package.json`; pages under `src/content/docs/`; `src/content.config.ts` using `docsLoader()` / `docsSchema()`.
|
|
8
|
+
- Live site: `<meta name="generator" content="Starlight ...">` next to an Astro generator tag; `/_astro/` asset URLs; `<starlight-theme-select>` / `<starlight-toc>` elements.
|
|
9
|
+
- The `starlight(` call (or the Starlight generator tag) wins. An Astro site without it is not Starlight.
|
|
10
|
+
|
|
11
|
+
## Get the source
|
|
12
|
+
|
|
13
|
+
### From the repo
|
|
14
|
+
|
|
15
|
+
- Pages: every `.md`, `.mdx`, `.mdoc` under `src/content/docs/`. Custom routes in `src/pages/` (`.astro`, `.html`) are not content: list them and report.
|
|
16
|
+
- Read the whole Astro config, every file it imports (sidebar arrays are often split out), `src/content.config.ts` (schema `extend` adds frontmatter keys), and `ec.config.mjs` if present.
|
|
17
|
+
- i18n: each `locales` key is a folder under `src/content/docs/` (`fr/`, `zh-cn/`); a `root` locale lives directly in `src/content/docs/`. No built-in versioning: a versioning plugin in `plugins` holds the extra trees; read its config (`mint migrate --topic navigation`, Structure rules).
|
|
18
|
+
- `draft: true` pages never reach production: mark them `excluded`.
|
|
19
|
+
|
|
20
|
+
### From an export
|
|
21
|
+
|
|
22
|
+
None; the site is built from the repo.
|
|
23
|
+
|
|
24
|
+
### From the live site
|
|
25
|
+
|
|
26
|
+
Find the repo through the "Edit page" link (`editLink.baseUrl`). Otherwise list URLs from `/sitemap-index.xml` (generated when `site` is set) and convert each page's `.sl-markdown-content` element.
|
|
27
|
+
|
|
28
|
+
## Config → docs.json
|
|
29
|
+
|
|
30
|
+
Reference: https://starlight.astro.build/reference/configuration/
|
|
31
|
+
|
|
32
|
+
| Starlight | docs.json |
|
|
33
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
|
|
34
|
+
| `title` (string, or per-locale object) | `name` (default-locale value) |
|
|
35
|
+
| `description` | `description` |
|
|
36
|
+
| `logo.src` or `logo.light` / `logo.dark` | `logo` (string or `{ light, dark }`); move the files from `src/` into the repo |
|
|
37
|
+
| `logo.replacesTitle`, `logo.alt` | drop and report |
|
|
38
|
+
| `favicon` (path in `public/`) | `favicon` |
|
|
39
|
+
| `social` (array of `{ icon, label, href }`; older object form `{ github: url }`) | `navbar.links` (Starlight shows them in the header); GitHub/Discord entries take `type` |
|
|
40
|
+
| `head` `meta` tags | `seo.metatags` |
|
|
41
|
+
| `head` analytics scripts (gtag, GTM, Plausible, ...) | matching `integrations.*` key; other scripts: drop and report |
|
|
42
|
+
| `lastUpdated: true` | `metadata.timestamp: true` |
|
|
43
|
+
| `expressiveCode.themes` | `styling.codeblocks` (only Shiki theme names) |
|
|
44
|
+
| `locales`, `defaultLocale` | `navigation.languages`, `default: true` on the default |
|
|
45
|
+
| `sidebar` | `navigation` (see Navigation) |
|
|
46
|
+
| `plugins` | per plugin: OpenAPI plugins → `mint migrate --topic api`; anything else: drop and report |
|
|
47
|
+
| `editLink`, `tableOfContents`, `pagination`, `pagefind`, `customCss`, `components` (overrides), `credits`, `titleDelimiter`, `disable404Route`, `routeMiddleware`, `markdown.headingLinks` | drop and report |
|
|
48
|
+
| Astro `site`, `base`, `trailingSlash` | no field; see URLs and redirects |
|
|
49
|
+
| Astro `redirects` | `redirects` (see URLs and redirects) |
|
|
50
|
+
|
|
51
|
+
## Navigation
|
|
52
|
+
|
|
53
|
+
Reference: https://starlight.astro.build/guides/sidebar/
|
|
54
|
+
|
|
55
|
+
- No `sidebar` config: Starlight autogenerates from the whole `src/content/docs/` tree (one group per folder, labelled with the folder name as written). Expand it the same way as `autogenerate` below.
|
|
56
|
+
- `'path/slug'` string or `{ slug }` → page `path/slug`. Label comes from the page `title`; a `label` override → `sidebarTitle` on that page.
|
|
57
|
+
- `{ label, link }` → not a page. External or non-docs links: report them (`mint migrate --topic navigation`, Structure rules).
|
|
58
|
+
- `{ label, items: [...] }` → `{ "group": label, "pages": [...] }`, recursing in order.
|
|
59
|
+
- `{ label, autogenerate: { directory } }` and `{ label, items: [{ autogenerate: { directory } }] }` → one group whose `pages` are the files of `directory`, each subfolder a nested group labelled with the folder name. A bare `{ autogenerate }` at any level splices its entries into the parent.
|
|
60
|
+
- Autogenerated order: alphabetical by file id; `sidebar.order` in a page's frontmatter overrides it (lower first). Confirm the merged order against the rendered sidebar (`npx astro build` then read `dist/`, or the live site) before writing it.
|
|
61
|
+
- Page frontmatter `sidebar.label` → `sidebarTitle`; `sidebar.hidden: true` → leave the page out of `navigation`; `sidebar.badge` (string or `{ text, variant }`) → page `tag` with the text. These only apply to autogenerated and `slug` entries.
|
|
62
|
+
- Item or group `badge` → page `tag` / group `tag` (text only; drop `variant`, `class`).
|
|
63
|
+
- `collapsed`: Starlight groups default open. Nested group without `collapsed: true` → `"expanded": true`. `autogenerate.collapsed: true` → leave its subgroups unexpanded. `collapsed` on a top-level group has no equivalent: report.
|
|
64
|
+
- `translations` on items/groups → the label for that group in each `navigation.languages` entry. Sidebar `slug`s omit the locale prefix: prepend the locale folder per language.
|
|
65
|
+
- `attrs` (on items, `autogenerate`, or `sidebar.attrs` frontmatter) → drop and report.
|
|
66
|
+
|
|
67
|
+
## Content conversion
|
|
68
|
+
|
|
69
|
+
Syntax reference: https://starlight.astro.build/guides/authoring-content/
|
|
70
|
+
|
|
71
|
+
| Starlight | Mintlify |
|
|
72
|
+
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
73
|
+
| `:::note` / `<Aside>` / `<Aside type="note">` | `<Note>` |
|
|
74
|
+
| `:::tip` / `<Aside type="tip">` | `<Tip>` |
|
|
75
|
+
| `:::caution` / `<Aside type="caution">` | `<Warning>` |
|
|
76
|
+
| `:::danger` / `<Aside type="danger">` | `<Danger>` |
|
|
77
|
+
| `:::tip[Title]` / `<Aside title="Title">` | same callout (`mint migrate --topic conversion`, Components) |
|
|
78
|
+
| aside `{icon="..."}` / `icon` prop | drop and report |
|
|
79
|
+
| `<Tabs syncKey>` + `<TabItem label icon>` | `<Tabs>` + `<Tab title icon>` (drop `syncKey`) |
|
|
80
|
+
| `<Tabs>` whose items each hold only one code block | `<CodeGroup>`, `label` → fence title |
|
|
81
|
+
| `<Card title icon>` | `<Card title icon>` |
|
|
82
|
+
| `<LinkCard title href description>` | `<Card title href>` with `description` as body |
|
|
83
|
+
| `<CardGrid>` (`stagger` dropped) | `<Columns cols={2}>` |
|
|
84
|
+
| `<LinkButton href variant icon>` | Markdown link; report `variant` |
|
|
85
|
+
| `<Steps>` around an ordered list | `<Steps>`, one `<Step title>` per item, title from the item's lead line; keep a plain list if items have no lead line |
|
|
86
|
+
| `<FileTree>` nested list | `<FileTree>` nested list; strip trailing comments and bold highlights, keep `…` lines as plain items |
|
|
87
|
+
| `<Badge text variant size>` | `<Badge>text</Badge>`; variant → `color` (note blue, tip purple, caution yellow, danger red, success green, default gray); drop `size` |
|
|
88
|
+
| `<Icon name>` | `<Icon icon>` with a Font Awesome match, else drop |
|
|
89
|
+
| `<Code code lang title mark>` | fenced block; resolve `?raw` imports and variables (`mint migrate --topic conversion`, Code imports) |
|
|
90
|
+
| `<details><summary>S</summary>` | `<Accordion title="S">` |
|
|
91
|
+
| Markdoc `{% aside %}`, `{% tabs %}`, ... (`.mdoc`) | the same mappings |
|
|
92
|
+
| `import ... from '@astrojs/starlight/components'`, `astro:assets` | delete (`mint migrate --topic conversion`, Components) |
|
|
93
|
+
| other `.astro` / framework component imports | (`mint migrate --topic conversion`, Components) |
|
|
94
|
+
|
|
95
|
+
Expressive Code fence meta (https://expressive-code.com/key-features/text-markers/, /key-features/frames/):
|
|
96
|
+
|
|
97
|
+
| Source meta | Mintlify |
|
|
98
|
+
| ------------------------------------------------------------------------------- | -------------------------------------------------------------- |
|
|
99
|
+
| `title="x"` | `title="x"` |
|
|
100
|
+
| file-name comment in the first 4 lines (`// src/a.js`, `# a.py`) | remove the line, use it as the title |
|
|
101
|
+
| `{1,4-5}` / `mark={...}` | `highlight={1,4-5}` |
|
|
102
|
+
| `ins={2}` / `del={3}` | `[!code ++]` / `[!code --]` comment on each line |
|
|
103
|
+
| ` ```diff lang="js" ` with `+`/`-` lines | ` ```js `, strip the prefixes, add `[!code ++]` / `[!code --]` |
|
|
104
|
+
| labelled ranges `{"A":5}` | `highlight={5}`; report the label |
|
|
105
|
+
| `showLineNumbers` | `lines` |
|
|
106
|
+
| `wrap` | `wrap` |
|
|
107
|
+
| `collapse={1-5}` | `expandable` on the block; report the ranges |
|
|
108
|
+
| `"text"`, `/regex/`, `ins="text"`, `del="text"` inline markers | drop; report if meaningful |
|
|
109
|
+
| `frame=...`, `startLineNumber`, `preserveIndent`, `hangingIndent`, `wrap=false` | drop |
|
|
110
|
+
|
|
111
|
+
Frontmatter (https://starlight.astro.build/reference/frontmatter/):
|
|
112
|
+
|
|
113
|
+
- `title` → `title`. `description` is metadata only; Starlight does not render it on the page (`mint migrate --topic conversion`, Frontmatter).
|
|
114
|
+
- `template: splash` → `mode: "custom"`. `hero` → rebuild as a heading, paragraph, image and `<Card>` links from its `title`, `tagline`, `image`, `actions`; report.
|
|
115
|
+
- `tableOfContents: false` → `mode: "wide"`. `pagefind: false` → `searchable: false`.
|
|
116
|
+
- `slug`: path only (see URLs). `sidebar`: navigation only.
|
|
117
|
+
- `editUrl`, `head`, `banner`, `lastUpdated`, `prev`, `next`, `tableOfContents` levels, `draft`, schema-`extend` keys → drop and report.
|
|
118
|
+
|
|
119
|
+
## Assets
|
|
120
|
+
|
|
121
|
+
- `public/*` is served at the site root (`mint migrate --topic conversion`, Images and files).
|
|
122
|
+
- Images under `src/` (often `src/assets/`) are referenced relatively (`../../assets/x.png`), through aliases (`~/assets/x.png`, tsconfig `paths`), or imported (`import img from '...'` then `<Image src={img} />` from `astro:assets`). Move each file into the repo and rewrite every reference to a root-absolute path (`mint migrate --topic conversion`, Images and files).
|
|
123
|
+
- `hero.image.file` / `dark` / `light` and `logo` paths point into `src/`: move those files too.
|
|
124
|
+
|
|
125
|
+
## URLs and redirects
|
|
126
|
+
|
|
127
|
+
- Path = file path under `src/content/docs/` minus extension, lowercased and slugified by Astro; `index` maps to its folder. A `slug` frontmatter replaces the whole path. Take the final list from `dist/` after `npx astro build`, or from the sitemap.
|
|
128
|
+
- Locales: with a `root` locale the default language has no prefix (`/page`), others use `/<folder>/page`; without `root` every language is prefixed. Keep the same folders so paths do not move.
|
|
129
|
+
- Missing translations: Starlight served the default-locale content at `/<locale>/page` (`mint migrate --topic navigation`, Structure rules).
|
|
130
|
+
- `base: '/docs'`: every source URL started with the base (`mint migrate --topic navigation`, Redirects).
|
|
131
|
+
- `trailingSlash: 'always'`: source canonical URLs end in `/` (`mint migrate --topic navigation`, Redirects).
|
|
132
|
+
- Astro `redirects: { '/old': '/new' }` or `{ status, destination }` → one `redirects` entry each. `[...slug]` → `:slug*`; `[slug]` → one entry per page (`mint migrate --topic navigation`, Redirects).
|
|
133
|
+
|
|
134
|
+
## Known gaps
|
|
135
|
+
|
|
136
|
+
Report each: custom `.astro` pages and component overrides, aside icons, Expressive Code text markers and frames, `hero` and splash layouts, sidebar `attrs` and top-level `collapsed`, per-page `banner`/`head`/`prev`/`next`/`editUrl`, translation fallback pages, Pagefind settings, `customCss`, Starlight plugins without a Mintlify feature, and Astro integrations beyond Starlight.
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# VitePress
|
|
2
|
+
|
|
3
|
+
Vue/Vite static site generator. Pages are markdown-it Markdown compiled as Vue components; config is a JS/TS module.
|
|
4
|
+
|
|
5
|
+
## Detect
|
|
6
|
+
|
|
7
|
+
- Repo: a `.vitepress/` directory holding `config.{js,ts,mjs,mts}` (usually `docs/.vitepress/`) and a `vitepress` dependency. The folder containing `.vitepress/` is the project root; `package.json` scripts run `vitepress dev <root>`.
|
|
8
|
+
- Live site: `<meta name="generator" content="VitePress ...">`, `VPContent` / `VPDoc` classes.
|
|
9
|
+
- `.vitepress/` beats everything else. A `.vuepress/` folder or `vuepress` dependency means VuePress (`mint migrate --from vuepress`).
|
|
10
|
+
|
|
11
|
+
## Get the source
|
|
12
|
+
|
|
13
|
+
### From the repo
|
|
14
|
+
|
|
15
|
+
- Pages live in `srcDir` (default: project root), minus `srcExclude` globs. `<srcDir>/public/` holds static files.
|
|
16
|
+
- Read the whole config module plus every file it imports (sidebar/nav helpers, per-locale configs, `.vitepress/theme/index.*`).
|
|
17
|
+
- No built-in versioning. i18n: `locales` keys map to folders (`root` is the unprefixed default, `fr` serves `/fr/`).
|
|
18
|
+
- Dynamic routes: `[param].md` plus `[param].paths.{js,ts}` generate one page per path. Data loaders: `*.data.{js,ts}`.
|
|
19
|
+
- Build: `vitepress build <root>`, output in `.vitepress/dist/` (`mint migrate --topic discovery`, From the repo).
|
|
20
|
+
|
|
21
|
+
### From an export
|
|
22
|
+
|
|
23
|
+
None; the site is built from the repo.
|
|
24
|
+
|
|
25
|
+
### From the live site
|
|
26
|
+
|
|
27
|
+
Follow the "Edit this page" link (`themeConfig.editLink.pattern`) or the footer/nav GitHub link to the repo and fetch raw `.md` from there. Rendered HTML is the fallback.
|
|
28
|
+
|
|
29
|
+
## Config → docs.json
|
|
30
|
+
|
|
31
|
+
| VitePress | docs.json |
|
|
32
|
+
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
33
|
+
| `title` | `name` |
|
|
34
|
+
| `description` | `description` |
|
|
35
|
+
| `themeConfig.logo` (string, `{ src }`, `{ light, dark }`) | `logo` (string or `{ light, dark }`) |
|
|
36
|
+
| `head` `link rel="icon"` | `favicon` |
|
|
37
|
+
| `head` gtag / GTM scripts | `integrations.ga4.measurementId` / `integrations.gtm.tagId` |
|
|
38
|
+
| `head` `meta` tags | `seo.metatags` |
|
|
39
|
+
| `appearance: 'dark'` | `appearance.default: "dark"` |
|
|
40
|
+
| `appearance: false` / `'force-dark'` / `'force-auto'` | `appearance.default` `light` / `dark` / `system` plus `appearance.strict: true` |
|
|
41
|
+
| `lastUpdated: true` | `metadata.timestamp: true` |
|
|
42
|
+
| `markdown.theme` | `styling.codeblocks` |
|
|
43
|
+
| `themeConfig.socialLinks` | `footer.socials` (`twitter` → `x`); `{ svg }` icons: drop and report |
|
|
44
|
+
| `themeConfig.nav`, `themeConfig.sidebar` | `navigation` (see Navigation) |
|
|
45
|
+
| `locales` | `navigation.languages` |
|
|
46
|
+
| `base`, `cleanUrls`, `rewrites` | no field; see URLs and redirects |
|
|
47
|
+
| `themeConfig.footer`, `siteTitle`, `titleTemplate` | drop and report |
|
|
48
|
+
| `themeConfig.editLink`, `search` (local or Algolia), `carbonAds`, `outline`, `aside`, `docFooter`, `*Label` strings, `gradedContainers` | drop and report |
|
|
49
|
+
| `markdown.lineNumbers` | drop; add `lines` to each fence if the user wants it site-wide |
|
|
50
|
+
| `markdown.container` labels, `markdown.math` | drop (Mintlify renders `$` math natively) |
|
|
51
|
+
| `markdown.config` / `preConfig` (`md.use(...)`) | find each plugin's syntax in the content and convert it; report each plugin |
|
|
52
|
+
| `vite`, `vue`, build hooks (`transformHead`, `transformPageData`, `buildEnd`, ...) | drop and report what each one did |
|
|
53
|
+
|
|
54
|
+
## Navigation
|
|
55
|
+
|
|
56
|
+
Full reference: https://vitepress.dev/reference/default-theme-sidebar and https://vitepress.dev/reference/default-theme-nav
|
|
57
|
+
|
|
58
|
+
- `themeConfig.sidebar` array: each top-level `{ text, items }` → a group, in order; nested `items` → nested groups. Each `{ text, link }` → a page.
|
|
59
|
+
- Resolve `link`: prepend the enclosing `base` (a nested `base` overrides its parent's), strip leading `/`, `.md`, `.html`; a trailing `/` means `<dir>/index`.
|
|
60
|
+
- `text` that differs from the page H1 → `sidebarTitle`.
|
|
61
|
+
- A group with its own `link` → that page becomes the group's `root`.
|
|
62
|
+
- `collapsed` on nested groups: `true` → `expanded: false`; `false` or unset → `expanded: true` (VitePress opens them). On top-level groups it has no Mintlify equivalent: report `collapsed: true`.
|
|
63
|
+
- Multi-sidebar object (`{ '/guide/': [...], '/api/': { base, items } }`) → one tab per key; label from the `nav` item that links into that path.
|
|
64
|
+
- `nav`: links into a sidebar key → those tabs; dropdown `items` → that tab's `menu`; external links (`mint migrate --topic navigation`, Structure rules). Drop `activeMatch`, `target`, `rel`, `noIcon`.
|
|
65
|
+
- External `link` items inside the sidebar: report them; do not invent pages.
|
|
66
|
+
- Pages no sidebar lists were reachable only by URL (`mint migrate --topic navigation`, Structure rules).
|
|
67
|
+
|
|
68
|
+
## Content conversion
|
|
69
|
+
|
|
70
|
+
Syntax reference: https://vitepress.dev/guide/markdown. `:::` containers (`mint migrate --topic conversion`, Admonitions); GitHub alerts (`mint migrate --topic conversion`, GitHub alerts); callout titles (`mint migrate --topic conversion`, Components).
|
|
71
|
+
|
|
72
|
+
| VitePress | Mintlify |
|
|
73
|
+
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
|
|
74
|
+
| Container registered in `markdown.container.customContainers` | the callout closest in meaning; report |
|
|
75
|
+
| `::: details Title` (`{open}`) | `<Accordion title="Title">` (`defaultOpen`); untitled → `title="Details"` |
|
|
76
|
+
| `{no-title}` on a container | drop the attribute |
|
|
77
|
+
| `::: raw` | remove the wrapper lines |
|
|
78
|
+
| `::: v-pre`, `<span v-pre>` | unwrap; the `{{ }}` inside was shown literally, so keep it as literal text |
|
|
79
|
+
| ` ```js-vue ` (any `-vue` suffix) | plain language; substitute the `{{ }}` values inside |
|
|
80
|
+
| `::: code-group` with ` ```js [config.js] ` fences | `<CodeGroup>`; each `[label]` becomes the fence title; unlabeled fence → language name |
|
|
81
|
+
| `> [!DANGER]` | `<Danger>` |
|
|
82
|
+
| ` ```js{1,4-6} ` | ` ```js highlight={1,4-6} ` |
|
|
83
|
+
| `:line-numbers` / `:line-numbers=N` / `:no-line-numbers` | `lines` / `lines` (start offset lost: report) / drop |
|
|
84
|
+
| `// [!code ++]`, `// [!code --]` | keep |
|
|
85
|
+
| `// [!code focus]`, `// [!code focus:N]` | remove the comment; add those lines to `focus={...}` |
|
|
86
|
+
| `// [!code highlight]` | remove the comment; add the line to `highlight={...}` |
|
|
87
|
+
| `// [!code error]`, `// [!code warning]` | remove the comment; report |
|
|
88
|
+
| ` ```ts twoslash ` | keep `twoslash` |
|
|
89
|
+
| `<<< @/path/file.ts{2 ts:line-numbers} [Title]`, `<<< file#region` | `mint migrate --topic conversion`, Code imports; `@` is `srcDir` |
|
|
90
|
+
| `<!--@include: ./part.md-->` | `mint migrate --topic conversion`, Reusable content |
|
|
91
|
+
| `<!--@include: ./part.md{3,}-->`, `#region`, `#heading-anchor` | inline the selected lines |
|
|
92
|
+
| `[[toc]]` | delete |
|
|
93
|
+
| `:tada:` emoji shortcodes | the Unicode emoji |
|
|
94
|
+
| `$...$`, `$$...$$` (with `markdown.math`) | keep |
|
|
95
|
+
| ` ```mermaid ` (from a mermaid plugin) | keep |
|
|
96
|
+
|
|
97
|
+
Vue in markdown (https://vitepress.dev/guide/using-vue):
|
|
98
|
+
|
|
99
|
+
- `{{ expr }}`, `$frontmatter.x`, `$params.x` (`mint migrate --topic conversion`, Template tags).
|
|
100
|
+
- `<script setup>`, `<script>`, `<style>` blocks: delete; report styles that mattered.
|
|
101
|
+
- `<Badge type="tip|info|warning|danger" text="x" />` or with children → `<Badge color="...">x</Badge>`, closest color.
|
|
102
|
+
- `<ClientOnly>`: unwrap. `v-if` / `v-for` / `v-pre` on HTML: render the static result.
|
|
103
|
+
- Global components (registered in `.vitepress/theme/index.*` `enhanceApp`) and imported `.vue` files (`mint migrate --topic conversion`, Components). `VPTeamMembers` → `<Card>`s in `<Columns>`.
|
|
104
|
+
|
|
105
|
+
Frontmatter (https://vitepress.dev/reference/frontmatter-config); `title` and `description` (`mint migrate --topic conversion`, Frontmatter):
|
|
106
|
+
|
|
107
|
+
| VitePress | Mintlify |
|
|
108
|
+
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
109
|
+
| `title` (sets only `<title>`; the visible H1 is in the body) | `title` from the body H1 |
|
|
110
|
+
| `layout: home` with `hero` / `features` | `mode: custom`; hero `name`/`text`/`tagline` as heading and paragraph, `actions` as links or `<Card>`s, each feature as `<Card title href>` in `<Columns cols={3}>` |
|
|
111
|
+
| `layout: page` | `mode: frame` |
|
|
112
|
+
| `sidebar: false` | `mode: center` |
|
|
113
|
+
| `aside: false` | `mode: wide` |
|
|
114
|
+
| `head` `og:image` meta | `"og:image"` |
|
|
115
|
+
| `outline`, `prev`, `next`, `editLink`, `lastUpdated`, `footer`, `navbar`, `pageClass`, `titleTemplate`, other `head` | drop and report |
|
|
116
|
+
|
|
117
|
+
## Assets
|
|
118
|
+
|
|
119
|
+
- `<srcDir>/public/` is served at the site root (`mint migrate --topic conversion`, Images and files).
|
|
120
|
+
- Asset references never include `base`; do not add it.
|
|
121
|
+
|
|
122
|
+
## URLs and redirects
|
|
123
|
+
|
|
124
|
+
- `cleanUrls: false` (default): `guide/foo.md` serves `/guide/foo.html` (`mint migrate --topic navigation`, Redirects).
|
|
125
|
+
- `cleanUrls: true`: `/guide/foo`, matching Mintlify paths.
|
|
126
|
+
- `index.md` serves its folder URL (`/guide/`); `index.md` at the root serves `/`.
|
|
127
|
+
- `base: '/docs/'` prefixes every URL. If the Mintlify site keeps that subpath, keep URLs under it; otherwise see `mint migrate --topic navigation`, Redirects.
|
|
128
|
+
- `rewrites` change the URL away from the file path: place each file at its rewritten path so the URL is unchanged. Relative links in rewritten pages are already written against rewritten paths.
|
|
129
|
+
- Locale pages serve under `/<key>/`.
|
|
130
|
+
- Old URL list: `.vitepress/dist/**/*.html` from the build, or the live `sitemap.xml`.
|
|
131
|
+
- VitePress heading slugs (and any custom `markdown.anchor.slugify`) differ from Mintlify's (`mint migrate --topic conversion`, Heading IDs).
|
|
132
|
+
|
|
133
|
+
## Known gaps
|
|
134
|
+
|
|
135
|
+
Report each of these when present:
|
|
136
|
+
|
|
137
|
+
- Vue components, composables (`useData`), and custom theme layouts.
|
|
138
|
+
- Data loaders and dynamic routes (pages must be materialized).
|
|
139
|
+
- Local search and Algolia DocSearch settings.
|
|
140
|
+
- Footer message/copyright, edit links, prev/next overrides, outline levels, carbon ads.
|
|
141
|
+
- Code line-number offsets, `[!code error|warning]` coloring.
|
|
142
|
+
- Collapsible top-level sidebar groups.
|
|
143
|
+
- Custom markdown-it plugins and Vite plugins.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# VuePress
|
|
2
|
+
|
|
3
|
+
Vue-powered static site generator. VuePress 1 and VuePress 2 differ in config shape, sidebar format, containers and code tabs; rows below mark `v1` / `v2` where they differ.
|
|
4
|
+
|
|
5
|
+
## Detect
|
|
6
|
+
|
|
7
|
+
- Repo: a `.vuepress/` directory (usually `docs/.vuepress/`) with `config.{js,ts}` (v1 also `config.yml` / `config.toml`) and a `vuepress` dependency.
|
|
8
|
+
- Major version: the `vuepress` dependency version. v1 configs use `module.exports = { themeConfig: {...} }` and `.vuepress/enhanceApp.js`; v2 configs use `theme: defaultTheme({...})`, a `bundler`, and `.vuepress/client.{js,ts}`.
|
|
9
|
+
- Live site: `<meta name="generator" content="VuePress x.y.z">`; `theme-container` class; v1 adds `theme-default-content`.
|
|
10
|
+
- A `.vitepress/` folder means VitePress (`mint migrate --from vitepress`), even if VuePress appears in old dependencies.
|
|
11
|
+
|
|
12
|
+
## Get the source
|
|
13
|
+
|
|
14
|
+
### From the repo
|
|
15
|
+
|
|
16
|
+
- The source dir is the argument to `vuepress dev <dir>` in `package.json` scripts. Pages are every `.md` under it (v2: filtered by `pagePatterns`).
|
|
17
|
+
- Static files: `.vuepress/public/` (v2: the `public` option can move it).
|
|
18
|
+
- Read the config plus everything it imports, `.vuepress/components/` (v1 auto-registers these globally), `enhanceApp.js` / `client.{js,ts}`, and `styles/`.
|
|
19
|
+
- No built-in versioning. i18n: `locales` keys are folder paths (`'/'` default, `'/zh/'` → `zh/`); the default theme repeats them under `themeConfig.locales` (v1) or `locales` in the theme options (v2) with per-locale nav and sidebar.
|
|
20
|
+
- Build: `vuepress build <dir>`, output in `.vuepress/dist` by default (`mint migrate --topic discovery`, From the repo).
|
|
21
|
+
|
|
22
|
+
### From an export
|
|
23
|
+
|
|
24
|
+
None; the site is built from the repo.
|
|
25
|
+
|
|
26
|
+
### From the live site
|
|
27
|
+
|
|
28
|
+
Follow the edit link or repo link (`repo` / `docsRepo` / `docsDir`) to fetch raw `.md`; rendered HTML is the fallback.
|
|
29
|
+
|
|
30
|
+
## Config → docs.json
|
|
31
|
+
|
|
32
|
+
| VuePress | docs.json |
|
|
33
|
+
| --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
|
|
34
|
+
| `title` | `name` |
|
|
35
|
+
| `description` | `description` |
|
|
36
|
+
| `head` `link rel="icon"` | `favicon` |
|
|
37
|
+
| `head` gtag / GTM scripts, Google Analytics plugin id | `integrations.ga4.measurementId` / `integrations.gtm.tagId` |
|
|
38
|
+
| `head` `meta` tags | `seo.metatags` |
|
|
39
|
+
| `logo` (v2 also `logoDark`) | `logo` (string or `{ light, dark }`) |
|
|
40
|
+
| v2 `colorMode: 'light' \| 'dark' \| 'auto'` | `appearance.default` `light` / `dark` / `system` |
|
|
41
|
+
| v2 `colorModeSwitch: false` | `appearance.strict: true` |
|
|
42
|
+
| `repo` (navbar repository link) | `navbar.links` entry with `type: "github"` |
|
|
43
|
+
| `lastUpdated` truthy (v1 string label; v2 on by default) | `metadata.timestamp: true` if the site showed dates |
|
|
44
|
+
| `nav` (v1) / `navbar` (v2), `sidebar` | `navigation` (see Navigation) |
|
|
45
|
+
| `locales` + theme `locales` | `navigation.languages` |
|
|
46
|
+
| `base`, `permalink` (v1), `permalinkPattern` (v2), `markdown.pageSuffix` (v1) | no field; see URLs and redirects |
|
|
47
|
+
| `editLinks` / `editLink`, `docsRepo`, `docsDir`, `docsBranch`, `editLinkText` | drop and report |
|
|
48
|
+
| `search`, `searchMaxSuggestions`, `algolia` (v1), search plugins (v2) | drop and report |
|
|
49
|
+
| `sidebarDepth`, `displayAllHeaders`, `activeHeaderLinks`, `smoothScroll`, `nextLinks` / `prevLinks`, `contributors`, `externalLinkIcon` | drop |
|
|
50
|
+
| `markdown.lineNumbers` | drop; add `lines` per fence if wanted site-wide |
|
|
51
|
+
| `markdown.extendMarkdown` / `markdown.plugins` (v1), `extendsMarkdown` plugins (v2), `markdown.slugify` / `markdown.anchor` | find each plugin's syntax in content and convert; report each |
|
|
52
|
+
| `plugins` (any) | report each; convert content they add |
|
|
53
|
+
| `styles/palette.styl`, `index.styl` (v1), `styles/` (v2) | `colors.primary` from the accent color; drop the rest and report |
|
|
54
|
+
| `configureWebpack`, `chainWebpack`, bundler options | drop |
|
|
55
|
+
|
|
56
|
+
## Navigation
|
|
57
|
+
|
|
58
|
+
Full reference: v1 https://v1.vuepress.vuejs.org/theme/default-theme-config.html#sidebar, v2 https://ecosystem.vuejs.press/themes/default/config.html#sidebar
|
|
59
|
+
|
|
60
|
+
v1 `themeConfig.sidebar`:
|
|
61
|
+
|
|
62
|
+
- Array of strings → pages in order: strip `.md`; `'/'` or a path ending `/` → that folder's `README`; label is the page title.
|
|
63
|
+
- `[path, 'Text']` → page with `sidebarTitle: "Text"` when it differs from the H1.
|
|
64
|
+
- `{ title, path, collapsable, children }` → group `title`; `path` → group `root`; nested groups → nested groups. `collapsable` (default `true`) has no top-level equivalent: report. Nested groups: the one at `initialOpenGroupIndex` (default `0`) → `expanded: true`, the rest `expanded: false`.
|
|
65
|
+
- Object keyed by path (`'/guide/': [...]`) → one tab per key; children resolve against the key (`''` = the key's `README`, `'one'` = `<key>one`). The `'/'` fallback key is the root sidebar.
|
|
66
|
+
- `'auto'` (global, per key, or `sidebar: auto` frontmatter) shows only that page's headings: those pages have no sidebar nav. Build their placement from `nav` and the folder tree, and report.
|
|
67
|
+
|
|
68
|
+
v2 `sidebar` (theme option):
|
|
69
|
+
|
|
70
|
+
- Default is `'heading'`: headings only, no site-wide sidebar. Navigation then comes only from `navbar` and the folder tree; report this.
|
|
71
|
+
- Array of strings (page file paths, resolved against the enclosing `prefix` unless they start with `/`) and `{ text, link, prefix, collapsible, children }` items. `text` → group; `link` → group `root`; `children` → pages and nested groups. `collapsible: true` on nested groups → set `expanded` to match how the live site opens them.
|
|
72
|
+
- Object keyed by path → one tab per key; a key set to `'heading'` gets no sidebar (report).
|
|
73
|
+
- External `link` items: report; do not invent pages.
|
|
74
|
+
|
|
75
|
+
Navbar: v1 `nav` items `{ text, link }` / `{ text, items }` (nested `items` are sub-groups); v2 `navbar` items `{ text, link }` / `{ text, prefix, children }` / page path strings. Links into a sidebar key → those tabs; dropdowns → tab `menu`; external links (`mint migrate --topic navigation`, Structure rules). Drop `ariaLabel`, `target`, `rel`, `activeMatch`.
|
|
76
|
+
|
|
77
|
+
Pages no sidebar lists were reachable only by URL (`mint migrate --topic navigation`, Structure rules).
|
|
78
|
+
|
|
79
|
+
## Content conversion
|
|
80
|
+
|
|
81
|
+
Syntax reference: v1 https://v1.vuepress.vuejs.org/guide/markdown.html, v2 https://vuejs.press/guide/markdown.html and https://ecosystem.vuejs.press/themes/default/markdown.html. `:::` containers (`mint migrate --topic conversion`, Admonitions); callout titles (`mint migrate --topic conversion`, Components).
|
|
82
|
+
|
|
83
|
+
| VuePress | Mintlify |
|
|
84
|
+
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
85
|
+
| v2 `::: caution` | `<Danger>` |
|
|
86
|
+
| `::: details Title` | `<Accordion title="Title">`; untitled → `title="Details"` |
|
|
87
|
+
| v2 `> [!note]` `[!tip]` `[!important]` `[!warning]` `[!caution]` (when `themePlugins.hint.alert` is on) | `mint migrate --topic conversion`, GitHub alerts |
|
|
88
|
+
| v1 `<code-group>` + `<code-block title="X" active>` | `<CodeGroup>`; each block's `title` becomes the fence title; drop `active` |
|
|
89
|
+
| v2 `::: code-tabs` + `@tab Label` (`@tab:active`) | `<CodeGroup>`; each `@tab` label becomes the fence title |
|
|
90
|
+
| v2 `::: tabs` / `::: tabs#id` + `@tab Label` | `<Tabs>` + `<Tab title="Label">` |
|
|
91
|
+
| v1 `::: slot name` | inline the slot content where it rendered; report |
|
|
92
|
+
| ` ```js{1,4-6} ` | ` ```js highlight={1,4-6} ` |
|
|
93
|
+
| v2 `title="file.ts"` fence meta | fence title `file.ts` |
|
|
94
|
+
| v2 `:line-numbers` / `:no-line-numbers` | `lines` / drop |
|
|
95
|
+
| v2 `:v-pre` / `:no-v-pre` | drop; resolve any `{{ }}` inside a `:no-v-pre` fence |
|
|
96
|
+
| v2 `:collapsed-lines` (prismjs or shiki plugin) | `expandable` |
|
|
97
|
+
| v2 `// [!code ++]`, `// [!code --]` (notation enabled) | keep |
|
|
98
|
+
| v2 `// [!code focus]`, `// [!code highlight]` | remove the comment; add the line to `focus={...}` / `highlight={...}` |
|
|
99
|
+
| v2 `// [!code error]`, `// [!code warning]`, `// [!code word:x]` | remove the comment; report |
|
|
100
|
+
| v1 `<<< @/path/file.js{2}` (`#region`) | `mint migrate --topic conversion`, Code imports; `@` is the directory `vuepress` ran from |
|
|
101
|
+
| v2 `@[code{3-10} js{3}](../foo.js)` | `mint migrate --topic conversion`, Code imports; the `{3}` highlight is relative to the imported lines |
|
|
102
|
+
| v2 `<!-- @include: ./part.md -->` (markdown-include plugin) | `mint migrate --topic conversion`, Reusable content; line ranges and `#region` → inline the selection |
|
|
103
|
+
| `[[toc]]` | delete |
|
|
104
|
+
| `:tada:` emoji shortcodes | the Unicode emoji |
|
|
105
|
+
|
|
106
|
+
Vue in markdown (v1 https://v1.vuepress.vuejs.org/guide/using-vue.html, v2 https://vuejs.press/guide/markdown.html#using-vue-in-markdown):
|
|
107
|
+
|
|
108
|
+
- `{{ expr }}`, `$page`, `$frontmatter`, `$site` (v1) (`mint migrate --topic conversion`, Template tags).
|
|
109
|
+
- `$withBase('/x.png')` → `/x.png`.
|
|
110
|
+
- `<script>`, `<style>` blocks: delete; report styles that mattered.
|
|
111
|
+
- `<Badge text="x" type="..." vertical="...">` → `<Badge color="...">x</Badge>`, closest color (v1 types `tip|warning|error`; v2 `tip|warning|danger|important|info|note`).
|
|
112
|
+
- `<ClientOnly>`: unwrap. v1 `<OutboundLink/>`: delete.
|
|
113
|
+
- Components from `.vuepress/components/` or registered in `enhanceApp.js` / `client.{js,ts}` (`mint migrate --topic conversion`, Components).
|
|
114
|
+
|
|
115
|
+
Frontmatter; `title` and `description` (`mint migrate --topic conversion`, Frontmatter):
|
|
116
|
+
|
|
117
|
+
| VuePress | Mintlify |
|
|
118
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
119
|
+
| `title` (else first heading) | `title` |
|
|
120
|
+
| `home: true` (v1 `heroImage`, `heroText`, `tagline`, `actionText`, `actionLink`, `features`; v2 `actions` list, `heroImageDark`) | `mode: custom`; hero as heading, paragraph and links; each feature as `<Card title>` in `<Columns cols={3}>`; any markdown below the frontmatter follows |
|
|
121
|
+
| `sidebar: false` | `mode: center` |
|
|
122
|
+
| `search: false` (v1) | `searchable: false` |
|
|
123
|
+
| `tags` (v1, search terms) | `keywords` |
|
|
124
|
+
| `meta` / `head` `og:image` | `"og:image"` |
|
|
125
|
+
| `permalink`, `permalinkPattern` | see URLs and redirects; then drop |
|
|
126
|
+
| `layout`, `metaTitle`, `canonicalUrl`, `lang`, `date`, `navbar`, `sidebarDepth`, `prev`, `next`, `editLink`, `lastUpdated`, `contributors`, `pageClass` | drop and report |
|
|
127
|
+
|
|
128
|
+
## Assets
|
|
129
|
+
|
|
130
|
+
- `.vuepress/public/` is served at the site root (`mint migrate --topic conversion`, Images and files).
|
|
131
|
+
- References never include `base`; do not add it.
|
|
132
|
+
|
|
133
|
+
## URLs and redirects
|
|
134
|
+
|
|
135
|
+
- `README.md` and `index.md` serve the folder URL with a trailing slash (`guide/README.md` → `/guide/`) (`mint migrate --topic conversion`, Files).
|
|
136
|
+
- Other pages serve `.html` URLs (`guide/foo.md` → `/guide/foo.html`); v1 `markdown.pageSuffix` and clean-URL plugins can change this (`mint migrate --topic navigation`, Redirects).
|
|
137
|
+
- `permalink` frontmatter or a global `permalink` (v1) / `permalinkPattern` (v2) replaces the file-based URL: place the page at that path, or redirect the permalink to the new path.
|
|
138
|
+
- `base: '/docs/'` prefixes every URL (`mint migrate --topic navigation`, Redirects).
|
|
139
|
+
- Locale pages serve under their locale key (`/zh/...`).
|
|
140
|
+
- Old URL list: `**/*.html` in the build output, or the live `sitemap.xml`.
|
|
141
|
+
- VuePress heading slugs (and custom `markdown.slugify`) differ from Mintlify's (`mint migrate --topic conversion`, Heading IDs).
|
|
142
|
+
|
|
143
|
+
## Known gaps
|
|
144
|
+
|
|
145
|
+
Report each of these when present:
|
|
146
|
+
|
|
147
|
+
- Vue components, custom layouts, and theme slots.
|
|
148
|
+
- Built-in or Algolia search settings; v1 search `tags` beyond `keywords`.
|
|
149
|
+
- `'auto'` / `'heading'` sidebars (no page nav existed).
|
|
150
|
+
- Collapsible top-level sidebar groups.
|
|
151
|
+
- Edit links, last-updated text, contributors, prev/next overrides, sidebar depth.
|
|
152
|
+
- Stylus / SCSS theme customization beyond the primary color.
|
|
153
|
+
- Custom markdown-it plugins, `[!code error|warning|word]` coloring, `$withBase` dynamic paths.
|