Merge branch 'main' into chore/vite-3

docs/guide/deploying.md

@@ -55,6 +55,7 @@ Set up a new project and change these settings using your dashboard:
 
 - **Build Command:** `yarn docs:build`
 - **Output Directory:** `docs/.vitepress/dist`
+- **Node Version:** `14` (or above, by default it usually will be 14 or 16, but on Cloudflare Pages the default is still 12, so you may need to [change that](https://developers.cloudflare.com/pages/platform/build-configuration/))
 
 ::: warning
 Don't enable options like _Auto Minify_ for HTML code. It will remove comments from output which have meaning to Vue. You may see hydration mismatch errors if they get removed.

docs/guide/markdown.md

@@ -388,6 +388,48 @@ You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/co
 
 <!--lint enable strong-marker-->
 
+## Markdown File Inclusion
+
+You can include a markdown file in another markdown file like this:
+
+**Input**
+
+```md
+# Docs
+
+## Basics
+
+<!--@include: ./parts/basics.md-->
+```
+
+**Part file** (`parts/basics.md`)
+
+```md
+Some getting started stuff.
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+**Equivalent code**
+
+```md
+# Docs
+
+## Basics
+
+Some getting started stuff.
+
+### Configuration
+
+Can be created using `.foorc.json`.
+```
+
+::: warning
+Note that this does not throw errors if your file is not present. Hence, when using this feature make sure that the contents are being rendered as expected.
+:::
+
 ## Advanced Configuration
 
 VitePress uses [markdown-it](https://github.com/markdown-it/markdown-it) as the Markdown renderer. A lot of the extensions above are implemented via custom plugins. You can further customize the `markdown-it` instance using the `markdown` option in `.vitepress/config.js`:

docs/guide/theme-introduction.md

@@ -207,3 +207,12 @@ Full list of slots available in the default theme layout:
   - `home-hero-after`
   - `home-features-before`
   - `home-features-after`
+- Always:
+  - `layout-top`
+  - `layout-bottom`
+  - `nav-bar-title-before`
+  - `nav-bar-title-after`
+  - `nav-bar-content-before`
+  - `nav-bar-content-after`
+  - `nav-screen-content-before`
+  - `nav-screen-content-after`

docs/guide/theme-nav.md

@@ -114,7 +114,7 @@ export default {
 
 ### Customize link's "active" state
 
-Nav menu items will be highlighted when the current page is under the matching path. if you would like to customize the path to be mathced, define `activeMatch` property and regex as a string value.
+Nav menu items will be highlighted when the current page is under the matching path. if you would like to customize the path to be matched, define `activeMatch` property and regex as a string value.
 
 ```js
 export default {

docs/guide/theme-team-page.md

@@ -60,9 +60,9 @@ The above will display a team member in card looking element. It should display
 
 <VPTeamMembers size="small" :members="members" />
 
-`<VPTeamMembers>` component comes in 2 different sizes, `small` and `medium`. While it boiles down to your preference, usually `small` size should fit better when used in doc page. Also, you may add more properties to each member such as adding "description" or "sponsor" button. Learn more about it in [`<VPTeamMembers>`](#vpteammembers).
+`<VPTeamMembers>` component comes in 2 different sizes, `small` and `medium`. While it boils down to your preference, usually `small` size should fit better when used in doc page. Also, you may add more properties to each member such as adding "description" or "sponsor" button. Learn more about it in [`<VPTeamMembers>`](#vpteammembers).
 
-Embbeding team members in doc page is good for small size team where having dedicated full team page might be too much, or introducing partial members as a refference to documenation context.
+Embbeding team members in doc page is good for small size team where having dedicated full team page might be too much, or introducing partial members as a reference to documentation context.
 
 If you have large number of members, or simply would like to have more space to show team members, consider [creating a full team page](#create-a-full-team-page).
 
@@ -217,7 +217,7 @@ interface TeamMember {
 
 ## `<VPTeamPage>`
 
-The root component when creating a full team page. It only accepts a single slot. It's will style all passed in team related components.
+The root component when creating a full team page. It only accepts a single slot. It will style all passed in team related components.
 
 ## `<VPTeamPageTitle>`
 

src/client/theme-default/Layout.vue

@@ -29,7 +29,14 @@ provide('close-sidebar', closeSidebar)
     <slot name="layout-top" />
     <VPSkipLink />
     <VPBackdrop class="backdrop" :show="isSidebarOpen" @click="closeSidebar" />
-    <VPNav />
+    <VPNav>
+      <template #nav-bar-title-before><slot name="nav-bar-title-before" /></template>
+      <template #nav-bar-title-after><slot name="nav-bar-title-after" /></template>
+      <template #nav-bar-content-before><slot name="nav-bar-content-before" /></template>
+      <template #nav-bar-content-after><slot name="nav-bar-content-after" /></template>
+      <template #nav-screen-content-before><slot name="nav-screen-content-before" /></template>
+      <template #nav-screen-content-after><slot name="nav-screen-content-after" /></template>
+    </VPNav>
     <VPLocalNav :open="isSidebarOpen" @open-menu="openSidebar" />
     <VPSidebar :open="isSidebarOpen" />
 

src/client/theme-default/components/VPButton.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { normalizeLink } from '../support/utils'
+import { EXTERNAL_URL_RE } from '../../shared'
 
 const props = defineProps<{
   tag?: string
@@ -15,7 +16,7 @@ const classes = computed(() => [
   props.theme ?? 'brand'
 ])
 
-const isExternal = computed(() => props.href && /^[a-z]+:/i.test(props.href))
+const isExternal = computed(() => props.href && EXTERNAL_URL_RE.test(props.href))
 
 const component = computed(() => {
   if (props.tag) {

src/client/theme-default/components/VPLink.vue

@@ -2,13 +2,14 @@
 import { computed } from 'vue'
 import { normalizeLink } from '../support/utils'
 import VPIconExternalLink from './icons/VPIconExternalLink.vue'
+import { EXTERNAL_URL_RE } from '../../shared'
 
 const props = defineProps<{
   href?: string
   noIcon?: boolean
 }>()
 
-const isExternal = computed(() => props.href && /^[a-z]+:/i.test(props.href))
+const isExternal = computed(() => props.href && EXTERNAL_URL_RE.test(props.href))
 </script>
 
 <template>

src/client/theme-default/components/VPNav.vue

@@ -13,8 +13,16 @@ provide('close-screen', closeScreen)
 
 <template>
   <header class="VPNav" :class="{ 'no-sidebar' : !hasSidebar }">
-    <VPNavBar :is-screen-open="isScreenOpen" @toggle-screen="toggleScreen" />
+    <VPNavBar :is-screen-open="isScreenOpen" @toggle-screen="toggleScreen">
-    <VPNavScreen :open="isScreenOpen" />
+      <template #nav-bar-title-before><slot name="nav-bar-title-before" /></template>
+      <template #nav-bar-title-after><slot name="nav-bar-title-after" /></template>
+      <template #nav-bar-content-before><slot name="nav-bar-content-before" /></template>
+      <template #nav-bar-content-after><slot name="nav-bar-content-after" /></template>
+    </VPNavBar>
+    <VPNavScreen :open="isScreenOpen">
+      <template #nav-screen-content-before><slot name="nav-screen-content-before" /></template>
+      <template #nav-screen-content-after><slot name="nav-screen-content-after" /></template>
+    </VPNavScreen>
   </header>
 </template>
 

src/client/theme-default/components/VPNavBar.vue

@@ -23,15 +23,20 @@ const { hasSidebar } = useSidebar()
 <template>
   <div class="VPNavBar" :class="{ 'has-sidebar' : hasSidebar }">
     <div class="container">
-      <VPNavBarTitle />
+      <VPNavBarTitle>
+        <template #nav-bar-title-before><slot name="nav-bar-title-before" /></template>
+        <template #nav-bar-title-after><slot name="nav-bar-title-after" /></template>
+      </VPNavBarTitle>
 
       <div class="content">
+        <slot name="nav-bar-content-before" />
         <VPNavBarSearch class="search" />
         <VPNavBarMenu class="menu" />
         <VPNavBarTranslations class="translations" />
         <VPNavBarAppearance class="appearance" />
         <VPNavBarSocialLinks class="social-links" />
         <VPNavBarExtra class="extra" />
+        <slot name="nav-bar-content-after" />
         <VPNavBarHamburger
           class="hamburger"
           :active="isScreenOpen"

src/client/theme-default/components/VPNavBarTitle.vue

@@ -10,9 +10,11 @@ const { hasSidebar } = useSidebar()
 <template>
   <div class="VPNavBarTitle" :class="{ 'has-sidebar': hasSidebar }">
     <a class="title" :href="site.base">
+      <slot name="nav-bar-title-before" />
       <VPImage class="logo" :image="theme.logo" />
       <template v-if="theme.siteTitle">{{ theme.siteTitle }}</template>
       <template v-else-if="theme.siteTitle === undefined">{{ site.title }}</template>
+      <slot name="nav-bar-title-after" />
     </a>
   </div>
 </template>

src/client/theme-default/components/VPNavScreen.vue

@@ -29,10 +29,12 @@ function unlockBodyScroll() {
   >
     <div v-if="open" class="VPNavScreen" ref="screen">
       <div class="container">
+        <slot name="nav-screen-content-before" />
         <VPNavScreenMenu class="menu" />
         <VPNavScreenTranslations class="translations" />
         <VPNavScreenAppearance class="appearance" />
         <VPNavScreenSocialLinks class="social-links" />
+        <slot name="nav-screen-content-after" />
       </div>
     </div>
   </transition>

src/client/theme-default/support/utils.ts

@@ -1,15 +1,15 @@
 import { ref } from 'vue'
 import { withBase, useData } from 'vitepress'
+import { EXTERNAL_URL_RE } from '../../shared'
 
 export const HASH_RE = /#.*$/
 export const EXT_RE = /(index)?\.(md|html)$/
-export const OUTBOUND_RE = /^[a-z]+:/i
 
 const inBrowser = typeof window !== 'undefined'
 const hashRef = ref(inBrowser ? location.hash : '')
 
 export function isExternal(path: string): boolean {
-  return OUTBOUND_RE.test(path)
+  return EXTERNAL_URL_RE.test(path)
 }
 
 export function throttleAndDebounce(fn: () => void, delay: number): () => void {

src/node/markdown/plugins/image.ts

@@ -7,9 +7,10 @@ export const imagePlugin = (md: MarkdownIt) => {
   const imageRule = md.renderer.rules.image!
   md.renderer.rules.image = (tokens, idx, options, env, self) => {
     const token = tokens[idx]
-    const url = token.attrGet('src')
+    let url = token.attrGet('src')
-    if (url && !EXTERNAL_URL_RE.test(url) && !/^\.?\//.test(url)) {
+    if (url && !EXTERNAL_URL_RE.test(url)) {
-      token.attrSet('src', './' + url)
+      if (!/^\.?\//.test(url)) url = './' + url
+      token.attrSet('src', decodeURIComponent(url))
     }
     return imageRule(tokens, idx, options, env, self)
   }

src/node/markdownToVue.ts

@@ -55,11 +55,15 @@ export async function createMarkdownToVueRenderFn(
 
     // resolve includes
     let includes: string[] = []
-    src = src.replace(includesRE, (_, m1) => {
+    src = src.replace(includesRE, (m, m1) => {
+      try {
         const includePath = path.join(dir, m1)
         const content = fs.readFileSync(includePath, 'utf-8')
         includes.push(slash(includePath))
         return content
+      } catch (error) {
+        return m // silently ignore error if file is not present
+      }
     })
 
     const { content, data: frontmatter } = matter(src)

src/shared/shared.ts

@@ -11,7 +11,7 @@ export type {
   CleanUrlsMode
 } from '../../types/shared'
 
-export const EXTERNAL_URL_RE = /^https?:/i
+export const EXTERNAL_URL_RE = /^[a-z]+:/i
 export const APPEARANCE_KEY = 'vitepress-theme-appearance'
 
 export const inBrowser = typeof window !== 'undefined'