From 9ca6ba76ef58ec07536b42411facc77244214699 Mon Sep 17 00:00:00 2001 From: Evan You Date: Thu, 2 Mar 2023 15:39:06 +0800 Subject: [PATCH 01/32] docs: update home page --- docs/index.md | 28 +++++++++++++------ docs/public/vite.svg | 15 ++++++++++ docs/public/vue.svg | 4 +++ .../theme-default/components/VPFeature.vue | 3 +- 4 files changed, 40 insertions(+), 10 deletions(-) create mode 100644 docs/public/vite.svg create mode 100644 docs/public/vue.svg diff --git a/docs/index.md b/docs/index.md index e3e88564947..f3344fe3f4e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,7 +7,7 @@ titleTemplate: Vite & Vue Powered Static Site Generator hero: name: VitePress text: Vite & Vue Powered Static Site Generator - tagline: Simple, powerful, and performant. Meet the modern SSG framework you've always wanted. + tagline: Simple, powerful, and fast. Meet the modern SSG framework you've always wanted. actions: - theme: brand text: Get Started @@ -17,12 +17,22 @@ hero: link: https://github.com/vuejs/vitepress features: - - title: "Vite: The DX that can't be beat" - details: Feel the speed of Vite. Instant server start and lightning fast HMR that stays fast regardless of the app size. - - title: Designed to be simplicity first - details: With Markdown-centered content, it's built to help you focus on writing and deployed with minimum configuration. - - title: Power of Vue meets Markdown - details: Enhance your content with all the features of Vue in Markdown, while being able to customize your site with Vue. - - title: Fully static yet still dynamic - details: Go wild with true SSG + SPA architecture. Static on page load, but engage users with 100% interactivity from there. + - icon: 📝 + title: Focus on Your Content + details: Effortlessly create beautiful documentation sites with the feature-rich default theme. + - icon: + src: vite.svg + width: 10 + height: 10 + title: Enjoy the Vite DX + details: Instant server start, lightning fast hot updates, and leverage Vite ecosystem plugins. + - icon: + src: vue.svg + width: 10 + height: 10 + title: Customize with Vue + details: Use Vue syntax and components directly in markdown, or build custom themes with Vue components. + - icon: 🚀 + title: Ship Fast Sites + details: Fast initial load with static HTML, fast post-load navigation with client-side routing. --- diff --git a/docs/public/vite.svg b/docs/public/vite.svg new file mode 100644 index 00000000000..de4aeddc12b --- /dev/null +++ b/docs/public/vite.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + diff --git a/docs/public/vue.svg b/docs/public/vue.svg new file mode 100644 index 00000000000..71c1cfb9afa --- /dev/null +++ b/docs/public/vue.svg @@ -0,0 +1,4 @@ + + + + diff --git a/src/client/theme-default/components/VPFeature.vue b/src/client/theme-default/components/VPFeature.vue index 89b5b3ee233..b9bd6af6d20 100644 --- a/src/client/theme-default/components/VPFeature.vue +++ b/src/client/theme-default/components/VPFeature.vue @@ -59,7 +59,8 @@ defineProps<{ } .VPFeature:deep(.VPImage) { - width: fit-content; + width: 48px; + height: 48px; margin-bottom: 20px; } From 1e47cafabdacd4ad5ea9ab2e9cb35fb960e64d0e Mon Sep 17 00:00:00 2001 From: Evan You Date: Thu, 2 Mar 2023 16:36:20 +0800 Subject: [PATCH 02/32] docs: restructure --- docs/.vitepress/config.ts | 74 +++++----- docs/config/introduction.md | 76 ----------- docs/guide/asset-handling.md | 2 +- docs/guide/configuration.md | 27 ---- ...customization-intro.md => custom-theme.md} | 0 docs/guide/{deploying.md => deploy.md} | 4 +- docs/guide/dynamic-routes.md | 0 docs/guide/extending-default-theme.md | 0 docs/guide/frontmatter.md | 2 +- docs/guide/getting-started.md | 34 ++++- docs/guide/i18n.md | 2 +- docs/guide/markdown.md | 6 +- docs/guide/migration-from-vitepress-0.md | 2 +- docs/guide/routing.md | 6 +- docs/guide/theme-nav.md | 6 +- docs/guide/theme-sidebar.md | 2 +- docs/guide/theme-team-page.md | 2 +- docs/guide/using-vue.md | 8 +- docs/index.md | 2 +- .../default-theme-config.md} | 0 .../frontmatter-config.md | 8 +- .../index.md => reference/runtime-api.md} | 4 +- .../site-config.md} | 126 ++++++++++++++---- package.json | 5 +- 24 files changed, 196 insertions(+), 202 deletions(-) delete mode 100644 docs/config/introduction.md delete mode 100644 docs/guide/configuration.md rename docs/guide/{customization-intro.md => custom-theme.md} (100%) rename docs/guide/{deploying.md => deploy.md} (98%) create mode 100644 docs/guide/dynamic-routes.md create mode 100644 docs/guide/extending-default-theme.md rename docs/{config/theme-config.md => reference/default-theme-config.md} (100%) rename docs/{config => reference}/frontmatter-config.md (86%) rename docs/{api/index.md => reference/runtime-api.md} (92%) rename docs/{config/app-config.md => reference/site-config.md} (80%) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index c53710e0966..ff598e8e91e 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -25,8 +25,7 @@ export default defineConfig({ sidebar: { '/guide/': sidebarGuide(), - '/config/': sidebarConfig(), - '/api/': sidebarGuide() + '/reference/': sidebarReference() }, editLink: { @@ -60,14 +59,9 @@ function nav() { return [ { text: 'Guide', link: '/guide/what-is-vitepress', activeMatch: '/guide/' }, { - text: 'Config Reference', - link: '/config/introduction', - activeMatch: '/config/' - }, - { - text: 'Runtime API', - link: '/api/', - activeMatch: '/api/' + text: 'Reference', + link: '/reference/site-config', + activeMatch: '/reference/' }, { text: pkg.version, @@ -93,9 +87,8 @@ function sidebarGuide() { items: [ { text: 'What is VitePress?', link: '/guide/what-is-vitepress' }, { text: 'Getting Started', link: '/guide/getting-started' }, - { text: 'Configuration', link: '/guide/configuration' }, { text: 'Routing', link: '/guide/routing' }, - { text: 'Deploying', link: '/guide/deploying' } + { text: 'Deploy', link: '/guide/deploy' } ] }, { @@ -113,45 +106,48 @@ function sidebarGuide() { text: 'Customization', collapsed: false, items: [ - // { text: 'Default Theme', link: '/guide/default-theme' }, - // { - // text: 'Extending the Default Theme', - // link: '/guide/customization-extending-default-theme' - // }, - { text: 'Building a Custom Theme', link: '/guide/customization-intro' }, { - text: 'Runtime API', - link: '/api/' + text: 'Extending the Default Theme', + link: '/guide/extending-default-theme' }, - { text: 'Build-Time Data Loading', link: '/guide/data-loading' } + { 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: 'Migrations', + // collapsed: false, + // items: [ + // { + // text: 'Migration from VuePress', + // link: '/guide/migration-from-vuepress' + // }, + // { + // text: 'Migration from VitePress 0.x', + // link: '/guide/migration-from-vitepress-0' + // } + // ] + // }, { - text: 'Migrations', - collapsed: false, - items: [ - { - text: 'Migration from VuePress', - link: '/guide/migration-from-vuepress' - }, - { - text: 'Migration from VitePress 0.x', - link: '/guide/migration-from-vitepress-0' - } - ] + text: 'Config & API Reference', + link: '/reference/site-config' } ] } -function sidebarConfig() { +function sidebarReference() { return [ { - text: 'Config Reference', + text: 'Reference', items: [ - { text: 'Introduction', link: '/config/introduction' }, - { text: 'App Config', link: '/config/app-config' }, - { text: 'Default Theme Config', link: '/config/theme-config' }, - { text: 'Frontmatter Config', link: '/config/frontmatter-config' } + { 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' } ] } ] diff --git a/docs/config/introduction.md b/docs/config/introduction.md deleted file mode 100644 index f70829d121b..00000000000 --- a/docs/config/introduction.md +++ /dev/null @@ -1,76 +0,0 @@ -# Introduction - -Place your configuration file at `.vitepress/config.js`. This is where all VitePress-specific files will be placed. - -``` -. -├─ docs -│ ├─ .vitepress -│ │ └─ config.js -│ └─ index.md -└─ package.json -``` - -::: tip -You can also use any of `.ts`, `.cjs`, `.mjs`, `.cts`, `.mts` as the config file extension. -::: - -VitePress comes with 2 types of configuration. One is the [App Config](./app-config) which configures the site's fundamental features such as setting title of the site, or customize how markdown parser works. Second is the [Theme Config](./theme-config) which configures the theme of the site, for example, adding a sidebar, or add features such as "Edit this page on GitHub" link. - -There's also another configuration you may do in [Frontmatter](./frontmatter-config). Frontmatter config can override global config defined in App Config or Theme Config for that specific page. However, there're several options that are only available at frontmatter as well. - -Please refer to the corresponding config page to learn more. - -## Config Intellisense - -Since VitePress ships with TypeScript typings, you can leverage your IDE's intellisense with jsdoc type hints: - -```js -/** - * @type {import('vitepress').UserConfig} - */ -const config = { - // ... -} - -export default config -``` - -Alternatively, you can use the `defineConfig` helper at which should provide intellisense without the need for jsdoc annotations: - -```js -import { defineConfig } from 'vitepress' - -export default defineConfig({ - // ... -}) -``` - -VitePress also directly supports TS config files. You can use `.vitepress/config.ts` with the `defineConfig` helper as well. - -## Typed Theme Config - -By default, `defineConfig` helper leverages the theme config type from default theme: - -```ts -import { defineConfig } from 'vitepress' - -export default defineConfig({ - themeConfig: { - // Type is `DefaultTheme.Config` - } -}) -``` - -If you use a custom theme and want type checks for the theme config, you'll need to use `defineConfigWithTheme` instead, and pass the config type for your custom theme via a generic argument: - -```ts -import { defineConfigWithTheme } from 'vitepress' -import { ThemeConfig } from 'your-theme' - -export default defineConfigWithTheme({ - themeConfig: { - // Type is `ThemeConfig` - } -}) -``` diff --git a/docs/guide/asset-handling.md b/docs/guide/asset-handling.md index 132b6b6e95c..8ec2ac24284 100644 --- a/docs/guide/asset-handling.md +++ b/docs/guide/asset-handling.md @@ -45,7 +45,7 @@ However, if you are authoring a theme component that links to assets dynamically ``` -In this case it is recommended to wrap the path with the [`withBase` helper](/api/#withbase) provided by VitePress: +In this case it is recommended to wrap the path with the [`withBase` helper](/reference/runtime-api#withbase) provided by VitePress: ```vue