From e21a06ce81db3fdba82b162dfb10dab01989f07f Mon Sep 17 00:00:00 2001 From: Evan You Date: Sun, 5 Mar 2023 00:35:27 +0800 Subject: [PATCH] docs: move default theme content to reference --- docs/.vitepress/config.ts | 65 +++++++++++++++++-- docs/guide/cms.md | 15 +++++ docs/guide/custom-theme.md | 26 ++++---- docs/guide/data-loading.md | 2 + docs/guide/dynamic-routes.md | 0 docs/guide/i18n.md | 2 +- docs/guide/markdown.md | 2 +- docs/guide/migration-from-vitepress-0.md | 6 +- docs/guide/routing.md | 2 +- .../default-theme-badge.md} | 0 .../default-theme-carbon-ads.md} | 0 docs/reference/default-theme-config.md | 10 +-- .../default-theme-edit-link.md} | 0 .../default-theme-footer.md} | 2 +- .../default-theme-home-page.md} | 4 +- .../default-theme-last-updated.md} | 0 .../default-theme-layout.md} | 8 +-- .../default-theme-nav.md} | 0 .../default-theme-prev-next-link.md} | 0 .../default-theme-search.md} | 0 .../default-theme-sidebar.md} | 0 .../default-theme-team-page.md} | 2 +- docs/reference/frontmatter-config.md | 4 +- docs/reference/runtime-api.md | 2 +- 24 files changed, 111 insertions(+), 41 deletions(-) create mode 100644 docs/guide/cms.md delete mode 100644 docs/guide/dynamic-routes.md rename docs/{guide/theme-badge.md => reference/default-theme-badge.md} (100%) rename docs/{guide/theme-carbon-ads.md => reference/default-theme-carbon-ads.md} (100%) rename docs/{guide/theme-edit-link.md => reference/default-theme-edit-link.md} (100%) rename docs/{guide/theme-footer.md => reference/default-theme-footer.md} (89%) rename docs/{guide/theme-home-page.md => reference/default-theme-home-page.md} (97%) rename docs/{guide/theme-last-updated.md => reference/default-theme-last-updated.md} (100%) rename docs/{guide/theme-layout.md => reference/default-theme-layout.md} (75%) rename docs/{guide/theme-nav.md => reference/default-theme-nav.md} (100%) rename docs/{guide/theme-prev-next-link.md => reference/default-theme-prev-next-link.md} (100%) rename docs/{guide/theme-search.md => reference/default-theme-search.md} (100%) rename docs/{guide/theme-sidebar.md => reference/default-theme-sidebar.md} (100%) rename docs/{guide/theme-team-page.md => reference/default-theme-team-page.md} (99%) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 6c4210f0..e7bae559 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -106,7 +106,7 @@ function sidebarGuide() { }, { text: 'Building a Custom Theme', link: '/guide/custom-theme' }, { text: 'Build-Time Data Loading', link: '/guide/data-loading' }, - { text: 'Dynamic Routes', link: '/guide/dynamic-routes' } + { text: 'Connecting to a CMS', link: '/guide/cms' } ] }, // { @@ -136,13 +136,66 @@ function sidebarReference() { text: 'Reference', items: [ { text: 'Site Config', link: '/reference/site-config' }, - { - text: 'Default Theme Config', - link: '/reference/default-theme-config' - }, { text: 'Frontmatter Config', link: '/reference/frontmatter-config' }, { text: 'Runtime API', link: '/reference/runtime-api' }, - { text: 'CLI', link: '/reference/cli' } + { text: 'CLI', link: '/reference/cli' }, + { + text: 'Default Theme', + items: [ + { + text: 'Overview', + link: '/reference/default-theme-config' + }, + { + text: 'Nav', + link: '/reference/default-theme-nav' + }, + { + text: 'Sidebar', + link: '/reference/default-theme-sidebar' + }, + { + text: 'Home Page', + link: '/reference/default-theme-home-page' + }, + { + text: 'Footer', + link: '/reference/default-theme-footer' + }, + { + text: 'Layout', + link: '/reference/default-theme-layout' + }, + { + text: 'Badge', + link: '/reference/default-theme-badge' + }, + { + text: 'Team Page', + link: '/reference/default-theme-team-page' + }, + { + text: 'Prev / Next Links', + link: '/reference/default-theme-prev-next-links' + }, + { + text: 'Edit Link', + link: '/reference/default-theme-edit-link' + }, + { + text: 'Last Updated Timestamp', + link: '/reference/default-theme-last-updated' + }, + { + text: 'Algolia Search', + link: '/reference/default-theme-search' + }, + { + text: 'Carbon Ads', + link: '/reference/default-theme-carbon-ads' + } + ] + } ] } ] diff --git a/docs/guide/cms.md b/docs/guide/cms.md new file mode 100644 index 00000000..ed6a07f7 --- /dev/null +++ b/docs/guide/cms.md @@ -0,0 +1,15 @@ +--- +outline: deep +--- + +# Connecting to a CMS + +## General Workflow + +## Integration Guides + +If you have written a guide on integrating VitePress with a specific CMS, please use the "Edit this page" link below to submit it here! + +### Storyblok + +### Directus diff --git a/docs/guide/custom-theme.md b/docs/guide/custom-theme.md index de8e71c9..2deb48f8 100644 --- a/docs/guide/custom-theme.md +++ b/docs/guide/custom-theme.md @@ -2,18 +2,18 @@ VitePress comes with its default theme providing many features out of the box. Learn more about each feature on its dedicated page listed below. -- [Nav](./theme-nav) -- [Sidebar](./theme-sidebar) -- [Prev Next Link](./theme-prev-next-link) -- [Edit Link](./theme-edit-link) -- [Last Updated](./theme-last-updated) -- [Layout](./theme-layout) -- [Home Page](./theme-home-page) -- [Team Page](./theme-team-page) -- [Badge](./theme-badge) -- [Footer](./theme-footer) -- [Search](./theme-search) -- [Carbon Ads](./theme-carbon-ads) +- [Nav](/reference/default-theme-nav) +- [Sidebar](/reference/default-theme-sidebar) +- [Prev Next Link](/reference/default-theme-prev-next-link) +- [Edit Link](/reference/default-theme-edit-link) +- [Last Updated](/reference/default-theme-last-updated) +- [Layout](/reference/default-theme-layout) +- [Home Page](/reference/default-theme-home-page) +- [Team Page](/reference/default-theme-team-page) +- [Badge](/reference/default-theme-badge) +- [Footer](/reference/default-theme-footer) +- [Search](/reference/default-theme-search) +- [Carbon Ads](/reference/default-theme-carbon-ads) If you don't find the features you're looking for, or you would rather create your own theme, you may customize VitePress to fit your requirements. In the following sections, we'll go through each way of customizing the VitePress theme. @@ -142,7 +142,7 @@ export default DefaultTheme } ``` -See [default theme CSS variables](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) that can be overridden. +See [default theme CSS variables](https://github.com/vuejs/vitepress/blob/main/src/clien/reference/default-theme-default/styles/vars.css) that can be overridden. ### Layout Slots diff --git a/docs/guide/data-loading.md b/docs/guide/data-loading.md index ee9c1c2b..bdc30035 100644 --- a/docs/guide/data-loading.md +++ b/docs/guide/data-loading.md @@ -1,3 +1,5 @@ +# Build-Time Data Loading + ## Basic Usage ```js diff --git a/docs/guide/dynamic-routes.md b/docs/guide/dynamic-routes.md deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/guide/i18n.md b/docs/guide/i18n.md index ccd5b66a..45489516 100644 --- a/docs/guide/i18n.md +++ b/docs/guide/i18n.md @@ -49,7 +49,7 @@ interface LocaleSpecificConfig { } ``` -Refer [`DefaultTheme.Config`](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) interface for details on customizing the placeholder texts of the default theme. Don't override `themeConfig.algolia` or `themeConfig.carbonAds` at locale-level. Refer [Algolia docs](./theme-search#i18n) for using multilingual search. +Refer [`DefaultTheme.Config`](https://github.com/vuejs/vitepress/blob/main/types/default-theme.d.ts) interface for details on customizing the placeholder texts of the default theme. Don't override `themeConfig.algolia` or `themeConfig.carbonAds` at locale-level. Refer [Algolia docs](/reference/default-theme-search#i18n) for using multilingual search. **Pro tip:** Config file can be stored at `docs/.vitepress/config/index.ts` too. It might help you organize stuff by creating a configuration file per locale and then merge and export them from `index.ts`. diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md index abba4466..8b12834f 100644 --- a/docs/guide/markdown.md +++ b/docs/guide/markdown.md @@ -64,7 +64,7 @@ lang: en-US This data will be available to the rest of the page, along with all custom and theming components. -For more details, see [Frontmatter](./frontmatter). +For more details, see [Frontmatter](/reference/frontmatter-config). ## GitHub-Style Tables diff --git a/docs/guide/migration-from-vitepress-0.md b/docs/guide/migration-from-vitepress-0.md index ee21616b..e80d9f4f 100644 --- a/docs/guide/migration-from-vitepress-0.md +++ b/docs/guide/migration-from-vitepress-0.md @@ -12,12 +12,12 @@ If you're coming from VitePress 0.x version, there're several breaking changes d - `children` key is now named `items`. - Top level item may not contain `link` at the moment. We're planning to bring it back. - `repo`, `repoLabel`, `docsDir`, `docsBranch`, `editLinks`, `editLinkText` are removed in favor of more flexible api. - - For adding GitHub link with icon to the nav, use [Social Links](./theme-nav#navigation-links) feature. - - For adding "Edit this page" feature, use [Edit Link](./theme-edit-link) feature. + - For adding GitHub link with icon to the nav, use [Social Links](/reference/default-theme-nav#navigation-links) feature. + - For adding "Edit this page" feature, use [Edit Link](/reference/default-theme-edit-link) feature. - `lastUpdated` option is now split into `config.lastUpdated` and `themeConfig.lastUpdatedText`. - `carbonAds.carbon` is changed to `carbonAds.code`. ## Frontmatter Config -- `home: true` option has changed to `layout: home`. Also, many Homepage related settings have been modified to provide additional features. See [Home Page guide](./theme-home-page) for details. +- `home: true` option has changed to `layout: home`. Also, many Homepage related settings have been modified to provide additional features. See [Home Page guide](/reference/default-theme-home-page) for details. - `footer` option is moved to [`themeConfig.footer`](/reference/default-theme-config#footer). diff --git a/docs/guide/routing.md b/docs/guide/routing.md index 4045d808..6ad29ef2 100644 --- a/docs/guide/routing.md +++ b/docs/guide/routing.md @@ -154,7 +154,7 @@ export default { } ``` -The rewrite paths are compiled using the `path-to-regexp` package - consult [its documentation](](https://github.com/pillarjs/path-to-regexp#parameters)) for more advanced syntax. +The rewrite paths are compiled using the `path-to-regexp` package - consult [its documentation](https://github.com/pillarjs/path-to-regexp#parameters) for more advanced syntax. ### Relative Link Handling in Page diff --git a/docs/guide/theme-badge.md b/docs/reference/default-theme-badge.md similarity index 100% rename from docs/guide/theme-badge.md rename to docs/reference/default-theme-badge.md diff --git a/docs/guide/theme-carbon-ads.md b/docs/reference/default-theme-carbon-ads.md similarity index 100% rename from docs/guide/theme-carbon-ads.md rename to docs/reference/default-theme-carbon-ads.md diff --git a/docs/reference/default-theme-config.md b/docs/reference/default-theme-config.md index 43dfc4b7..9f149b1d 100644 --- a/docs/reference/default-theme-config.md +++ b/docs/reference/default-theme-config.md @@ -64,7 +64,7 @@ export default { - Type: `NavItem` -The configuration for the nav menu item. You may learn more details at [Theme: Nav](../guide/theme-nav#navigation-links). +The configuration for the nav menu item. You may learn more details at [Theme: Nav](./default-theme-nav#navigation-links). ```js export default { @@ -111,7 +111,7 @@ interface NavItemWithChildren { - Type: `Sidebar` -The configuration for the sidebar menu item. You may learn more details at [Theme: Sidebar](../guide/theme-sidebar). +The configuration for the sidebar menu item. You may learn more details at [Theme: Sidebar](./default-theme-sidebar). ```js export default { @@ -271,7 +271,7 @@ export interface Footer { - Type: `EditLink` -Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. See [Theme: Edit Link](../guide/theme-edit-link) for more details. +Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. See [Theme: Edit Link](./default-theme-edit-link) for more details. ```js export default { @@ -310,7 +310,7 @@ export default { - Type: `AlgoliaSearch` -An option to support searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Learn more in [Theme: Search](../guide/theme-search) +An option to support searching your docs site using [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Learn more in [Theme: Search](./default-theme-search) ```ts export interface AlgoliaSearchOptions extends DocSearchProps { @@ -344,7 +344,7 @@ export interface CarbonAdsOptions { } ``` -Learn more in [Theme: Carbon Ads](../guide/theme-carbon-ads) +Learn more in [Theme: Carbon Ads](./default-theme-carbon-ads) ## docFooter diff --git a/docs/guide/theme-edit-link.md b/docs/reference/default-theme-edit-link.md similarity index 100% rename from docs/guide/theme-edit-link.md rename to docs/reference/default-theme-edit-link.md diff --git a/docs/guide/theme-footer.md b/docs/reference/default-theme-footer.md similarity index 89% rename from docs/guide/theme-footer.md rename to docs/reference/default-theme-footer.md index d59d0e1d..6b62dbf6 100644 --- a/docs/guide/theme-footer.md +++ b/docs/reference/default-theme-footer.md @@ -36,4 +36,4 @@ export default { } ``` -Note that footer will not be displayed when the [SideBar](./theme-sidebar) is visible. +Note that footer will not be displayed when the [SideBar](/reference/default-theme-sidebar) is visible. diff --git a/docs/guide/theme-home-page.md b/docs/reference/default-theme-home-page.md similarity index 97% rename from docs/guide/theme-home-page.md rename to docs/reference/default-theme-home-page.md index 498af6e1..93de38e1 100644 --- a/docs/guide/theme-home-page.md +++ b/docs/reference/default-theme-home-page.md @@ -1,6 +1,6 @@ # Home Page -VitePress default theme provides a homepage layout, which you can also see used on [the homepage of this site](../). You may use it on any of your pages by specifying `layout: home` in the [frontmatter](./frontmatter). +VitePress default theme provides a homepage layout, which you can also see used on [the homepage of this site](../). You may use it on any of your pages by specifying `layout: home` in the [frontmatter](./frontmatter-config). ```yaml --- @@ -131,7 +131,7 @@ interface Feature { // Link when clicked on feature component. The link can // be both internal or external. // - // e.g. `guide/theme-home-page` or `htttps://example.com` + // e.g. `guid/reference/default-theme-home-page` or `htttps://example.com` link?: string // Link text to be shown inside feature component. Best diff --git a/docs/guide/theme-last-updated.md b/docs/reference/default-theme-last-updated.md similarity index 100% rename from docs/guide/theme-last-updated.md rename to docs/reference/default-theme-last-updated.md diff --git a/docs/guide/theme-layout.md b/docs/reference/default-theme-layout.md similarity index 75% rename from docs/guide/theme-layout.md rename to docs/reference/default-theme-layout.md index 09b5cff8..40997cc1 100644 --- a/docs/guide/theme-layout.md +++ b/docs/reference/default-theme-layout.md @@ -1,6 +1,6 @@ # Layout -You may choose the page layout by setting `layout` option to the page [frontmatter](./frontmatter). There are 3 layout options, `doc`, `page`, and `home`. If nothing is specified, then the page is treated as `doc` page. +You may choose the page layout by setting `layout` option to the page [frontmatter](./frontmatter-config). There are 3 layout options, `doc`, `page`, and `home`. If nothing is specified, then the page is treated as `doc` page. ```yaml --- @@ -19,11 +19,11 @@ It also provides documentation specific features listed below. These features ar - Edit Link - Prev Next Link - Outline -- [Carbon Ads](./theme-carbon-ads) +- [Carbon Ads](./default-theme-carbon-ads) ## Page Layout -Option `page` is treated as "blank page". The Markdown will still be parsed, and all of the [Markdown Extensions](./markdown) work as same as `doc` layout, but it wouldn't get any default stylings. +Option `page` is treated as "blank page". The Markdown will still be parsed, and all of the [Markdown Extensions](/guide/markdown) work as same as `doc` layout, but it wouldn't get any default stylings. The page layout will let you style everything by you without VitePress theme affecting the markup. This is useful when you want to create your own custom page. @@ -31,7 +31,7 @@ Note that even in this layout, sidebar will still show up if the page has a matc ## Home Layout -Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Theme: Home Page](./theme-home-page) for more details. +Option `home` will generate templated "Homepage". In this layout, you can set extra options such as `hero` and `features` to customize the content further. Please visit [Theme: Home Page](/reference/default-theme-home-page) for more details. ## No Layout diff --git a/docs/guide/theme-nav.md b/docs/reference/default-theme-nav.md similarity index 100% rename from docs/guide/theme-nav.md rename to docs/reference/default-theme-nav.md diff --git a/docs/guide/theme-prev-next-link.md b/docs/reference/default-theme-prev-next-link.md similarity index 100% rename from docs/guide/theme-prev-next-link.md rename to docs/reference/default-theme-prev-next-link.md diff --git a/docs/guide/theme-search.md b/docs/reference/default-theme-search.md similarity index 100% rename from docs/guide/theme-search.md rename to docs/reference/default-theme-search.md diff --git a/docs/guide/theme-sidebar.md b/docs/reference/default-theme-sidebar.md similarity index 100% rename from docs/guide/theme-sidebar.md rename to docs/reference/default-theme-sidebar.md diff --git a/docs/guide/theme-team-page.md b/docs/reference/default-theme-team-page.md similarity index 99% rename from docs/guide/theme-team-page.md rename to docs/reference/default-theme-team-page.md index b13bff51..576a56c5 100644 --- a/docs/guide/theme-team-page.md +++ b/docs/reference/default-theme-team-page.md @@ -68,7 +68,7 @@ If you have large number of members, or simply would like to have more space to ## Create a full Team Page -Instead of adding team members to doc page, you may also create a full Team Page, similar to how you can create a custom [Home Page](./theme-home-page). +Instead of adding team members to doc page, you may also create a full Team Page, similar to how you can create a custom [Home Page](/reference/default-theme-home-page). To create a team page, first, create a new md file. The file name doesn't matter, but here lets call it `team.md`. In this file, set frontmatter option `layout: page`, and then you may compose your page structure using `TeamPage` components. diff --git a/docs/reference/frontmatter-config.md b/docs/reference/frontmatter-config.md index 96fdfa8f..52df37db 100644 --- a/docs/reference/frontmatter-config.md +++ b/docs/reference/frontmatter-config.md @@ -81,7 +81,7 @@ type HeadConfig = - Type: `boolean` - Default: `true` -Whether to display [Last Updated](../guide/theme-last-updated) text in the current page. +Whether to display [Last Updated](/reference/default-theme-last-updated) text in the current page. ```yaml --- @@ -169,7 +169,7 @@ This option only takes effect when `layout` is set to `home`. It defines items to display in features section. -You may learn more about it in [Theme: Home Page](../guide/theme-home-page). +You may learn more about it in [Theme: Home Page](/reference/default-theme-home-page). ## aside diff --git a/docs/reference/runtime-api.md b/docs/reference/runtime-api.md index e9dfae91..4f3d9108 100644 --- a/docs/reference/runtime-api.md +++ b/docs/reference/runtime-api.md @@ -1,4 +1,4 @@ -# Runtime API Reference +# Runtime API VitePress offers several built-in APIs to let you access app data. VitePress also comes with a few built-in components that can be used globally.