Merge branch 'main' into feat/multi-level-sidebar

vuejs · Jul 22, 2022 · 0a1f0b3 · 0a1f0b3
2 parents 308de16 + 7295033
commit 0a1f0b3
Show file tree

Hide file tree

Showing 66 changed files with 826 additions and 554 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -1,6 +1,10 @@
 name: Test
 
-on: [push]
+on:
+  push:
+    branches:
+      - main
+  pull_request:
 
 jobs:
   test:

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -1,5 +1,7 @@
 import { defineConfig } from '../../src/node'
 
+import { version } from '../../package.json'
+
 export default defineConfig({
   lang: 'en-US',
   title: 'VitePress',
@@ -47,9 +49,18 @@ function nav() {
     { text: 'Guide', link: '/guide/what-is-vitepress', activeMatch: '/guide/' },
     { text: 'Configs', link: '/config/introduction', activeMatch: '/config/' },
     {
-      text: 'Changelog',
-      link: 'https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md'
-    }
+      text: version,
+      items: [
+        {
+          text: 'Changelog',
+          link: 'https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md'
+        },
+        {
+          text: 'Contributing',
+          link: 'https://github.com/vuejs/vitepress/blob/main/.github/contributing.md'
+        },
+      ],
+    },
   ]
 }
 

diff --git a/docs/config/app-configs.md b/docs/config/app-configs.md
@@ -12,6 +12,21 @@ export default {
 }
 ```
 
+## appearance
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to enable "Dark Mode" or not. If the option is set to `true`, it adds `.dark` class to the `<html>` tag depending on the users preference.
+
+It also injects inline script that tries to read users settings from local storage by `vitepress-theme-appearance` key and restores users preferred color mode.
+
+```ts
+export default {
+  appearance: true
+}
+```
+
 ## base
 
 - Type: `string`
@@ -27,57 +42,77 @@ export default {
 }
 ```
 
-## lang
+## description
 
 - Type: `string`
-- Default: `en-US`
+- Default: `A VitePress site`
 
-The lang attribute for the site. This will render as a `<html lang="en-US">` tag in the page HTML.
+Description for the site. This will render as a `<meta>` tag in the page HTML.
 
 ```ts
 export default {
-  lang: 'en-US'
+  description: 'A VitePress site'
 }
 ```
 
-## title
+## head
 
-- Type: `string`
-- Default: `VitePress`
+- Type: `HeadConfig[]`
+- Default: `[]`
 
-Title for the site. This will be displayed in the nav bar. Also used as the suffix for all page titles unless `titleTemplate` is defined.
+Additional elements to render in the `<head>` tag in the page HTML. The user-added tags are rendered before the closing `head` tag, after VitePress tags.
 
 ```ts
 export default {
-  title: 'VitePress'
+  head: [
+    ['link', { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }]
+    // would render: <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  ]
 }
 ```
 
-## titleTemplate
+```ts
+type HeadConfig =
+  | [string, Record<string, string>]
+  | [string, Record<string, string>, string]
+```
 
-- Type: `string | boolean`
+## ignoreDeadLinks
 
-The suffix for the title. For example, if you set `title` as `VitePress` and set `titleTemplate` as `My Site`, the html title becomes `VitePress | My Site`.
+- Type: `boolean`
+- Default: `false`
 
-Set `false` to disable the feature. If the option is `undefined`, then the value of `title` option will be used.
+When set to `true`, VitePress will not fail builds due to dead links.
 
 ```ts
 export default {
-  title: 'VitePress',
-  titleTemplate: 'Vite & Vue powered static site generator'
+  ignoreDeadLinks: true
 }
 ```
 
-## description
+## lang
 
 - Type: `string`
-- Default: `A VitePress site`
+- Default: `en-US`
 
-Description for the site. This will render as a `<meta>` tag in the page HTML.
+The lang attribute for the site. This will render as a `<html lang="en-US">` tag in the page HTML.
 
 ```ts
 export default {
-  description: 'A VitePress site'
+  lang: 'en-US'
+}
+```
+
+## lastUpdated
+
+- Type: `boolean`
+- Default: `false`
+
+Use git commit to get the timestamp. This option enables the default theme to display the page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](theme-configs#lastupdatedtext) option.
+
+```ts
+export default {
+  lastUpdated: true
 }
 ```
 
@@ -96,13 +131,18 @@ export default {
 }
 ```
 
-Below shows the the full option you may define within this object.
+Below are all the options that you can have in this object:
 
 ```ts
 interface MarkdownOptions extends MarkdownIt.Options {
-  // Syntax highlight theme for Shiki.
+  // Custom theme for syntax highlighting.
+  // You can use an existing theme.
   // See: https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes
-  theme?: Shiki.Theme | { light: Shiki.Theme, dark: Shiki.Theme }
+  // Or add your own theme.
+  // See: https://github.com/shikijs/shiki/blob/main/docs/themes.md#loading-theme
+  theme?:
+    | Shiki.IThemeRegistration
+    | { light: Shiki.IThemeRegistration; dark: Shiki.IThemeRegistration }
 
   // Enable line numbers in code block.
   lineNumbers?: boolean
@@ -123,39 +163,38 @@ interface MarkdownOptions extends MarkdownIt.Options {
   }
 
   // markdown-it-toc-done-right plugin options
-  // https://github.com/nagaozen/markdown-it-toc-done-right
+  // See: https://github.com/nagaozen/markdown-it-toc-done-right
   toc?: any
 
-  // Configure the Markdown-it instance to fully customize
-  // how it works.
+  // Configure the Markdown-it instance.
   config?: (md: MarkdownIt) => void
 }
 ```
 
-## appearance
-
-- Type: `boolean`
-- Default: `true`
+## title
 
-Whether to enable "Dark Mode" or not. If the option is set to `true`, it adds `.dark` class to the `<html>` tag depending on the users preference.
+- Type: `string`
+- Default: `VitePress`
 
-It also injects inline script that tries to read users settings from local storage by `vitepress-theme-appearance` key and restores users preferred color mode.
+Title for the site. This will be displayed in the nav bar. Also used as the suffix for all page titles unless `titleTemplate` is defined.
 
 ```ts
 export default {
-  appearance: true
+  title: 'VitePress'
 }
 ```
 
-## lastUpdated
+## titleTemplate
 
-- Type: `boolean`
-- Default: `false`
+- Type: `string | boolean`
 
-Use git commit to get the timestamp. This option enables the default theme to display the page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](theme-configs#lastupdatedtext) option.
+The suffix for the title. For example, if you set `title` as `VitePress` and set `titleTemplate` as `My Site`, the html title becomes `VitePress | My Site`.
+
+Set `false` to disable the feature. If the option is `undefined`, then the value of `title` option will be used.
 
 ```ts
 export default {
-  lastUpdated: true
+  title: 'VitePress',
+  titleTemplate: 'Vite & Vue powered static site generator'
 }
 ```
diff --git a/docs/config/frontmatter-configs.md b/docs/config/frontmatter-configs.md
@@ -54,7 +54,7 @@ description: VitePress
 
 ### head
 
-- Type: `Head[]`
+- Type: `HeadConfig[]`
 
 Specify extra head tags to be injected:
 
@@ -71,7 +71,7 @@ head:
 ```
 
 ```ts
-type Head =
+type HeadConfig =
   | [string, Record<string, string>]
   | [string, Record<string, string>, string]
 ```
@@ -98,7 +98,7 @@ Determines the layout of the page.
 
 - `doc` - It applies default documentation styles to the markdown content.
 - `home` - Special layout for "Home Page". You may add extra options such as `hero` and `features` to rappidly create beautiful landing page.
-- `page` - Behave similar to `doc` but it aplies no styles to the content. Useful when you want to create a fully custom page.
+- `page` - Behave similar to `doc` but it applies no styles to the content. Useful when you want to create a fully custom page.
 
 ```yaml
 ---
@@ -110,7 +110,7 @@ layout: doc
 
 - Type: `Hero`
 
-This option only take effect when `layout` is set to `home`.
+This option only takes effect when `layout` is set to `home`.
 
 It defines contents of home hero section.
 
@@ -165,7 +165,7 @@ interface HeroAction {
 
 - Type: `Feature[]`
 
-This option only take effect when `layout` is set to `home`.
+This option only takes effect when `layout` is set to `home`.
 
 It defines items to display in features section.
 
@@ -199,3 +199,16 @@ interface Feature {
   details: string
 }
 ```
+
+## aside
+
+- Type: `boolean`
+- Default: `true`
+
+If you want the right aside component in `doc` layout not to be shown, set this option to `false`.
+
+```yaml
+---
+aside: false
+---
+```
diff --git a/docs/config/theme-configs.md b/docs/config/theme-configs.md
@@ -130,9 +130,24 @@ interface SidebarItem {
 }
 ```
 
+## outlineTitle
+
+- Type: `string`
+- Default: `On this page`
+
+Can be used to customize the title of the right sidebar (on the top of outline links). This is useful when writing documentation in another language.
+
+```js
+export default {
+  themeConfig: {
+    outlineTitle: 'In hac pagina'
+  }
+}
+```
+
 ## socialLinks
 
-- Type: `SocialLink`
+- Type: `SocialLink[]`
 
 You may define this option to show your social account links with icons in nav.
 
@@ -142,7 +157,13 @@ export default {
     socialLinks: [
       { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
       { icon: 'twitter', link: '...' },
-      { icon: 'discord', link: '...' }
+      // You can also add custom icons by passing SVG as string:
+      {
+        icon: {
+          svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Dribbble</title><path d="M12...6.38z"/></svg>'
+        },
+        link: '...'
+      }
     ]
   }
 }
@@ -163,6 +184,7 @@ type SocialLinkIcon =
   | 'slack'
   | 'twitter'
   | 'youtube'
+  | { svg: string }
 ```
 
 ## footer
@@ -247,9 +269,33 @@ export default {
 
 ```ts
 export interface CarbonAds {
-  code: string,
+  code: string
   placement: string
 }
 ```
 
 Learn more in [Theme: Carbon Ads](../guide/theme-carbon-ads)
+
+## docFooter
+
+- Type: `DocFooter`
+
+Can be used to customize text appearing above previous and next links. Helpful if not writing docs in English.
+
+```js
+export default {
+  themeConfig: {
+    docFooter: {
+      prev: 'Pagina prior',
+      next: 'Proxima pagina'
+    }
+  }
+}
+```
+
+```ts
+export interface DocFooter {
+  prev?: string
+  next?: string
+}
+```