vitepress 0.22.4 → 1.0.0-alpha.1

package/README.md

@@ -1,4 +1,4 @@
-# (WIP) VitePress 📝💨
+# VitePress (alpha) 📝💨
 
 [![Test](https://github.com/vuejs/vitepress/workflows/Test/badge.svg)](https://github.com/vuejs/vitepress/actions)
 [![npm](https://img.shields.io/npm/v/vitepress)](https://www.npmjs.com/package/vitepress)
@@ -7,6 +7,8 @@
 
 VitePress is [VuePress](https://vuepress.vuejs.org)' spiritual successor, built on top of [vite](https://github.com/vitejs/vite).
 
+Currently, it's in the `alpha` stage. It is already suitable for out-of-the-box documentation use, but the config and theming API may still change between minor releases.
+
 ## Documentation
 
 To check out docs, visit [vitepress.vuejs.org](https://vitepress.vuejs.org).

package/bin/vitepress.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-require('../dist/node/cli')
+import('../dist/node/cli.js')

package/client.d.ts

@@ -1,4 +1,3 @@
-// re-export vite client types
-// with strict installers like pnpm, user won't be able to reference vite/client
-// in project root
+// re-export vite client types. with strict installers like pnpm, user won't
+// be able to reference vite/client in project root.
 /// <reference types="vite/client" />

package/dist/client/app/components/ClientOnly.js

@@ -1,4 +1,4 @@
-import { ref, onMounted, defineComponent } from 'vue';
+import { defineComponent, ref, onMounted } from 'vue';
 export const ClientOnly = defineComponent({
     setup(_, { slots }) {
         const show = ref(false);

package/dist/client/app/composables/head.js

@@ -1,4 +1,5 @@
 import { watchEffect } from 'vue';
+import { createTitle } from '../../shared';
 export function useUpdateHead(route, siteDataByRouteRef) {
     let managedHeadTags = [];
     let isFirstUpdate = true;
@@ -50,11 +51,10 @@ export function useUpdateHead(route, siteDataByRouteRef) {
     watchEffect(() => {
         const pageData = route.data;
         const siteData = siteDataByRouteRef.value;
-        const pageTitle = pageData && pageData.title;
         const pageDescription = pageData && pageData.description;
         const frontmatterHead = pageData && pageData.frontmatter.head;
         // update title and description
-        document.title = (pageTitle ? pageTitle + ` | ` : ``) + siteData.title;
+        document.title = createTitle(siteData, pageData);
         document
             .querySelector(`meta[name=description]`)
             .setAttribute('content', pageDescription || siteData.description);

package/dist/client/app/data.js

@@ -1,6 +1,6 @@
 import { shallowRef, readonly, computed, inject } from 'vue';
 import serializedSiteData from '@siteData';
-import { resolveSiteDataByRoute } from '../shared';
+import { resolveSiteDataByRoute, createTitle } from '../shared';
 import { withBase } from './utils';
 export const dataSymbol = Symbol();
 export const siteDataRef = shallowRef(parse(serializedSiteData));
@@ -29,9 +29,7 @@ export function initData(route) {
             return withBase(path || '/');
         }),
         title: computed(() => {
-            return route.data.title
-                ? route.data.title + ' | ' + site.value.title
-                : site.value.title;
+            return createTitle(site.value, route.data);
         }),
         description: computed(() => {
             return route.data.description || site.value.description;

package/dist/client/app/index.js

@@ -1,9 +1,9 @@
 import { createApp as createClientApp, createSSRApp, defineAsyncComponent, h, onMounted, watch } from 'vue';
+import Theme from '/@theme/index';
 import { inBrowser, pathToFile } from './utils';
 import { RouterSymbol, createRouter } from './router';
 import { siteDataRef, useData } from './data';
 import { useUpdateHead } from './composables/head';
-import Theme from '/@theme/index';
 import { usePrefetch } from './composables/preFetch';
 import { dataSymbol, initData } from './data';
 import { Content } from './components/Content';
@@ -73,14 +73,10 @@ function newRouter() {
         if (isInitialPageLoad || initialPath === pageFilePath) {
             pageFilePath = pageFilePath.replace(/\.js$/, '.lean.js');
         }
-        // in browser: native dynamic import
         if (inBrowser) {
             isInitialPageLoad = false;
-            return import(/*@vite-ignore*/ pageFilePath);
         }
-        // SSR: sync require
-        // @ts-ignore
-        return require(pageFilePath);
+        return import(/*@vite-ignore*/ pageFilePath);
     }, NotFound);
 }
 function handleHMR(router) {

package/dist/client/app/router.js

@@ -1,5 +1,5 @@
 import { reactive, inject, markRaw, nextTick, readonly } from 'vue';
-import { inBrowser } from './utils';
+import { inBrowser, withBase } from './utils';
 import { siteDataRef } from './data';
 export const RouterSymbol = Symbol();
 // we are just using URL to parse the pathname and hash - the base doesn't
@@ -51,7 +51,7 @@ export function createRouter(loadPageModule, fallbackComponent) {
                 if (!comp) {
                     throw new Error(`Invalid route component: ${comp}`);
                 }
-                route.path = pendingPath;
+                route.path = inBrowser ? pendingPath : withBase(pendingPath);
                 route.component = markRaw(comp);
                 route.data = import.meta.env.PROD
                     ? markRaw(JSON.parse(__pageData))
@@ -94,7 +94,7 @@ export function createRouter(loadPageModule, fallbackComponent) {
             }
             if (latestPendingPath === pendingPath) {
                 latestPendingPath = null;
-                route.path = pendingPath;
+                route.path = inBrowser ? pendingPath : withBase(pendingPath);
                 route.component = fallbackComponent ? markRaw(fallbackComponent) : null;
                 route.data = notFoundPageData;
             }

package/dist/client/index.d.ts

@@ -1,129 +1,123 @@
-import { AllowedComponentProps } from 'vue';
-import { App } from 'vue';
-import { Component } from 'vue';
-import { ComponentCustomProps } from 'vue';
-import { ComponentOptions } from 'vue';
-import { ComponentOptionsMixin } from 'vue';
-import { DefineComponent } from 'vue';
-import { EmitsOptions } from 'vue';
-import { ExtractPropTypes } from 'vue';
-import { Ref } from 'vue';
-import { RendererElement } from 'vue';
-import { RendererNode } from 'vue';
-import { VNode } from 'vue';
-import { VNodeProps } from 'vue';
-
-export declare const Content: DefineComponent<    {}, () => VNode<RendererNode, RendererElement, {
-[key: string]: any;
-}>, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, EmitsOptions, string, VNodeProps & AllowedComponentProps & ComponentCustomProps, Readonly<ExtractPropTypes<    {}>>, {}>;
-
-export declare const Debug: ComponentOptions<{}, any, any, any, any, any, any, any>;
-
-export declare interface EnhanceAppContext {
-    app: App;
-    router: Router;
-    siteData: Ref<SiteData>;
-}
-
-export declare type HeadConfig =
-| [string, Record<string, string>]
-| [string, Record<string, string>, string]
-
-export declare interface Header {
-    level: number
-    title: string
-    slug: string
-}
-
-export declare const inBrowser: boolean;
-
-export declare interface LocaleConfig {
-    lang: string
-    title?: string
-    description?: string
-    head?: HeadConfig[]
-    label?: string
-    selectText?: string
-}
-
-export declare interface PageData {
-    relativePath: string
-    title: string
-    description: string
-    headers: Header[]
-    frontmatter: Record<string, any>
-    lastUpdated?: number
-}
-
-export declare interface Route {
-    path: string;
-    data: PageData;
-    component: Component | null;
-}
-
-export declare interface Router {
-    route: Route;
-    go: (href?: string) => Promise<void>;
-}
-
-export declare interface SiteData<ThemeConfig = any> {
-    base: string
-    /**
-     * Language of the site as it should be set on the `html` element.
-     * @example `en-US`, `zh-CN`
-     */
-    lang: string
-    title: string
-    description: string
-    head: HeadConfig[]
-    themeConfig: ThemeConfig
-    scrollOffset: number | string
-    locales: Record<string, LocaleConfig>
-    /**
-     * Available locales for the site when it has defined `locales` in its
-     * `themeConfig`. This object is otherwise empty. Keys are paths like `/` or
-     * `/zh/`.
-     */
-    langs: Record<
-    string,
-        {
-        /**
-         * Lang attribute as set on the `<html>` element.
-         * @example `en-US`, `zh-CN`
-         */
-        lang: string
-        /**
-         * Label to display in the language menu.
-         * @example `English`, `简体中文`
-         */
-        label: string
-    }
-    >
-}
-
-export declare interface Theme {
-    Layout: Component;
-    NotFound?: Component;
-    enhanceApp?: (ctx: EnhanceAppContext) => void;
-}
-
-export declare function useData<T = any>(): VitePressData<T>;
-
-export declare function useRoute(): Route;
-
-export declare function useRouter(): Router;
-
-export declare interface VitePressData<T = any> {
-    site: Ref<SiteData<T>>;
-    page: Ref<PageData>;
-    theme: Ref<T>;
-    frontmatter: Ref<PageData['frontmatter']>;
-    title: Ref<string>;
-    description: Ref<string>;
-    lang: Ref<string>;
-    localePath: Ref<string>;
-}
-
-export declare function withBase(path: string): string;
-
-export { }
+import * as vue from 'vue';
+import { Component, Ref, App } from 'vue';
+
+// types shared between server and client
+
+
+interface PageData {
+  relativePath: string
+  title: string
+  titleTemplate?: string | boolean
+  description: string
+  headers: Header[]
+  frontmatter: Record<string, any>
+  lastUpdated?: number
+}
+
+interface Header {
+  level: number
+  title: string
+  slug: string
+}
+
+interface SiteData<ThemeConfig = any> {
+  base: string
+
+  /**
+   * Language of the site as it should be set on the `html` element.
+   *
+   * @example `en-US`, `zh-CN`
+   */
+  lang: string
+
+  title: string
+  titleTemplate?: string | boolean
+  description: string
+  head: HeadConfig[]
+  appearance: boolean
+  themeConfig: ThemeConfig
+  scrollOffset: number | string
+  locales: Record<string, LocaleConfig>
+
+  /**
+   * Available locales for the site when it has defined `locales` in its
+   * `themeConfig`. This object is otherwise empty. Keys are paths like `/` or
+   * `/zh/`.
+   */
+  langs: Record<
+    string,
+    {
+      /**
+       * Lang attribute as set on the `<html>` element.
+       * @example `en-US`, `zh-CN`
+       */
+      lang: string
+      /**
+       * Label to display in the language menu.
+       * @example `English`, `简体中文`
+       */
+      label: string
+    }
+  >
+}
+
+type HeadConfig =
+  | [string, Record<string, string>]
+  | [string, Record<string, string>, string]
+
+interface LocaleConfig {
+  lang: string
+  title?: string
+  titleTemplate?: string | boolean
+  description?: string
+  head?: HeadConfig[]
+  label?: string
+  selectText?: string
+}
+
+declare const inBrowser: boolean;
+
+interface Route {
+    path: string;
+    data: PageData;
+    component: Component | null;
+}
+interface Router {
+    route: Route;
+    go: (href?: string) => Promise<void>;
+}
+declare function useRouter(): Router;
+declare function useRoute(): Route;
+
+interface VitePressData<T = any> {
+    site: Ref<SiteData<T>>;
+    page: Ref<PageData>;
+    theme: Ref<T>;
+    frontmatter: Ref<PageData['frontmatter']>;
+    title: Ref<string>;
+    description: Ref<string>;
+    lang: Ref<string>;
+    localePath: Ref<string>;
+}
+declare function useData<T = any>(): VitePressData<T>;
+
+interface EnhanceAppContext {
+    app: App;
+    router: Router;
+    siteData: Ref<SiteData>;
+}
+interface Theme {
+    Layout: Component;
+    NotFound?: Component;
+    enhanceApp?: (ctx: EnhanceAppContext) => void;
+}
+
+declare function withBase(path: string): string;
+
+declare const Content: vue.DefineComponent<{}, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, vue.EmitsOptions, string, vue.VNodeProps & vue.AllowedComponentProps & vue.ComponentCustomProps, Readonly<vue.ExtractPropTypes<{}>>, {}>;
+
+declare const Debug: vue.ComponentOptions<{}, any, any, any, any, any, any, any>;
+
+export { Content, Debug, EnhanceAppContext, HeadConfig, Header, LocaleConfig, PageData, Route, Router, SiteData, Theme, VitePressData, inBrowser, useData, useRoute, useRouter, withBase };

package/dist/client/index.js

@@ -8,5 +8,4 @@ export { inBrowser, withBase } from './app/utils';
 // components
 export { Content } from './app/components/Content';
 import _Debug from './app/components/Debug.vue';
-const Debug = _Debug;
-export { Debug };
+export const Debug = _Debug;

package/dist/client/shared.js

@@ -1,4 +1,5 @@
 export const EXTERNAL_URL_RE = /^https?:/i;
+export const APPEARANCE_KEY = 'vitepress-theme-appearance';
 // @ts-ignore
 export const inBrowser = typeof window !== 'undefined';
 function findMatchRoot(route, roots) {
@@ -52,6 +53,27 @@ export function resolveSiteDataByRoute(siteData, route) {
         langs: createLangDictionary(siteData)
     });
 }
+/**
+ * Create the page title string based on configs.
+ */
+export function createTitle(siteData, pageData) {
+    const title = pageData.title || siteData.title;
+    const template = pageData.titleTemplate ?? siteData.titleTemplate;
+    const templateString = createTitleTemplate(siteData.title, template);
+    return `${title}${templateString}`;
+}
+function createTitleTemplate(siteTitle, template) {
+    if (template === false) {
+        return '';
+    }
+    if (template === true || template === undefined) {
+        return ` | ${siteTitle}`;
+    }
+    if (siteTitle === template) {
+        return '';
+    }
+    return ` | ${template}`;
+}
 /**
  * Clean up the route by removing the `base` path if it's set in config.
  */

package/dist/client/theme-default/Layout.vue

@@ -1,189 +1,55 @@
 <script setup lang="ts">
-import { ref, computed, watch, defineAsyncComponent } from 'vue'
-import { useRoute, useData } from 'vitepress'
-import { isSideBarEmpty, getSideBarConfig } from './support/sideBar'
-
-// components
-import Home from './components/Home.vue'
-import NavBar from './components/NavBar.vue'
-import SideBar from './components/SideBar.vue'
-import Page from './components/Page.vue'
-
-const NoopComponent = () => null
-
-const CarbonAds = __CARBON__
-  ? defineAsyncComponent(() => import('./components/CarbonAds.vue'))
-  : NoopComponent
-const BuySellAds = __BSA__
-  ? defineAsyncComponent(() => import('./components/BuySellAds.vue'))
-  : NoopComponent
-const AlgoliaSearchBox = __ALGOLIA__
-  ? defineAsyncComponent(() => import('./components/AlgoliaSearchBox.vue'))
-  : NoopComponent
-
-// generic state
-const route = useRoute()
-const { site, page, theme, frontmatter } = useData()
-
-// custom layout
-const isCustomLayout = computed(() => !!frontmatter.value.customLayout)
-// home
-const enableHome = computed(() => !!frontmatter.value.home)
-
-// automatic multilang check for AlgoliaSearchBox
-const isMultiLang = computed(() => Object.keys(site.value.langs).length > 1)
-
-// navbar
-const showNavbar = computed(() => {
-  const themeConfig = theme.value
-  if (frontmatter.value.navbar === false || themeConfig.navbar === false) {
-    return false
-  }
-  return (
-    site.value.title || themeConfig.logo || themeConfig.repo || themeConfig.nav
-  )
-})
-
-// sidebar
-const openSideBar = ref(false)
-
-const showSidebar = computed(() => {
-  if (frontmatter.value.home || frontmatter.value.sidebar === false) {
-    return false
-  }
-
-  return !isSideBarEmpty(
-    getSideBarConfig(theme.value.sidebar, route.data.relativePath)
-  )
-})
-
-const toggleSidebar = (to?: boolean) => {
-  openSideBar.value = typeof to === 'boolean' ? to : !openSideBar.value
-}
-
-const hideSidebar = toggleSidebar.bind(null, false)
-// close the sidebar when navigating to a different location
-watch(route, hideSidebar)
-// TODO: route only changes when the pathname changes
-// listening to hashchange does nothing because it's prevented in router
-
-// page classes
-const pageClasses = computed(() => {
-  return [
-    {
-      'no-navbar': !showNavbar.value,
-      'sidebar-open': openSideBar.value,
-      'no-sidebar': !showSidebar.value
-    }
-  ]
-})
+import { provide } from 'vue'
+import { useSidebar, useCloseSidebarOnEscape } from './composables/sidebar'
+import VPSkipLink from './components/VPSkipLink.vue'
+import VPBackdrop from './components/VPBackdrop.vue'
+import VPNav from './components/VPNav.vue'
+import VPLocalNav from './components/VPLocalNav.vue'
+import VPSidebar from './components/VPSidebar.vue'
+import VPContent from './components/VPContent.vue'
+import VPFooter from './components/VPFooter.vue'
+
+const {
+  isOpen: isSidebarOpen,
+  open: openSidebar,
+  close: closeSidebar
+} = useSidebar()
+
+useCloseSidebarOnEscape(isSidebarOpen, closeSidebar)
+
+provide('close-sidebar', closeSidebar)
 </script>
 
 <template>
-  <div class="theme" :class="pageClasses">
-    <NavBar v-if="showNavbar" @toggle="toggleSidebar">
-      <template #search>
-        <slot name="navbar-search">
-          <AlgoliaSearchBox
-            v-if="theme.algolia"
-            :options="theme.algolia"
-            :multilang="isMultiLang"
-          />
-        </slot>
-      </template>
-    </NavBar>
-
-    <SideBar :open="openSideBar">
-      <template #sidebar-top>
-        <slot name="sidebar-top" />
-      </template>
-      <template #sidebar-bottom>
-        <slot name="sidebar-bottom" />
-      </template>
-    </SideBar>
-    <!-- TODO: make this button accessible -->
-    <div class="sidebar-mask" @click="toggleSidebar(false)" />
-
-    <Content v-if="isCustomLayout" />
-
-    <template v-else-if="enableHome">
-      <!-- A slot for customizing the entire homepage easily -->
-      <slot name="home">
-        <Home>
-          <template #hero>
-            <slot name="home-hero" />
-          </template>
-          <template #features>
-            <slot name="home-features" />
-          </template>
-          <template #footer>
-            <slot name="home-footer" />
-          </template>
-        </Home>
-      </slot>
-    </template>
-
-    <Page v-else>
-      <template #top>
-        <slot name="page-top-ads">
-          <div
-            id="ads-container"
-            v-if="theme.carbonAds && theme.carbonAds.carbon"
-          >
-            <CarbonAds
-              :key="'carbon' + page.relativePath"
-              :code="theme.carbonAds.carbon"
-              :placement="theme.carbonAds.placement"
-            />
-          </div>
-        </slot>
-        <slot name="page-top" />
-      </template>
-      <template #bottom>
-        <slot name="page-bottom" />
-        <slot name="page-bottom-ads">
-          <BuySellAds
-            v-if="theme.carbonAds && theme.carbonAds.custom"
-            :key="'custom' + page.relativePath"
-            :code="theme.carbonAds.custom"
-            :placement="theme.carbonAds.placement"
-          />
-        </slot>
-      </template>
-    </Page>
+  <div class="Layout">
+    <VPSkipLink />
+    <VPBackdrop class="backdrop" :show="isSidebarOpen" @click="closeSidebar" />
+    <VPNav />
+    <VPLocalNav :open="isSidebarOpen" @open-menu="openSidebar" />
+    <VPSidebar :open="isSidebarOpen" />
+
+    <VPContent>
+      <template #home-hero-before><slot name="home-hero-before" /></template>
+      <template #home-hero-after><slot name="home-hero-after" /></template>
+      <template #home-features-before><slot name="home-features-before" /></template>
+      <template #home-features-after><slot name="home-features-after" /></template>
+
+      <template #aside-top><slot name="aside-top" /></template>
+      <template #aside-bottom><slot name="aside-bottom" /></template>
+      <template #aside-outline-before><slot name="aside-outline-before" /></template>
+      <template #aside-outline-after><slot name="aside-outline-after" /></template>
+      <template #aside-ads-before><slot name="aside-ads-before" /></template>
+      <template #aside-ads-after><slot name="aside-ads-after" /></template>
+    </VPContent>
+
+    <VPFooter />
   </div>
-
-  <Debug />
 </template>
 
-<style>
-#ads-container {
-  margin: 0 auto;
-}
-
-@media (min-width: 420px) {
-  #ads-container {
-    position: relative;
-    right: 0;
-    float: right;
-    margin: -8px -8px 24px 24px;
-    width: 146px;
-  }
-}
-
-@media (max-width: 420px) {
-  #ads-container {
-    /* Avoid layout shift */
-    height: 105px;
-    margin: 1.75rem 0;
-  }
-}
-
-@media (min-width: 1400px) {
-  #ads-container {
-    position: fixed;
-    right: 8px;
-    bottom: 8px;
-  }
+<style scoped>
+.Layout {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
 }
 </style>