diff --git a/.commitlintrc.cjs b/.commitlintrc.cjs index 536f7ac82d..ad316718d0 100644 --- a/.commitlintrc.cjs +++ b/.commitlintrc.cjs @@ -5,15 +5,12 @@ const getSubDirectories = (dir) => fs .readdirSync(dir) .filter((item) => fs.statSync(path.join(dir, item)).isDirectory()) -const corePackages = getSubDirectories(path.resolve(__dirname, 'packages')) -const ecosystemPackages = getSubDirectories( - path.resolve(__dirname, 'ecosystem'), -) +const packages = getSubDirectories(path.resolve(__dirname, 'packages')) module.exports = { extends: ['@commitlint/config-conventional'], rules: { - 'scope-enum': [2, 'always', [...corePackages, ...ecosystemPackages]], + 'scope-enum': [2, 'always', packages], 'footer-max-line-length': [0], }, } diff --git a/.eslintrc.cjs b/.eslintrc.cjs index e7d0adb478..baf3799456 100644 --- a/.eslintrc.cjs +++ b/.eslintrc.cjs @@ -1,17 +1,6 @@ module.exports = { root: true, extends: 'vuepress', - globals: { - __VUEPRESS_VERSION__: 'readonly', - __VUEPRESS_BASE__: 'readonly', - __VUEPRESS_DEV__: 'readonly', - __VUEPRESS_SSR__: 'readonly', - __VUE_HMR_RUNTIME__: 'readonly', - __VUE_OPTIONS_API__: 'readonly', - __VUE_PROD_DEVTOOLS__: 'readonly', - // workaround for vue3.3 slots, should be removed once eslint-plugin-vue supports this - defineSlots: 'readonly', - }, overrides: [ { files: ['*.ts', '*.vue', '*.cts'], @@ -25,12 +14,6 @@ module.exports = { 'vue/multi-word-component-names': 'off', }, }, - { - files: ['**/client/config.ts'], - rules: { - 'vue/match-component-file-name': 'off', - }, - }, { files: ['**/tests/**/*.ts', 'tsup.config.ts'], rules: { diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml deleted file mode 100644 index 8156978643..0000000000 --- a/.github/workflows/check-docs.yml +++ /dev/null @@ -1,56 +0,0 @@ -name: check-docs - -on: - push: - branches: - - main - paths-ignore: - - 'docs/**' - - '**.md' - pull_request: - branches: - - main - workflow_dispatch: - -jobs: - check-docs: - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, windows-latest, macos-latest] - node: ['18', '20'] - bundler: ['vite', 'webpack'] - - runs-on: ${{ matrix.os }} - - steps: - - uses: actions/checkout@v4 - - - name: Install pnpm - uses: pnpm/action-setup@v2 - - - name: Use Node.js ${{ matrix.node }} - uses: actions/setup-node@v4 - with: - node-version: ${{ matrix.node }} - cache: pnpm - - - name: Install dependencies - run: pnpm install --frozen-lockfile - - - name: Build source code - run: pnpm build - - - name: Build docs with ${{ matrix.bundler }} - run: pnpm docs:build - env: - DOCS_BUNDLER: ${{ matrix.bundler }} - - check-docs-result: - if: ${{ always() }} - name: check-docs result - runs-on: ubuntu-latest - needs: [check-docs] - steps: - - if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }} - run: exit 1 diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index 3172b1c18a..0000000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,46 +0,0 @@ -name: docs - -on: - push: - branches: - - main - paths-ignore: - - '**/__tests__/**' - workflow_dispatch: - -jobs: - docs: - runs-on: ubuntu-latest - - env: - DOCS_GA_ID: G-CTB8FQ7VMW - NODE_VERSION: '18' - - steps: - - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - name: Install pnpm - uses: pnpm/action-setup@v2 - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: ${{ env.NODE_VERSION }} - cache: pnpm - - - name: Install dependencies - run: pnpm install --frozen-lockfile - - - name: Build documentation site - run: pnpm docs:release - - - name: Deploy to GitHub Pages - uses: crazy-max/ghaction-github-pages@v4 - with: - repo: vuepress/vuepress.github.io - target_branch: main - build_dir: docs/.vuepress/dist - env: - GH_PAT: ${{ secrets.GH_PAGES_TOKEN }} diff --git a/docs/contributing.md b/CONTRIBUTING.md similarity index 87% rename from docs/contributing.md rename to CONTRIBUTING.md index 8c417b512a..67769303a3 100644 --- a/docs/contributing.md +++ b/CONTRIBUTING.md @@ -1,7 +1,3 @@ ---- -sidebar: auto ---- - # Contributing Guide ## Overview @@ -19,13 +15,11 @@ In the `packages` directory: - `shared`: Utilities that shared between node side and client side. - `utils`: Utilities that should only be used in node side. -In the `ecosystem` directory: +Here are some wrapper packages that use the above packages: -- `plugin-${name}`: Official plugins. -- `theme-default`: The default theme. - `vuepress`: A wrapper of `vuepress-vite`. -- `vuepress-vite`: A wrapper of `@vuepress/cli` + `@vuepress/bundler-vite` + `@vuepress/theme-default`. If users want to use default theme with vite, they can simply install this package. -- `vuepress-webpack`: A wrapper of `@vuepress/cli` + `@vuepress/bundler-webpack` + `@vuepress/theme-default`. If users want to use default theme with webpack, they can simply install this package. +- `vuepress-vite`: A wrapper of `@vuepress/cli` + `@vuepress/bundler-vite`. If users want to use vite, they can simply install this package. +- `vuepress-webpack`: A wrapper of `@vuepress/cli` + `@vuepress/bundler-webpack`. If users want to use webpack, they can simply install this package. ## Development Setup @@ -62,9 +56,9 @@ Main tools that used in this project: ### `pnpm build` -The `build` script uses `tsc` and `tsup` to compile TypeScript source files to JavaScript dist files. +The `build` script uses `tsup` to compile TypeScript source files to JavaScript dist files. -Also, it will copy necessary resources from source directory to dist directory, because some source files (e.g. `.vue`, `.css` files) would not be processed by `tsc` nor `tsup`, but should keep the same relative path in the dist directory. +Also, it will copy necessary resources from source directory to dist directory, because some source files (e.g. `.vue`, `.css` files) would not be processed by `tsup`, but should keep the same relative path in the dist directory. You may need to run this script first after your clone this repository, because the dist files are ignored by `.gitignore`. diff --git a/docs/zh/contributing.md b/CONTRIBUTING_zh.md similarity index 85% rename from docs/zh/contributing.md rename to CONTRIBUTING_zh.md index 6f82a6c21c..e710045bab 100644 --- a/docs/zh/contributing.md +++ b/CONTRIBUTING_zh.md @@ -1,7 +1,3 @@ ---- -sidebar: auto ---- - # 贡献指南 ## 概览 @@ -19,13 +15,11 @@ sidebar: auto - `shared`: 既可以在 Node 端使用、也可以在客户端使用的工具函数模块。 - `utils`: 仅可以在 Node 端使用的工具函数模块。 -在 `ecosystem` 目录下： +还有一些对上述 Package 进行封装后的 Package ： -- `plugin-${name}`: 官方插件。 -- `theme-default`: 默认主题。 - `vuepress`: 是 `vuepress-vite` 的封装。 -- `vuepress-vite`: 是 `@vuepress/cli` + `@vuepress/bundler-vite` + `@vuepress/theme-default` 的封装。如果用户想使用 默认主题 + Vite ，仅安装这个 Package 就可以了。 -- `vuepress-webpack`: 是 `@vuepress/cli` + `@vuepress/bundler-webpack` + `@vuepress/theme-default` 的封装。如果用户想使用 默认主题 + Webpack ，仅安装这个 Package 就可以了。 +- `vuepress-vite`: 是 `@vuepress/cli` + `@vuepress/bundler-vite` 的封装。如果用户想使用 Vite ，仅安装这个 Package 就可以了。 +- `vuepress-webpack`: 是 `@vuepress/cli` + `@vuepress/bundler-webpack` 的封装。如果用户想使用 Webpack ，仅安装这个 Package 就可以了。 ## 开发配置 @@ -62,9 +56,9 @@ pnpm docs:dev ### `pnpm build` -`build` 命令会使用 `tsc` 和 `tsup` 将 TypeScript 源文件编译为 JavaScript 文件。 +`build` 命令会使用 `tsup` 将 TypeScript 源文件编译为 JavaScript 文件。 -此外，它还会将必要的资源文件从源文件目录复制到输出目录。这是因为一些资源文件不会被 `tsc` 或 `tsup` 处理，但它们仍需要被放置到输出目录，并保持它们的项目对路径不变。 +此外，它还会将必要的资源文件从源文件目录复制到输出目录。这是因为一些资源文件不会被 `tsup` 处理，但它们仍需要被放置到输出目录，并保持它们的项目对路径不变。 你在克隆代码仓库后，可能需要先执行该命令来确保项目代码可以顺利运行，因为编译后的输出目录被 `.gitignore` 排除在仓库以外了。 diff --git a/LICENSE b/LICENSE index 15f1f7e7a4..44387d629b 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2018-present, Yuxi (Evan) You +Copyright (c) 2018-present, VuePress Community Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/docs/.vuepress/components/NpmBadge.vue b/docs/.vuepress/components/NpmBadge.vue deleted file mode 100644 index c9ff7be250..0000000000 --- a/docs/.vuepress/components/NpmBadge.vue +++ /dev/null @@ -1,49 +0,0 @@ - - - - - diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts deleted file mode 100644 index 25a1b4cf1e..0000000000 --- a/docs/.vuepress/config.ts +++ /dev/null @@ -1,183 +0,0 @@ -import process from 'node:process' -import { viteBundler } from '@vuepress/bundler-vite' -import { webpackBundler } from '@vuepress/bundler-webpack' -import { defineUserConfig } from '@vuepress/cli' -import { docsearchPlugin } from '@vuepress/plugin-docsearch' -import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics' -import { registerComponentsPlugin } from '@vuepress/plugin-register-components' -import { shikiPlugin } from '@vuepress/plugin-shiki' -import { defaultTheme } from '@vuepress/theme-default' -import { getDirname, path } from '@vuepress/utils' -import { - head, - navbarEn, - navbarZh, - sidebarEn, - sidebarZh, -} from './configs/index.js' - -const __dirname = getDirname(import.meta.url) -const isProd = process.env.NODE_ENV === 'production' - -export default defineUserConfig({ - // set site base to default value - base: '/', - - // extra tags in `` - head, - - // site-level locales config - locales: { - '/': { - lang: 'en-US', - title: 'VuePress', - description: 'Vue-powered Static Site Generator', - }, - '/zh/': { - lang: 'zh-CN', - title: 'VuePress', - description: 'Vue 驱动的静态网站生成器', - }, - }, - - // specify bundler via environment variable - bundler: - process.env.DOCS_BUNDLER === 'webpack' ? webpackBundler() : viteBundler(), - - // configure default theme - theme: defaultTheme({ - logo: '/images/hero.png', - repo: 'vuepress/vuepress-next', - docsDir: 'docs', - - // theme-level locales config - locales: { - /** - * English locale config - * - * As the default locale of @vuepress/theme-default is English, - * we don't need to set all of the locale fields - */ - '/': { - // navbar - navbar: navbarEn, - // sidebar - sidebar: sidebarEn, - // page meta - editLinkText: 'Edit this page on GitHub', - }, - - /** - * Chinese locale config - */ - '/zh/': { - // navbar - navbar: navbarZh, - selectLanguageName: '简体中文', - selectLanguageText: '选择语言', - selectLanguageAriaLabel: '选择语言', - // sidebar - sidebar: sidebarZh, - // page meta - editLinkText: '在 GitHub 上编辑此页', - lastUpdatedText: '上次更新', - contributorsText: '贡献者', - // custom containers - tip: '提示', - warning: '注意', - danger: '警告', - // 404 page - notFound: [ - '这里什么都没有', - '我们怎么到这来了？', - '这是一个 404 页面', - '看起来我们进入了错误的链接', - ], - backToHome: '返回首页', - // a11y - openInNewWindow: '在新窗口打开', - toggleColorMode: '切换颜色模式', - toggleSidebar: '切换侧边栏', - }, - }, - - themePlugins: { - // only enable git plugin in production mode - git: isProd, - // use shiki plugin in production mode instead - prismjs: !isProd, - }, - }), - - // configure markdown - markdown: { - importCode: { - handleImportPath: (str) => - str.replace(/^@vuepress/, path.resolve(__dirname, '../../ecosystem')), - }, - }, - - // use plugins - plugins: [ - docsearchPlugin({ - appId: '34YFD9IUQ2', - apiKey: '9a9058b8655746634e01071411c366b8', - indexName: 'vuepress', - searchParameters: { - facetFilters: ['tags:v2'], - }, - locales: { - '/zh/': { - placeholder: '搜索文档', - translations: { - button: { - buttonText: '搜索文档', - buttonAriaLabel: '搜索文档', - }, - modal: { - searchBox: { - resetButtonTitle: '清除查询条件', - resetButtonAriaLabel: '清除查询条件', - cancelButtonText: '取消', - cancelButtonAriaLabel: '取消', - }, - startScreen: { - recentSearchesTitle: '搜索历史', - noRecentSearchesText: '没有搜索历史', - saveRecentSearchButtonTitle: '保存至搜索历史', - removeRecentSearchButtonTitle: '从搜索历史中移除', - favoriteSearchesTitle: '收藏', - removeFavoriteSearchButtonTitle: '从收藏中移除', - }, - errorScreen: { - titleText: '无法获取结果', - helpText: '你可能需要检查你的网络连接', - }, - footer: { - selectText: '选择', - navigateText: '切换', - closeText: '关闭', - searchByText: '搜索提供者', - }, - noResultsScreen: { - noResultsText: '无法找到相关结果', - suggestedQueryText: '你可以尝试查询', - reportMissingResultsText: '你认为该查询应该有结果？', - reportMissingResultsLinkText: '点击反馈', - }, - }, - }, - }, - }, - }), - googleAnalyticsPlugin({ - // we have multiple deployments, which would use different id - id: process.env.DOCS_GA_ID ?? '', - }), - registerComponentsPlugin({ - componentsDir: path.resolve(__dirname, './components'), - }), - // only enable shiki plugin in production mode - isProd ? shikiPlugin({ theme: 'dark-plus' }) : [], - ], -}) diff --git a/docs/.vuepress/configs/head.ts b/docs/.vuepress/configs/head.ts deleted file mode 100644 index 8d20be525a..0000000000 --- a/docs/.vuepress/configs/head.ts +++ /dev/null @@ -1,40 +0,0 @@ -import type { HeadConfig } from '@vuepress/core' - -export const head: HeadConfig[] = [ - [ - 'link', - { - rel: 'icon', - type: 'image/png', - sizes: '16x16', - href: `/images/icons/favicon-16x16.png`, - }, - ], - [ - 'link', - { - rel: 'icon', - type: 'image/png', - sizes: '32x32', - href: `/images/icons/favicon-32x32.png`, - }, - ], - ['link', { rel: 'manifest', href: '/manifest.webmanifest' }], - ['meta', { name: 'application-name', content: 'VuePress' }], - ['meta', { name: 'apple-mobile-web-app-title', content: 'VuePress' }], - ['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }], - [ - 'link', - { rel: 'apple-touch-icon', href: `/images/icons/apple-touch-icon.png` }, - ], - [ - 'link', - { - rel: 'mask-icon', - href: '/images/icons/safari-pinned-tab.svg', - color: '#3eaf7c', - }, - ], - ['meta', { name: 'msapplication-TileColor', content: '#3eaf7c' }], - ['meta', { name: 'theme-color', content: '#3eaf7c' }], -] diff --git a/docs/.vuepress/configs/index.ts b/docs/.vuepress/configs/index.ts deleted file mode 100644 index b23dc923d2..0000000000 --- a/docs/.vuepress/configs/index.ts +++ /dev/null @@ -1,3 +0,0 @@ -export * from './head.js' -export * from './navbar/index.js' -export * from './sidebar/index.js' diff --git a/docs/.vuepress/configs/meta.ts b/docs/.vuepress/configs/meta.ts deleted file mode 100644 index 64f53d0cf4..0000000000 --- a/docs/.vuepress/configs/meta.ts +++ /dev/null @@ -1,8 +0,0 @@ -import { createRequire } from 'node:module' -import { fs } from '@vuepress/utils' - -const require = createRequire(import.meta.url) - -export const version = fs.readJsonSync( - require.resolve('@vuepress/core/package.json'), -).version diff --git a/docs/.vuepress/configs/navbar/en.ts b/docs/.vuepress/configs/navbar/en.ts deleted file mode 100644 index 18ccb9cec7..0000000000 --- a/docs/.vuepress/configs/navbar/en.ts +++ /dev/null @@ -1,140 +0,0 @@ -import type { NavbarConfig } from '@vuepress/theme-default' -import { version } from '../meta.js' - -export const navbarEn: NavbarConfig = [ - { - text: 'Guide', - link: '/guide/', - }, - { - text: 'Reference', - children: [ - { - text: 'VuePress', - children: [ - { - text: 'CLI', - link: '/reference/cli.html', - }, - '/reference/config.md', - '/reference/frontmatter.md', - '/reference/components.md', - '/reference/plugin-api.md', - '/reference/theme-api.md', - '/reference/client-api.md', - '/reference/node-api.md', - ], - }, - { - text: 'Bundlers', - children: [ - '/reference/bundler/vite.md', - '/reference/bundler/webpack.md', - ], - }, - { - text: 'Default Theme', - children: [ - '/reference/default-theme/config.md', - '/reference/default-theme/frontmatter.md', - '/reference/default-theme/components.md', - '/reference/default-theme/markdown.md', - '/reference/default-theme/styles.md', - '/reference/default-theme/extending.md', - ], - }, - ], - }, - { - text: 'Plugins', - children: [ - { - text: 'Common Features', - children: [ - '/reference/plugin/back-to-top.md', - '/reference/plugin/container.md', - '/reference/plugin/external-link-icon.md', - '/reference/plugin/google-analytics.md', - '/reference/plugin/medium-zoom.md', - '/reference/plugin/nprogress.md', - '/reference/plugin/register-components.md', - ], - }, - { - text: 'Content Search', - children: [ - '/reference/plugin/docsearch.md', - '/reference/plugin/search.md', - ], - }, - { - text: 'PWA', - children: [ - '/reference/plugin/pwa.md', - '/reference/plugin/pwa-popup.md', - ], - }, - { - text: 'Syntax Highlighting', - children: [ - '/reference/plugin/prismjs.md', - '/reference/plugin/shiki.md', - ], - }, - { - text: 'Theme Development', - children: [ - '/reference/plugin/active-header-links.md', - '/reference/plugin/git.md', - '/reference/plugin/palette.md', - '/reference/plugin/theme-data.md', - '/reference/plugin/toc.md', - ], - }, - ], - }, - { - text: 'Learn More', - children: [ - { - text: 'Advanced', - children: [ - '/advanced/architecture.md', - '/advanced/plugin.md', - '/advanced/theme.md', - { - text: 'Cookbook', - link: '/advanced/cookbook/', - }, - ], - }, - { - text: 'Resources', - children: [ - '/contributing.md', - { - text: 'Awesome VuePress', - link: 'https://github.com/vuepress/awesome-vuepress', - }, - ], - }, - ], - }, - { - text: `v${version}`, - children: [ - { - text: 'Changelog', - link: 'https://github.com/vuepress/vuepress-next/blob/main/CHANGELOG.md', - }, - { - text: 'v1.x', - link: 'https://v1.vuepress.vuejs.org', - }, - { - text: 'v0.x', - link: 'https://v0.vuepress.vuejs.org', - }, - ], - }, -] diff --git a/docs/.vuepress/configs/navbar/index.ts b/docs/.vuepress/configs/navbar/index.ts deleted file mode 100644 index 7183393c31..0000000000 --- a/docs/.vuepress/configs/navbar/index.ts +++ /dev/null @@ -1,2 +0,0 @@ -export * from './en.js' -export * from './zh.js' diff --git a/docs/.vuepress/configs/navbar/zh.ts b/docs/.vuepress/configs/navbar/zh.ts deleted file mode 100644 index c86b1ea6f4..0000000000 --- a/docs/.vuepress/configs/navbar/zh.ts +++ /dev/null @@ -1,137 +0,0 @@ -import type { NavbarConfig } from '@vuepress/theme-default' -import { version } from '../meta.js' - -export const navbarZh: NavbarConfig = [ - { - text: '指南', - link: '/zh/guide/', - }, - { - text: '参考', - children: [ - { - text: 'VuePress', - children: [ - '/zh/reference/cli.md', - '/zh/reference/config.md', - '/zh/reference/frontmatter.md', - '/zh/reference/components.md', - '/zh/reference/plugin-api.md', - '/zh/reference/theme-api.md', - '/zh/reference/client-api.md', - '/zh/reference/node-api.md', - ], - }, - { - text: '打包工具', - children: [ - '/zh/reference/bundler/vite.md', - '/zh/reference/bundler/webpack.md', - ], - }, - { - text: '默认主题', - children: [ - '/zh/reference/default-theme/config.md', - '/zh/reference/default-theme/frontmatter.md', - '/zh/reference/default-theme/components.md', - '/zh/reference/default-theme/markdown.md', - '/zh/reference/default-theme/styles.md', - '/zh/reference/default-theme/extending.md', - ], - }, - ], - }, - { - text: '插件', - children: [ - { - text: '常用功能', - children: [ - '/zh/reference/plugin/back-to-top.md', - '/zh/reference/plugin/container.md', - '/zh/reference/plugin/external-link-icon.md', - '/zh/reference/plugin/google-analytics.md', - '/zh/reference/plugin/medium-zoom.md', - '/zh/reference/plugin/nprogress.md', - '/zh/reference/plugin/register-components.md', - ], - }, - { - text: '内容搜索', - children: [ - '/zh/reference/plugin/docsearch.md', - '/zh/reference/plugin/search.md', - ], - }, - { - text: 'PWA', - children: [ - '/zh/reference/plugin/pwa.md', - '/zh/reference/plugin/pwa-popup.md', - ], - }, - { - text: '语法高亮', - children: [ - '/zh/reference/plugin/prismjs.md', - '/zh/reference/plugin/shiki.md', - ], - }, - { - text: '主题开发', - children: [ - '/zh/reference/plugin/active-header-links.md', - '/zh/reference/plugin/git.md', - '/zh/reference/plugin/palette.md', - '/zh/reference/plugin/theme-data.md', - '/zh/reference/plugin/toc.md', - ], - }, - ], - }, - { - text: '了解更多', - children: [ - { - text: '深入', - children: [ - '/zh/advanced/architecture.md', - '/zh/advanced/plugin.md', - '/zh/advanced/theme.md', - { - text: 'Cookbook', - link: '/zh/advanced/cookbook/', - }, - ], - }, - { - text: '其他资源', - children: [ - '/zh/contributing.md', - { - text: 'Awesome VuePress', - link: 'https://github.com/vuepress/awesome-vuepress', - }, - ], - }, - ], - }, - { - text: `v${version}`, - children: [ - { - text: '更新日志', - link: 'https://github.com/vuepress/vuepress-next/blob/main/CHANGELOG.md', - }, - { - text: 'v1.x', - link: 'https://v1.vuepress.vuejs.org/zh/', - }, - { - text: 'v0.x', - link: 'https://v0.vuepress.vuejs.org/zh/', - }, - ], - }, -] diff --git a/docs/.vuepress/configs/sidebar/en.ts b/docs/.vuepress/configs/sidebar/en.ts deleted file mode 100644 index b358ab590e..0000000000 --- a/docs/.vuepress/configs/sidebar/en.ts +++ /dev/null @@ -1,126 +0,0 @@ -import type { SidebarConfig } from '@vuepress/theme-default' - -export const sidebarEn: SidebarConfig = { - '/guide/': [ - { - text: 'Guide', - children: [ - '/guide/README.md', - '/guide/getting-started.md', - '/guide/configuration.md', - '/guide/page.md', - '/guide/markdown.md', - '/guide/assets.md', - '/guide/i18n.md', - '/guide/deployment.md', - '/guide/theme.md', - '/guide/plugin.md', - '/guide/bundler.md', - '/guide/migration.md', - ], - }, - ], - '/advanced/': [ - { - text: 'Advanced', - children: [ - '/advanced/architecture.md', - '/advanced/plugin.md', - '/advanced/theme.md', - ], - }, - { - text: 'Cookbook', - children: [ - '/advanced/cookbook/README.md', - '/advanced/cookbook/usage-of-client-config.md', - '/advanced/cookbook/adding-extra-pages.md', - '/advanced/cookbook/making-a-theme-extendable.md', - '/advanced/cookbook/passing-data-to-client-code.md', - '/advanced/cookbook/markdown-and-vue-sfc.md', - ], - }, - ], - '/reference/': [ - { - text: 'VuePress Reference', - collapsible: true, - children: [ - '/reference/cli.md', - '/reference/config.md', - '/reference/frontmatter.md', - '/reference/components.md', - '/reference/plugin-api.md', - '/reference/theme-api.md', - '/reference/client-api.md', - '/reference/node-api.md', - ], - }, - { - text: 'Bundlers Reference', - collapsible: true, - children: ['/reference/bundler/vite.md', '/reference/bundler/webpack.md'], - }, - { - text: 'Default Theme Reference', - collapsible: true, - children: [ - '/reference/default-theme/config.md', - '/reference/default-theme/frontmatter.md', - '/reference/default-theme/components.md', - '/reference/default-theme/markdown.md', - '/reference/default-theme/styles.md', - '/reference/default-theme/extending.md', - ], - }, - { - text: 'Official Plugins Reference', - collapsible: true, - children: [ - { - text: 'Common Features', - children: [ - '/reference/plugin/back-to-top.md', - '/reference/plugin/container.md', - '/reference/plugin/external-link-icon.md', - '/reference/plugin/google-analytics.md', - '/reference/plugin/medium-zoom.md', - '/reference/plugin/nprogress.md', - '/reference/plugin/register-components.md', - ], - }, - { - text: 'Content Search', - children: [ - '/reference/plugin/docsearch.md', - '/reference/plugin/search.md', - ], - }, - { - text: 'PWA', - children: [ - '/reference/plugin/pwa.md', - '/reference/plugin/pwa-popup.md', - ], - }, - { - text: 'Syntax Highlighting', - children: [ - '/reference/plugin/prismjs.md', - '/reference/plugin/shiki.md', - ], - }, - { - text: 'Theme Development', - children: [ - '/reference/plugin/active-header-links.md', - '/reference/plugin/git.md', - '/reference/plugin/palette.md', - '/reference/plugin/theme-data.md', - '/reference/plugin/toc.md', - ], - }, - ], - }, - ], -} diff --git a/docs/.vuepress/configs/sidebar/index.ts b/docs/.vuepress/configs/sidebar/index.ts deleted file mode 100644 index 7183393c31..0000000000 --- a/docs/.vuepress/configs/sidebar/index.ts +++ /dev/null @@ -1,2 +0,0 @@ -export * from './en.js' -export * from './zh.js' diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts deleted file mode 100644 index fc75e5127b..0000000000 --- a/docs/.vuepress/configs/sidebar/zh.ts +++ /dev/null @@ -1,129 +0,0 @@ -import type { SidebarConfig } from '@vuepress/theme-default' - -export const sidebarZh: SidebarConfig = { - '/zh/guide/': [ - { - text: '指南', - children: [ - '/zh/guide/README.md', - '/zh/guide/getting-started.md', - '/zh/guide/configuration.md', - '/zh/guide/page.md', - '/zh/guide/markdown.md', - '/zh/guide/assets.md', - '/zh/guide/i18n.md', - '/zh/guide/deployment.md', - '/zh/guide/theme.md', - '/zh/guide/plugin.md', - '/zh/guide/bundler.md', - '/zh/guide/migration.md', - ], - }, - ], - '/zh/advanced/': [ - { - text: '深入', - children: [ - '/zh/advanced/architecture.md', - '/zh/advanced/plugin.md', - '/zh/advanced/theme.md', - ], - }, - { - text: 'Cookbook', - children: [ - '/zh/advanced/cookbook/README.md', - '/zh/advanced/cookbook/usage-of-client-config.md', - '/zh/advanced/cookbook/adding-extra-pages.md', - '/zh/advanced/cookbook/making-a-theme-extendable.md', - '/zh/advanced/cookbook/passing-data-to-client-code.md', - '/zh/advanced/cookbook/markdown-and-vue-sfc.md', - ], - }, - ], - '/zh/reference/': [ - { - text: 'VuePress 参考', - collapsible: true, - children: [ - '/zh/reference/cli.md', - '/zh/reference/config.md', - '/zh/reference/frontmatter.md', - '/zh/reference/components.md', - '/zh/reference/plugin-api.md', - '/zh/reference/theme-api.md', - '/zh/reference/client-api.md', - '/zh/reference/node-api.md', - ], - }, - { - text: '打包工具参考', - collapsible: true, - children: [ - '/zh/reference/bundler/vite.md', - '/zh/reference/bundler/webpack.md', - ], - }, - { - text: '默认主题参考', - collapsible: true, - children: [ - '/zh/reference/default-theme/config.md', - '/zh/reference/default-theme/frontmatter.md', - '/zh/reference/default-theme/components.md', - '/zh/reference/default-theme/markdown.md', - '/zh/reference/default-theme/styles.md', - '/zh/reference/default-theme/extending.md', - ], - }, - { - text: '官方插件参考', - collapsible: true, - children: [ - { - text: '常用功能', - children: [ - '/zh/reference/plugin/back-to-top.md', - '/zh/reference/plugin/container.md', - '/zh/reference/plugin/external-link-icon.md', - '/zh/reference/plugin/google-analytics.md', - '/zh/reference/plugin/medium-zoom.md', - '/zh/reference/plugin/nprogress.md', - '/zh/reference/plugin/register-components.md', - ], - }, - { - text: '内容搜索', - children: [ - '/zh/reference/plugin/docsearch.md', - '/zh/reference/plugin/search.md', - ], - }, - { - text: 'PWA', - children: [ - '/zh/reference/plugin/pwa.md', - '/zh/reference/plugin/pwa-popup.md', - ], - }, - { - text: '语法高亮', - children: [ - '/zh/reference/plugin/prismjs.md', - '/zh/reference/plugin/shiki.md', - ], - }, - { - text: '主题开发', - children: [ - '/zh/reference/plugin/active-header-links.md', - '/zh/reference/plugin/git.md', - '/zh/reference/plugin/palette.md', - '/zh/reference/plugin/theme-data.md', - '/zh/reference/plugin/toc.md', - ], - }, - ], - }, - ], -} diff --git a/docs/.vuepress/public/browserconfig.xml b/docs/.vuepress/public/browserconfig.xml deleted file mode 100644 index 5bdd109f95..0000000000 --- a/docs/.vuepress/public/browserconfig.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - #ffffff - - - diff --git a/docs/.vuepress/public/favicon.ico b/docs/.vuepress/public/favicon.ico deleted file mode 100644 index e481e5dda7..0000000000 Binary files a/docs/.vuepress/public/favicon.ico and /dev/null differ diff --git a/docs/.vuepress/public/images/cookbook/extending-a-theme-01.png b/docs/.vuepress/public/images/cookbook/extending-a-theme-01.png deleted file mode 100644 index 9ba6d7e812..0000000000 Binary files a/docs/.vuepress/public/images/cookbook/extending-a-theme-01.png and /dev/null differ diff --git a/docs/.vuepress/public/images/guide/vuepress-architecture-overview.png b/docs/.vuepress/public/images/guide/vuepress-architecture-overview.png deleted file mode 100644 index 4e64bee976..0000000000 Binary files a/docs/.vuepress/public/images/guide/vuepress-architecture-overview.png and /dev/null differ diff --git a/docs/.vuepress/public/images/guide/vuepress-core-process.png b/docs/.vuepress/public/images/guide/vuepress-core-process.png deleted file mode 100644 index acf17029cd..0000000000 Binary files a/docs/.vuepress/public/images/guide/vuepress-core-process.png and /dev/null differ diff --git a/docs/.vuepress/public/images/hero.png b/docs/.vuepress/public/images/hero.png deleted file mode 100644 index ac6beaff06..0000000000 Binary files a/docs/.vuepress/public/images/hero.png and /dev/null differ diff --git a/docs/.vuepress/public/images/icons/android-chrome-192x192.png b/docs/.vuepress/public/images/icons/android-chrome-192x192.png deleted file mode 100644 index ddd043910e..0000000000 Binary files a/docs/.vuepress/public/images/icons/android-chrome-192x192.png and /dev/null differ diff --git a/docs/.vuepress/public/images/icons/android-chrome-384x384.png b/docs/.vuepress/public/images/icons/android-chrome-384x384.png deleted file mode 100644 index 86e1fd58b3..0000000000 Binary files a/docs/.vuepress/public/images/icons/android-chrome-384x384.png and /dev/null differ diff --git a/docs/.vuepress/public/images/icons/apple-touch-icon.png b/docs/.vuepress/public/images/icons/apple-touch-icon.png deleted file mode 100644 index 208915f1de..0000000000 Binary files a/docs/.vuepress/public/images/icons/apple-touch-icon.png and /dev/null differ diff --git a/docs/.vuepress/public/images/icons/favicon-16x16.png b/docs/.vuepress/public/images/icons/favicon-16x16.png deleted file mode 100644 index ca5047e7b8..0000000000 Binary files a/docs/.vuepress/public/images/icons/favicon-16x16.png and /dev/null differ diff --git a/docs/.vuepress/public/images/icons/favicon-32x32.png b/docs/.vuepress/public/images/icons/favicon-32x32.png deleted file mode 100644 index e275ce9ba1..0000000000 Binary files a/docs/.vuepress/public/images/icons/favicon-32x32.png and /dev/null differ diff --git a/docs/.vuepress/public/images/icons/mstile-150x150.png b/docs/.vuepress/public/images/icons/mstile-150x150.png deleted file mode 100644 index d0b1439483..0000000000 Binary files a/docs/.vuepress/public/images/icons/mstile-150x150.png and /dev/null differ diff --git a/docs/.vuepress/public/images/icons/safari-pinned-tab.svg b/docs/.vuepress/public/images/icons/safari-pinned-tab.svg deleted file mode 100644 index dc0b992c04..0000000000 --- a/docs/.vuepress/public/images/icons/safari-pinned-tab.svg +++ /dev/null @@ -1,23 +0,0 @@ - - - - -Created by potrace 1.11, written by Peter Selinger 2001-2013 - - - - - diff --git a/docs/.vuepress/public/images/logo.png b/docs/.vuepress/public/images/logo.png deleted file mode 100644 index 60e17006ad..0000000000 Binary files a/docs/.vuepress/public/images/logo.png and /dev/null differ diff --git a/docs/.vuepress/public/manifest.webmanifest b/docs/.vuepress/public/manifest.webmanifest deleted file mode 100644 index d2e935f1ae..0000000000 --- a/docs/.vuepress/public/manifest.webmanifest +++ /dev/null @@ -1,21 +0,0 @@ -{ - "name": "VuePress", - "short_name": "VuePress", - "description": "Vue-powered Static Site Generator", - "start_url": "/index.html", - "display": "standalone", - "background_color": "#fff", - "theme_color": "#3eaf7c", - "icons": [ - { - "src": "/images/icons/android-chrome-192x192.png", - "sizes": "192x192", - "type": "image/png" - }, - { - "src": "/images/icons/android-chrome-384x384.png", - "sizes": "384x384", - "type": "image/png" - } - ] -} diff --git a/docs/.vuepress/public/new.html b/docs/.vuepress/public/new.html deleted file mode 100644 index 911989fe20..0000000000 --- a/docs/.vuepress/public/new.html +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/.vuepress/styles/index.scss b/docs/.vuepress/styles/index.scss deleted file mode 100644 index 90dc235ebf..0000000000 --- a/docs/.vuepress/styles/index.scss +++ /dev/null @@ -1,9 +0,0 @@ -:root { - scroll-behavior: smooth; -} - -@media (min-width: 751px) { - #docsearch-container:lang(zh-CN) { - min-width: 184.66px; - } -} diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index bb9568276d..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -home: true -title: Home -heroImage: /images/hero.png -actions: - - text: Get Started - link: /guide/getting-started.html - type: primary - - text: Introduction - link: /guide/ - type: secondary -features: - - title: Simplicity First - details: Minimal setup with markdown-centered project structure helps you focus on writing. - - title: Vue-Powered - details: Enjoy the dev experience of Vue, use Vue components in markdown, and develop custom themes with Vue. - - title: Performant - details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded. - - title: Themes - details: Providing a default theme out of the box. You can also choose a community theme or create your own one. - - title: Plugins - details: Flexible plugin API, allowing plugins to provide lots of plug-and-play features for your site. - - title: Bundlers - details: Default bundler is Vite, while Webpack is also supported. Choose the one you like! -footer: MIT Licensed | Copyright © 2018-present Evan You ---- diff --git a/docs/advanced/architecture.md b/docs/advanced/architecture.md deleted file mode 100644 index b80f495a05..0000000000 --- a/docs/advanced/architecture.md +++ /dev/null @@ -1,36 +0,0 @@ -# Architecture - -## Overview - -![vuepress-architecture-overview](/images/guide/vuepress-architecture-overview.png) - -The above figure shows a brief overview of the VuePress architecture: - -- Node App will generate temp files, including the pages, routes, etc. -- Bundler will handle Client App together with the temp files, just like a common Vue SPA. - -As a developer, you must be aware of that VuePress has two main parts: **Node App** and **Client App**, which is important when developing plugins and themes: - -- The entry file of a plugin or a theme will be loaded in Node App. -- Client files will be loaded in Client App, which will be handled by bundler. For example, components, client config files, etc. - -## Core Process and Hooks - -![vuepress-core-process](/images/guide/vuepress-core-process.png) - -The above figure shows the core process of VuePress Node App and the hooks of [Plugin API](../reference/plugin-api.md): - -- In the **init** stage: - - Theme and plugins will be loaded. That means all the plugins should be used before initialization. - - As we are using markdown-it to parse the markdown file, so we need to create markdown-it instance before loading pages: - - [extendsMarkdownOptions](../reference/plugin-api.md#extendsmarkdownoptions) hook will be processed to create markdown-it instance. - - [extendsMarkdown](../reference/plugin-api.md#extendsmarkdown) hook will be processed extends markdown-it instance. - - Page files will be loaded: - - [extendsPageOptions](../reference/plugin-api.md#extendspageoptions) hook will be processed to create pages. - - [extendsPage](../reference/plugin-api.md#extendspage) hook will be processed to extends page object. -- In the **prepare** stage: - - Temp files will be generated, so all hooks related to client files will be processed here. -- In the **dev / build** stage: - - Bundler will be resolved: - - [extendsBundlerOptions](../reference/plugin-api.md#extendsbundleroptions) hook will be processed to create bundler configuration. - - [alias](../reference/plugin-api.md#alias) hook and [define](../reference/plugin-api.md#define) hook would be used in bundler configuration, so they will be processed here. \ No newline at end of file diff --git a/docs/advanced/cookbook/README.md b/docs/advanced/cookbook/README.md deleted file mode 100644 index da53257d19..0000000000 --- a/docs/advanced/cookbook/README.md +++ /dev/null @@ -1,10 +0,0 @@ -# Introduction - -## What's the Cookbook for? - -- We are introducing essential concepts in the **Guide**, but you may not know how to dig deeper. -- We are listing APIs in the **Reference**, but you may not know how to take full advantage of them. - -So here comes the Cookbook. - -Each recipe will focus on one specific aspect, providing more detailed examples to show you the usages and possibilities of VuePress. diff --git a/docs/advanced/cookbook/adding-extra-pages.md b/docs/advanced/cookbook/adding-extra-pages.md deleted file mode 100644 index 4725368d17..0000000000 --- a/docs/advanced/cookbook/adding-extra-pages.md +++ /dev/null @@ -1,38 +0,0 @@ -# Adding Extra Pages - -Sometimes you might want to add some extra pages without creating a markdown file in the source directory. - -With the help of [Plugin API](../../reference/plugin-api.md) and [Node API](../../reference/node-api.md), we can do that with ease. - -## Add a Default Homepage - -As a theme author, you may not require users to create a `/README.md` file as the homepage, but you want to provide a default one: - -```ts -import { createPage } from '@vuepress/core' - -export default { - // all pages have been loaded after initialization - async onInitialized(app) { - // if the homepage does not exist - if (app.pages.every((page) => page.path !== '/')) { - // create a homepage - const homepage = await createPage(app, { - path: '/', - // set frontmatter - frontmatter: { - layout: 'Layout', - }, - // set markdown content - content: `\ -# Welcome to ${app.options.title} - -This is the default homepage -`, - }) - // add it to `app.pages` - app.pages.push(homepage) - } - }, -} -``` diff --git a/docs/advanced/cookbook/making-a-theme-extendable.md b/docs/advanced/cookbook/making-a-theme-extendable.md deleted file mode 100644 index 8214310f29..0000000000 --- a/docs/advanced/cookbook/making-a-theme-extendable.md +++ /dev/null @@ -1,66 +0,0 @@ -# Making a Theme Extendable - -Sometimes users might want make some minor changes to a theme, but they don't want to fork and modify the entire project. - -With the help of [Theme API](../../reference/theme-api.md), you can make your theme extendable, allowing users to make their own modifications easily. - -You must have known that how to [extend default theme](../../reference/default-theme/extending.md). Here we'll introduce how to make your own theme extendable like default theme. - -## Layout Slots - -This approach requires you to determine which parts of your theme could be extended. It is more suitable for those common customizations like page footer or header. - -You just need to provide slots in your layouts, and tell users how to make use of them: - -```vue - -``` - -## Component Aliases - -This approach requires you to consider which components of your theme should be replaceable, and you also need to split components into a suitable granularity. - -First, set `alias` for replaceable components of you theme: - -```ts -import type { Theme } from '@vuepress/core' -import { getDirname } from '@vuepress/utils' - -const __dirname = getDirname(import.meta.url) - -export const fooTheme = (options): Theme => { - return { - name: 'vuepress-theme-foo', - alias: { - // set alias for replaceable components - '@theme/Navbar.vue': path.resolve(__dirname, 'components/Navbar.vue'), - '@theme/Sidebar.vue': path.resolve(__dirname, 'components/Sidebar.vue'), - }, - } -} -``` - -Next, use those components via aliases in your theme: - -```vue - - - -``` - -Then, users can replace specific components by overriding the `alias` when extending or using your theme. diff --git a/docs/advanced/cookbook/markdown-and-vue-sfc.md b/docs/advanced/cookbook/markdown-and-vue-sfc.md deleted file mode 100644 index cdbc17715e..0000000000 --- a/docs/advanced/cookbook/markdown-and-vue-sfc.md +++ /dev/null @@ -1,78 +0,0 @@ -# Markdown and Vue SFC - -Each Markdown file is first compiled into HTML, and then converted to a Vue SFC. In other words, you can write a Markdown file like a Vue SFC: - -- Blocks ` - - -``` - -**Output** - -_Hello, {{ msg }}_ - - - -_Current count is: {{ count }}_ - - - - - - - - diff --git a/docs/advanced/cookbook/passing-data-to-client-code.md b/docs/advanced/cookbook/passing-data-to-client-code.md deleted file mode 100644 index 28407066c1..0000000000 --- a/docs/advanced/cookbook/passing-data-to-client-code.md +++ /dev/null @@ -1,63 +0,0 @@ -# Passing Data to Client Code - -As we know, VuePress plugin entries and theme entries are processed in Node side, but sometimes you might need to pass data to client side. For example, you want to generate different data when users use different options. - -## Use `define` Hook - -Plugin API provides a [define](../../reference/plugin-api.md#define) hook to define global constants for client code. You can make use of it to pass data to client. - -First, define some constants in `define` hook: - -```ts -export default (options) => ({ - define: { - __FOO__: options.foo || 'str', - __OBJ__: { - bar: options.bar || 123, - }, - }, -}) -``` - -Then use them in client code directly: - -```ts -const foo = __FOO__ -const obj = __OBJ__ -``` - -If you are using TypeScript in client code, you may need to declare the types of the global constants manually: - -```ts -declare const __FOO__: string -declare const __OBJ__: { bar: number } -``` - -## Write and Load Temp Files - -If you need to achieve some more complex features, you can write temp files and load them dynamically in client code. - -First, write a temp file `foo.js`, which will be generated in the [temp](../../reference/config.md#temp) directory: - -```ts -export default (options) => ({ - async onPrepared(app) { - // write temp file - await app.writeTemp('foo.js', `export const foo = ${JSON.stringify(options.foo)}`) - }, -}) -``` - -Then, load the temp file via `@temp` alias in client code: - -```ts -import { foo } from '@temp/foo' -``` - -If you are using TypeScript in client code, you may need to declare the type of the temp module manually: - -```ts -declare module '@temp/foo' { - export const foo: string -} -``` diff --git a/docs/advanced/cookbook/usage-of-client-config.md b/docs/advanced/cookbook/usage-of-client-config.md deleted file mode 100644 index 8dd27dce98..0000000000 --- a/docs/advanced/cookbook/usage-of-client-config.md +++ /dev/null @@ -1,174 +0,0 @@ -# Usage of Client Config - -You can make use of the [client config file](../../guide/configuration.md#client-config-file) directly in your project, or specify the file path in your plugin or theme via [clientConfigFile](../../reference/plugin-api.md#clientconfigfile) hook: - -```ts -import { getDirname, path } from '@vuepress/utils' - -const __dirname = getDirname(import.meta.url) - -const pluginOrTheme = { - clientConfigFile: path.resolve(__dirname, './path/to/clientConfig.ts'), -} -``` - -Inside the client config file, `@vuepress/client` package provides a helper function [defineClientConfig](../../reference/client-api.md#defineclientconfig) to help you define the client config: - -```ts -import { defineClientConfig } from '@vuepress/client' - -export default defineClientConfig({ - enhance({ app, router, siteData }) {}, - setup() {}, - layouts: {}, - rootComponents: [], -}) -``` - -## enhance - -The `enhance` function could be either synchronous or asynchronous. It accepts a context param with following properties: - -- `app` is the Vue application instance that created by [createApp](https://vuejs.org/api/application.html#createapp). -- `router` is the Vue Router instance that created by [createRouter](https://router.vuejs.org/api/#createrouter). -- `siteData` is a ref of an object that generated from user config, including [base](../../reference/config.md#base), [lang](../../reference/config.md#lang), [title](../../reference/config.md#title), [description](../../reference/config.md#description), [head](../../reference/config.md#head) and [locales](../../reference/config.md#locales). - -The `enhance` function will be invoked after the client app is created. It's possible to implement any enhancements to the Vue application. - -### Register Vue Components - -You can register global Vue components via the [app.component](https://vuejs.org/api/application.html#app-component) method: - -```ts -import { defineClientConfig } from '@vuepress/client' -import MyComponent from './MyComponent.vue' - -export default defineClientConfig({ - enhance({ app }) { - app.component('MyComponent', MyComponent) - }, -}) -``` - -### Use Non-SSR-Friendly Features - -VuePress will generate a SSR application to pre-render pages during build. Generally speaking, if a code snippet is using Browser / DOM APIs before client app is mounted, we call it non-SSR-friendly. - -We already provides a [ClientOnly](../../reference/components.md#clientonly) component to wrap non-SSR-friendly content. - -In the `enhance` function, you can make use of the [`__VUEPRESS_SSR__`](../../reference/client-api.md#ssr) flag for that purpose. - -```ts -import { defineClientConfig } from '@vuepress/client' - -export default defineClientConfig({ - async enhance() { - if (!__VUEPRESS_SSR__) { - const nonSsrFriendlyModule = await import('non-ssr-friendly-module') - // ... - } - }, -}) -``` - -### Use Router Methods - -You can make use of the [Router Methods](https://router.vuejs.org/api/#router-methods) that provided by vue-router. For example, add navigation guard: - -```ts -import { defineClientConfig } from '@vuepress/client' - -export default defineClientConfig({ - enhance({ router }) { - router.beforeEach((to) => { - console.log('before navigation') - }) - - router.afterEach((to) => { - console.log('after navigation') - }) - }, -}) -``` - -::: warning -It's not recommended to use `addRoute` method to add dynamic routes here, because those routes will **NOT** be pre-rendered in build mode. - -But you can still do that if you understand the drawback. -::: - -## setup - -The `setup` function would be invoked inside the [setup](https://vuejs.org/api/composition-api-setup.html) hook of the client vue app. - -### Use Composition API - -You can take the `setup` function as part of the [setup](https://vuejs.org/api/composition-api-setup.html) hook of the root component. Thus, all composition APIs are available here. - -```ts -import { defineClientConfig } from '@vuepress/client' -import { provide, ref } from 'vue' -import { useRoute, useRouter } from 'vue-router' - -export default defineClientConfig({ - setup() { - // get the current route location - const route = useRoute() - // get the vue-router instance - const router = useRouter() - // provide a value that can be injected by layouts, pages and other components - const count = ref(0) - provide('count', count) - } -}) -``` - -### Use Non-SSR-Friendly Features - -In the `setup` function, the [`__VUEPRESS_SSR__`](../../reference/client-api.md#ssr) flag is also available. - -Another way to use non-ssr-friendly features is to put them inside the [onMounted](https://vuejs.org/api/composition-api-lifecycle.html#onmounted) hook: - -```ts -import { defineClientConfig } from '@vuepress/client' -import { onMounted } from 'vue' - -export default defineClientConfig({ - setup() { - onMounted(() => { - // use DOM API after mounted - document.querySelector('#app') - }) - } -}) -``` - -## layouts - -The `layouts` options is to set layout components. After layout components are registered here, users can use it via [layout](../../reference/frontmatter.md#layout) frontmatter. - -```ts -import { defineClientConfig } from '@vuepress/client' -import MyLayout from './layouts/MyLayout.vue' - -export default defineClientConfig({ - layouts: { - MyLayout, - }, -}) -``` - -## rootComponents - -The `rootComponents` is a components array to be placed directly into the root node of the client vue app. - -Typical usage of this option is to put some global UI components, like global popup or so: - -```ts -import { defineClientConfig } from '@vuepress/client' -import GlobalPopup from './components/GlobalPopup.vue' - -export default defineClientConfig({ - rootComponents: [GlobalPopup], -}) -``` diff --git a/docs/advanced/plugin.md b/docs/advanced/plugin.md deleted file mode 100644 index e0be81bac6..0000000000 --- a/docs/advanced/plugin.md +++ /dev/null @@ -1,63 +0,0 @@ -# Writing a Plugin - -::: tip -Before reading this guide, you'd better learn the VuePress [architecture](./architecture.md) first. -::: - -## Create a Plugin - -A plugin should be a plain JavaScript object that satisfies the [Plugin API](../reference/plugin-api.md), which is called a *Plugin Object*: - -```ts -const fooPlugin = { - name: 'vuepress-plugin-foo', - // ... -} -``` - -A plugin could also be a function that receives the [app instance](../reference/node-api.md#app) as the param and returns a *Plugin Object*, which is called a *Plugin Function*: - -```ts -const barPlugin = (app) => { - return { - name: 'vuepress-plugin-bar', - // ... - } -} -``` - -A plugin usually needs to allow user options, so we typically provide users with a function to receive options, and returns a *Plugin Object* or a *Plugin Function*. Then your plugin should be converted like this: - -```ts -const fooPlugin = (options) => { - return { - name: 'vuepress-plugin-foo', - // ... - } -} - -const barPlugin = (options) => { - return (app) => { - return { - name: 'vuepress-plugin-bar', - // ... - } - } -} -``` - -## Publish to NPM - -After creating a plugin, you should follow some conventions in the [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json) file before publishing it to NPM: - -```json -{ - "name": "vuepress-plugin-foo", - "keywords": [ - "vuepress-plugin" - ] -} -``` - -- Set `name` to follow the naming convention, i.e. `vuepress-plugin-xxx` or `@org/vuepress-plugin-xxx`, which should be consistent with the [name](../reference/plugin-api.md#name) field of the *Plugin Object*. -- Set `keywords` to include `vuepress-plugin`, so that users can search your plugin on NPM. diff --git a/docs/advanced/theme.md b/docs/advanced/theme.md deleted file mode 100644 index bb83bf1642..0000000000 --- a/docs/advanced/theme.md +++ /dev/null @@ -1,100 +0,0 @@ -# Writing a Theme - -::: tip -Before reading this guide, you'd better learn the guide of [Writing a Plugin](./plugin.md) first. -::: - -## Create a Theme - -A VuePress theme is a special plugin, which should satisfy the [Theme API](../reference/theme-api.md). Like plugins, a theme should also be a *Theme Object* or a *Theme Function*, and could be wrapped with a function to receive options: - -```ts -import { getDirname, path } from '@vuepress/utils' - -const __dirname = getDirname(import.meta.url) - -const fooTheme = (options) => { - // returns a theme object - return { - name: 'vuepress-theme-foo', - - // path to the client config of your theme - clientConfigFile: path.resolve(__dirname, 'client.js'), - - // set custom dev / build template - // if the template is not specified, the default template from `@vuepress/client` will be used - templateBuild: path.resolve(__dirname, 'templates/build.html'), - templateDev: path.resolve(__dirname, 'templates/dev.html'), - - // use plugins - plugins: [ - // ... - ], - - // other plugin APIs are also available - } -} - -const barTheme = (options) => { - // returns a theme function - return (app) => { - return { - name: 'vuepress-theme-bar', - // ... - } - } -} -``` - -Then, create theme's client config file `client.js` : - -```ts -import { defineClientConfig } from '@vuepress/client' -import Layout from './layouts/Layout.vue' -import NotFound from './layouts/NotFound.vue' - -export default defineClientConfig({ - layouts: { - Layout, - NotFound, - }, -}) -``` - -The `layouts` field declares the layouts provided by your theme. A theme must provide at least two layouts: `Layout` and `NotFound`. The former is to provide default layout for common pages, while the latter is to provide layout for 404-not-found page. - -The `Layout` layout should contain the [Content](../reference/components.md#content) component to display the markdown content: - -```vue - -``` - -The `NotFound` layout will be used for the `404.html` page: - -```vue - -``` - -You can provide more layouts, and users can change layout via [layout](../reference/frontmatter.md#layout) frontmatter. - -## Publish to NPM - -Also, there are some conventions for theme in [package.json](https://docs.npmjs.com/cli/v8/configuring-npm/package-json): - -```json -{ - "name": "vuepress-theme-foo", - "keywords": [ - "vuepress-theme" - ] -} -``` - -- Set `name` to follow the naming convention: `vuepress-theme-xxx` or `@org/vuepress-theme-xxx`, which should be consistent with the [name](../reference/theme-api.md#name) field of the *Theme Object*. -- Set `keywords` to include `vuepress-theme`, so that users can search your theme on NPM. diff --git a/docs/guide/README.md b/docs/guide/README.md deleted file mode 100644 index d04f085472..0000000000 --- a/docs/guide/README.md +++ /dev/null @@ -1,39 +0,0 @@ -# Introduction - -VuePress is a markdown-centered static site generator. You can write your content (documentations, blogs, etc.) in [Markdown](https://en.wikipedia.org/wiki/Markdown), then VuePress will help you to generate a static site to host them. - -The purpose of creating VuePress was to support the documentation of Vue.js and its sub-projects, but now it has been helping a large amount of users to build their documentation, blogs, and other static sites. - -## How It Works - -A VuePress site is in fact a single-page application (SPA) powered by [Vue](https://vuejs.org/) and [Vue Router](https://router.vuejs.org). - -Routes are generated according to the relative path of your markdown files. Each Markdown file is compiled into HTML with [markdown-it](https://github.com/markdown-it/markdown-it) and then processed as the template of a Vue component. This allows you to directly use Vue inside your Markdown files and is great when you need to embed dynamic content. - -During development, we start a normal dev-server, and serve the VuePress site as a normal SPA. If you’ve used Vue before, you will notice the familiar development experience when you are writing and developing with VuePress. - -During build, we create a server-rendered version of the VuePress site and render the corresponding HTML by virtually visiting each route. This approach is inspired by [Nuxt](https://nuxtjs.org/)'s `nuxt generate` command and other projects like [Gatsby](https://www.gatsbyjs.org/). - -## Why Not ...? - -### Nuxt - -Nuxt is an outstanding Vue SSR framework, and it is capable of doing what VuePress does. But Nuxt is designed for building applications, while VuePress is more lightweight and focused on content-centric static sites. - -### VitePress - -VitePress is the little brother of VuePress. It's also created and maintained by our Vue.js team. It's even more lightweight and faster than VuePress. However, as a tradeoff, it's more opinionated and less configurable. For example, it does not support plugins. But VitePress is powerful enough to make your content online if you don't need advanced customizations. - -It might not be an appropriate comparison, but you can take VuePress and VitePress as Laravel and Lumen. - -### Docsify / Docute - -Both are great projects and also Vue-powered. Except they are both fully runtime-driven and therefore not SEO-friendly. If you don’t care for SEO and don’t want to mess with installing dependencies, these are still great choices. - -### Hexo - -Hexo has been serving the Vue 2.x docs well. The biggest problem is that its theming system is static and string-based - we want to take advantage of Vue for both the layout and the interactivity. Also, Hexo’s Markdown rendering isn’t the most flexible to configure. - -### GitBook - -We’ve been using GitBook for most of our sub project docs. The primary problem with GitBook is that its development reload performance is intolerable with a large amount of files. The default theme also has a pretty limiting navigation structure, and the theming system is, again, not Vue based. The team behind GitBook is also more focused on turning it into a commercial product rather than an open-source tool. diff --git a/docs/guide/assets.md b/docs/guide/assets.md deleted file mode 100644 index 7d3abb7fdb..0000000000 --- a/docs/guide/assets.md +++ /dev/null @@ -1,121 +0,0 @@ -# Assets - -## Relative URLs - -You can reference any assets using relative URLs in your Markdown content: - -```md -![An image](./image.png) -``` - -or - -```md -![An image](image.png) -``` - -This is generally the suggested way to import images, as users usually place images near the Markdown file that references them. - -## Public Files - -You can put some static assets inside public directory, and they will be copied to the root of the generated directory. - -The default public directory is `.vuepress/public`, which can be changed by [public](../reference/config.md#public) option. - -It would be useful in some cases: - -- You may need to provide static assets that are not directly referenced in any of your Markdown files, for example, favicon and PWA icons. -- You may need to serve some shared static assets, which may even be referenced outside your site, for example, logo images. -- You may want to reference images using absolute URLs in your Markdown content. - -Take our documentation source files as an example, we are putting the logo of VuePress inside the public directory: - -```bash -└─ docs - ├─ .vuepress - | └─ public - | └─ images - | └─ hero.png # <- Logo file - └─ guide - └─ assets.md # <- Here we are -``` - -We can reference our logo in current page like this: - -**Input** - -```md -![VuePress Logo](/images/hero.png) -``` - -**Output** - -![VuePress Logo](/images/hero.png) - -### Base Helper - -If your site is deployed to a non-root URL, for example, `https://foo.github.io/bar/`, then the [base](../reference/config.md#base) should be set to `'/bar/'`. Obviously, your public files would be served like `https://foo.github.io/bar/images/hero.png` after deployment. - -In most cases, you don't need to worry about the reference path of those public files, as VuePress will automatically handle `base` for you: - -```md - -![VuePress Logo](/images/hero.png) -``` - -However, sometimes you may have some dynamical links referencing public files, especially when you are authoring a custom theme. In such case, the `base` could not be handled automatically. To help with that, VuePress provides a [withBase](../reference/client-api.md#withbase) helper to prepend `base` for you: - -```vue - - - -``` - -You can also access the helper by `$withBase` directly: - -```md -VuePress Logo -``` - -## Packages and Path Aliases - -Although it is not a common usage, you can reference images from dependent packages: - -```bash -npm install -D package-name -``` - -Since markdown image syntax regards image links as relative paths by default, you need to use `` tag: - -```md -Image from dependency -``` - -The path aliases that set in config file are also supported: - -```ts -import { getDirname, path } from '@vuepress/utils' - -const __dirname = getDirname(import.meta.url) - -export default { - alias: { - '@alias': path.resolve(__dirname, './path/to/some/dir'), - }, -} -``` - -```md -Image from path alias -``` - -::: tip -Config reference: [alias](../reference/plugin-api.md#alias) -::: diff --git a/docs/guide/bundler.md b/docs/guide/bundler.md deleted file mode 100644 index 1a8640dc0b..0000000000 --- a/docs/guide/bundler.md +++ /dev/null @@ -1,67 +0,0 @@ -# Bundler - -VuePress has been using [Webpack](https://webpack.js.org/) as the bundler to dev and build sites. Since VuePress v2, other bundlers are also supported, and now we are using [Vite](https://vitejs.dev/) as the default bundler. Of course, you can still choose to use Webpack. - -## Choose a Bundler - -When using the [vuepress](https://www.npmjs.com/package/vuepress) package, Vite bundler is installed and used automatically. - -If you want to use Webpack bundler instead, you can remove it and install the [vuepress-webpack](https://www.npmjs.com/package/vuepress-webpack) package instead: - - - - -```bash -pnpm remove vuepress -pnpm add -D vuepress-webpack@next -``` - - - - - -```bash -yarn remove vuepress -yarn add -D vuepress-webpack@next -``` - - - - - -```bash -npm uninstall vuepress -npm install -D vuepress-webpack@next -``` - - - - -::: tip -In fact, the [vuepress](https://www.npmjs.com/package/vuepress) package is just a wrapper of the [vuepress-vite](https://www.npmjs.com/package/vuepress-vite) package. -::: - -## Configure Bundler - -Generally, you could use a bundler without extra configuration, because we have already configured them properly to work with VuePress. - -You can configure bundler for advanced usage via the [bundler](../reference/config.md#bundler) option: - -```ts -import { viteBundler } from 'vuepress' -// import { webpackBundler } from 'vuepress-webpack' - -export default { - bundler: viteBundler({ - vuePluginOptions: { - template: { - compilerOptions: { - isCustomElement: (tag) => tag === 'center', - }, - }, - }, - }), -} -``` - -You can refer to [Bundlers > Vite](../reference/bundler/vite.md) and [Bundlers > Webpack](../reference/bundler/webpack.md) to check out all options of the corresponding bundler. diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md deleted file mode 100644 index f07eed614b..0000000000 --- a/docs/guide/configuration.md +++ /dev/null @@ -1,92 +0,0 @@ -# Configuration - -## Config File - -Without any configuration, the VuePress site is pretty minimal. To customize your site, let’s first create a `.vuepress` directory inside your docs directory. This is where all VuePress-specific files will be placed. Your project structure is probably like this: - -``` -├─ docs -│ ├─ .vuepress -│ │ └─ config.js -│ └─ README.md -├─ .gitignore -└─ package.json -``` - -The essential file for configuring a VuePress site is `.vuepress/config.js`, while TypeScript config file is also supported. You can use `.vuepress/config.ts` instead to get better types hint for VuePress config. - -To be more specific, we have a convention for config file paths (in order of precedence): - -- In current working directory `cwd`: - - `vuepress.config.ts` - - `vuepress.config.js` - - `vuepress.config.mjs` -- In source directory `sourceDir`: - - `.vuepress/config.ts` - - `.vuepress/config.js` - - `.vuepress/config.mjs` - -You can also specify the config file via `--config` option of [CLI](../reference/cli.md): - -```sh -vuepress dev docs --config my-config.js -``` - -A basic config file looks like this: - -```ts -import { defineUserConfig } from 'vuepress' - -export default defineUserConfig({ - lang: 'en-US', - title: 'Hello VuePress', - description: 'Just playing around', -}) -``` - -::: tip -Check out the [Config Reference](../reference/config.md) for a full list of VuePress config. -::: - -## Client Config File - -In most cases, the config file is sufficient to configure your VuePress site. However, sometimes users may want to add some client-side code directly. To help with this, VuePress also supports a client config file: - -``` -├─ docs -│ ├─ .vuepress -│ │ ├─ client.js <--- client config file -│ │ └─ config.js <--- config file -│ └─ README.md -├─ .gitignore -└─ package.json -``` - -Similarly, we also have a convention for client config file paths (in order of precedence): - -- In current working directory `cwd`: - - `vuepress.client.ts` - - `vuepress.client.js` - - `vuepress.client.mjs` -- In source directory `sourceDir`: - - `.vuepress/client.ts` - - `.vuepress/client.js` - - `.vuepress/client.mjs` - -A basic client config file looks like this: - -```ts -import { defineClientConfig } from '@vuepress/client' - -export default defineClientConfig({ - enhance({ app, router, siteData }) {}, - setup() {}, - rootComponents: [], -}) -``` - -::: tip -Unlike config file, client config file could not be specified via CLI options. - -To learn more about client config file, see [Advanced > Cookbook > Usage of Client Config](../advanced/cookbook/usage-of-client-config.md) -::: diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md deleted file mode 100644 index 7f132b6839..0000000000 --- a/docs/guide/deployment.md +++ /dev/null @@ -1,224 +0,0 @@ -# Deployment - -The following guides are based on some shared assumptions: - -- You are placing your Markdown source files inside the `docs` directory of your project; -- You are using the default build output location (`.vuepress/dist`); -- You are using [pnpm](https://pnpm.io) as package manager, while npm and yarn are also supported; -- VuePress is installed as a local dependency in your project, and you have setup the following script in `package.json`: - -```json -{ - "scripts": { - "docs:build": "vuepress build docs" - } -} -``` - -## GitHub Pages - -1. Set the correct [base](../reference/config.md#base) config. - - If you are deploying to `https://.github.io/`, you can omit this step as `base` defaults to `"/"`. - - If you are deploying to `https://.github.io//`, for example your repository is at `https://github.com//`, then set `base` to `"//"`. - -2. Choose your preferred CI tools. Here we take [GitHub Actions](https://github.com/features/actions) as an example. - - Create `.github/workflows/docs.yml` to set up the workflow. - -::: details Click to expand sample config -```yaml -name: docs - -on: - # trigger deployment on every push to main branch - push: - branches: [main] - # trigger deployment manually - workflow_dispatch: - -jobs: - docs: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v4 - with: - # fetch all commits to get last updated time or other git log info - fetch-depth: 0 - - - name: Setup pnpm - uses: pnpm/action-setup@v2 - with: - # choose pnpm version to use - version: 8 - # install deps with pnpm - run_install: true - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - # choose node.js version to use - node-version: 18 - # cache deps for pnpm - cache: pnpm - - # run build script - - name: Build VuePress site - run: pnpm docs:build - - # please check out the docs of the workflow for more details - # @see https://github.com/crazy-max/ghaction-github-pages - - name: Deploy to GitHub Pages - uses: crazy-max/ghaction-github-pages@v4 - with: - # deploy to gh-pages branch - target_branch: gh-pages - # deploy the default output dir of VuePress - build_dir: docs/.vuepress/dist - env: - # @see https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` -::: - -::: tip -Please refer to [GitHub Pages official guide](https://pages.github.com/) for more details. -::: - -## GitLab Pages - -1. Set the correct [base](../reference/config.md#base) config. - - If you are deploying to `https://.gitlab.io/`, you can omit `base` as it defaults to `"/"`. - - If you are deploying to `https://.gitlab.io//`, for example your repository is at `https://gitlab.com//`, then set `base` to `"//"`. - -2. Create `.gitlab-ci.yml` to set up [GitLab CI](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) workflow. - -::: details Click to expand sample config -```yaml -# choose a docker image to use -image: node:18-buster - -pages: - # trigger deployment on every push to main branch - only: - - main - - # cache node_modules - cache: - key: - files: - - pnpm-lock.yaml - paths: - - .pnpm-store - - # Install pnpm - before_script: - - curl -fsSL https://get.pnpm.io/install.sh | sh - - - pnpm config set store-dir .pnpm-store - - # install dependencies and run build script - script: - - pnpm i --frozen-lockfile - - pnpm docs:build --dest public - - artifacts: - paths: - - public -``` -::: - -::: tip -Please refer to [GitLab Pages official guide](https://docs.gitlab.com/ce/user/project/pages/#getting-started) for more details. -::: - -## Google Firebase - -1. Make sure you have [firebase-tools](https://www.npmjs.com/package/firebase-tools) installed. - -2. Create `firebase.json` and `.firebaserc` at the root of your project with the following content: - -`firebase.json`: - -```json -{ - "hosting": { - "public": "./docs/.vuepress/dist", - "ignore": [] - } -} -``` - -`.firebaserc`: - -```json -{ - "projects": { - "default": "" - } -} -``` - -3. After running `pnpm docs:build`, deploy using the command `firebase deploy`. - -::: tip -Please refer to [Firebase CLI official guide](https://firebase.google.com/docs/cli) for more details. -::: - -## Heroku - -1. Install [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli). - -2. Create a Heroku account by [signing up](https://signup.heroku.com). - -3. Run `heroku login` and fill in your Heroku credentials: - -```bash -heroku login -``` - -4. Create a file called `static.json` in the root of your project with the below content: - -`static.json`: - -```json -{ - "root": "./docs/.vuepress/dist" -} -``` - -This is the configuration of your site; read more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static). - -## Kinsta - -See [Set Up VuePress on Kinsta](https://kinsta.com/docs/vuepress-application/). - -## Edgio - -See [Edgio Documentation > Framework Guides > VuePress](https://docs.edg.io/guides/vuepress). - -## Netlify - -1. On [Netlify](https://netlify.com), set up a new project from GitHub with the following settings: - - - **Build Command:** `pnpm docs:build` - - **Publish directory:** `docs/.vuepress/dist` - -2. Set [Environment variables](https://docs.netlify.com/configure-builds/environment-variables) to choose node version: - - - `NODE_VERSION`: 18 - -3. Hit the deploy button. - -## Vercel - -1. Go to [Vercel](https://vercel.com), set up a new project from GitHub with the following settings: - - - **FRAMEWORK PRESET:** `Other` - - **BUILD COMMAND:** `pnpm docs:build` - - **OUTPUT DIRECTORY:** `docs/.vuepress/dist` - -2. Hit the deploy button. diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md deleted file mode 100644 index 944de1e583..0000000000 --- a/docs/guide/getting-started.md +++ /dev/null @@ -1,145 +0,0 @@ -# Getting Started - -::: warning -VuePress v2 is currently in RC (Release Candidate) stage. It's ready to be used for building your site, but the config and API are not stable enough, which is possibly to have minor breaking changes. So make sure to read the [changelog](https://github.com/vuepress/vuepress-next/blob/main/CHANGELOG.md) carefully each time you upgrade a RC version. -::: - -## Prerequisites - -- [Node.js v18.16.0+](https://nodejs.org/) -- Package manager like [pnpm](https://pnpm.io), [yarn](https://classic.yarnpkg.com/en/), [npm](https://www.npmjs.com), etc. - -::: tip - -- When using [pnpm](https://pnpm.io/), you need to install `vue` and `@vuepress/client` as peer-dependencies. -- When using [yarn 2+](https://yarnpkg.com/), you need to set `nodeLinker: 'node-modules'` in your [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc#nodeLinker) file. - -::: - -## Manual Installation - -This section will help you build a basic VuePress documentation site from ground up. If you already have an existing project and would like to keep documentation inside the project, start from Step 3. - -- **Step 1**: Create and change into a new directory - -```bash -mkdir vuepress-starter -cd vuepress-starter -``` - -- **Step 2**: Initialize your project - - - - -```bash -git init -pnpm init -``` - - - - - -```bash -git init -yarn init -``` - - - - - -```bash -git init -npm init -``` - - - - -- **Step 3**: Install VuePress locally - - - - -```bash -pnpm add -D vuepress@next @vuepress/client@next vue -``` - - - - - -```bash -yarn add -D vuepress@next -``` - - - - - -```bash -npm install -D vuepress@next -``` - - - - -- **Step 4**: Add some [scripts](https://classic.yarnpkg.com/en/docs/package-json#toc-scripts) to `package.json` - -```json -{ - "scripts": { - "docs:dev": "vuepress dev docs", - "docs:build": "vuepress build docs" - } -} -``` - -- **Step 5**: Add the default temp and cache directory to `.gitignore` file - -```bash -echo 'node_modules' >> .gitignore -echo '.temp' >> .gitignore -echo '.cache' >> .gitignore -``` - -- **Step 6**: Create your first document - -```bash -mkdir docs -echo '# Hello VuePress' > docs/README.md -``` - -- **Step 7**: Serve the documentation site in the local server - - - - -```bash -pnpm docs:dev -``` - - - - - -```bash -yarn docs:dev -``` - - - - - -```bash -npm run docs:dev -``` - - - - -VuePress will start a hot-reloading development server at [http://localhost:8080](http://localhost:8080). When you modify your markdown files, the content in the browser will be auto updated. - -By now, you should have a basic but functional VuePress documentation site. Next, learn about the basics of [configuration](./configuration.md) in VuePress. diff --git a/docs/guide/i18n.md b/docs/guide/i18n.md deleted file mode 100644 index 0ec8175b74..0000000000 --- a/docs/guide/i18n.md +++ /dev/null @@ -1,72 +0,0 @@ -# I18n - -## Site I18n Config - -To take advantage of multi-language support in VuePress, you first need to use the following file and directory structure: - -``` -docs -├─ README.md -├─ foo.md -├─ nested -│  └─ README.md -└─ zh - ├─ README.md - ├─ foo.md - └─ nested -    └─ README.md -``` - -Then, specify the `locales` option in your [config file](./configuration.md#config-file): - -```ts -export default { - locales: { - // The key is the path for the locale to be nested under. - // As a special case, the default locale can use '/' as its path. - '/': { - lang: 'en-US', - title: 'VuePress', - description: 'Vue-powered Static Site Generator', - }, - '/zh/': { - lang: 'zh-CN', - title: 'VuePress', - description: 'Vue 驱动的静态网站生成器', - }, - }, -} -``` - -If a locale does not have a `lang`, `title`, `description` or `head`, VuePress will fallback to the root-level values. You can omit the root level config as long as they are provided in each locale. - -::: tip -Config reference: [locales](../reference/config.md#locales) -::: - -## Theme I18n Config - -VuePress does not restrict how themes provide multi-language support, so each theme may have different way to handle i18n, and some themes may not provide multi-language support at all. You'd better refer to the theme documentation for detailed guide. - -If you are using default theme, the multi-language support is the same as above: - -```ts -import { defaultTheme } from 'vuepress' - -export default { - theme: defaultTheme({ - locales: { - '/': { - selectLanguageName: 'English', - }, - '/zh/': { - selectLanguageName: '简体中文', - }, - }, - }), -} -``` - -::: tip -Config reference: [Default Theme > locales](../reference/default-theme/config.md#locales) -::: diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md deleted file mode 100644 index bb5947852f..0000000000 --- a/docs/guide/markdown.md +++ /dev/null @@ -1,435 +0,0 @@ -# Markdown - -Make sure you already know Markdown well before reading this section. If not, please learn some [Markdown tutorials](https://commonmark.org/help/) first. - -The Markdown content in VuePress will be parsed by [markdown-it](https://github.com/markdown-it/markdown-it), which supports [syntax extensions](https://github.com/markdown-it/markdown-it#syntax-extensions) via markdown-it plugins. - -You can also configure those built-in extensions, load more markdown-it plugins and implement your own extensions via [markdown](../reference/config.md#markdown) option and [extendsMarkdown](../reference/plugin-api.md#extendsmarkdown) option. - -## Syntax Extensions - -This section will introduce built-in Markdown syntax extensions of VuePress. - -### Embedded - -Embedded by markdown-it: - -- [Tables](https://help.github.com/articles/organizing-information-with-tables/) (GFM) -- [Strikethrough](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) (GFM) - -### Header Anchors - -You might have noticed that, a `#` anchor is displayed when you hover the mouse on the headers of each section. By clicking the `#` anchor, you can jump to the section directly. - -::: tip -This header anchors extension is supported by [markdown-it-anchor](https://github.com/valeriangalliat/markdown-it-anchor). - -Config reference: [markdown.anchor](../reference/config.md#markdown-anchor) -::: - -### Links - -When using Markdown [link syntax](https://spec.commonmark.org/0.29/#link-reference-definitions), VuePress will implement some conversions for you. - -Take our documentation source files as an example: - -```bash -└─ docs - ├─ guide - │ ├─ getting-started.md - │ ├─ markdown.md # <- Here we are - │ └─ README.md - ├─ reference - │ └─ config.md - └─ README.md -``` - -**Raw Markdown** - -```md - -[Home](../README.md) -[Config Reference](../reference/config.md) -[Getting Started](./getting-started.md) - -[Guide](/guide/README.md) -[Config Reference > markdown.links](/reference/config.md#links) - -[GitHub](https://github.com) -``` - -**Converted to** - -```vue - -``` - -**Rendered as** - -[Home](../README.md) -[Config Reference](../reference/config.md) -[Getting Started](./getting-started.md) -[Guide](/guide/README.md) -[Config Reference > markdown.links](/reference/config.md#links) -[GitHub](https://github.com) - -**Explanation** - -- Internal links will be converted to `` for SPA navigation. -- Internal links to `.md` files will be converted to the [page route path](./page.md#routing), and both absolute path and relative path are supported. -- External links will get `target="_blank" rel="noopener noreferrer"` attrs. - -**Suggestion** - -Try to use relative paths instead of absolute paths for internal links to markdown files. - -- Relative paths are a valid links to the target files, and they can navigate correctly when browsing the source files in your editor or repository. -- Relative paths are consistent in different locales, so you don't need to change the locale path when translating your content. - -::: tip -This links extension is supported by our built-in plugin. - -Config reference: [markdown.links](../reference/config.md#markdown-links) -::: - -### Emoji :tada: - -You can add emoji to your Markdown content by typing `:EMOJICODE:`. - -For a full list of available emoji and codes, check out [emoji-cheat-sheet](https://github.com/ikatyang/emoji-cheat-sheet). - -**Input** - -```md -VuePress 2 is out :tada: ! -``` - -**Output** - -VuePress 2 is out :tada: ! - -::: tip -This emoji extension is supported by [markdown-it-emoji](https://github.com/markdown-it/markdown-it-emoji). - -Config reference: [markdown.emoji](../reference/config.md#markdown-emoji) -::: - -### Table of Contents - -If you want to put the table of contents (TOC) of your current page inside your Markdown content, you can use the `[[toc]]` syntax. - -**Input** - -```md -[[toc]] -``` - -**Output** - -[[toc]] - -The headers in TOC will link to the corresponding [header anchors](#header-anchors), so TOC won't work well if you disable header anchors. - -::: tip -This toc extension is supported by [@mdit-vue/plugin-toc](https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc). - -Config reference: [markdown.toc](../reference/config.md#markdown-toc) -::: - -### Code Blocks - -Following code blocks extensions are implemented during markdown parsing in Node side. That means, the code blocks won't be processed in client side. - -#### Line Highlighting - -You can highlight specified lines of your code blocks by adding line ranges mark in your fenced code blocks: - -**Input** - -````md -```ts{1,6-8} -import { defaultTheme, defineUserConfig } from 'vuepress' - -export default defineUserConfig({ - title: 'Hello, VuePress', - - theme: defaultTheme({ - logo: 'https://vuejs.org/images/logo.png', - }), -}) -``` -```` - -**Output** - -```ts{1,6-8} -import { defaultTheme, defineUserConfig } from 'vuepress' - -export default defineUserConfig({ - title: 'Hello, VuePress', - - theme: defaultTheme({ - logo: 'https://vuejs.org/images/logo.png', - }), -}) -``` - -Examples for line ranges mark: - -- Line ranges: `{5-8}` -- Multiple single lines: `{4,7,9}` -- Combined: `{4,7-13,16,23-27,40}` - -::: tip -This line highlighting extension is supported by our built-in plugin, which is forked and modified from [markdown-it-highlight-lines](https://github.com/egoist/markdown-it-highlight-lines). - -Config reference: [markdown.code.highlightLines](../reference/config.md#markdown-code-highlightlines) -::: - -#### Line Numbers - -You must have noticed that the number of lines is displayed on the left side of code blocks. This is enabled by default and you can disable it in config. - -You can add `:line-numbers` / `:no-line-numbers` mark in your fenced code blocks to override the value set in config. - -**Input** - -````md -```ts -// line-numbers is enabled by default -const line2 = 'This is line 2' -const line3 = 'This is line 3' -``` - -```ts:no-line-numbers -// line-numbers is disabled -const line2 = 'This is line 2' -const line3 = 'This is line 3' -``` -```` - -**Output** - -```ts -// line-numbers is enabled by default -const line2 = 'This is line 2' -const line3 = 'This is line 3' -``` - -```ts:no-line-numbers -// line-numbers is disabled -const line2 = 'This is line 2' -const line3 = 'This is line 3' -``` - -::: tip -This line numbers extension is supported by our built-in plugin. - -Config reference: [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers) -::: - -#### Wrap with v-pre - -As [template syntax is allowed in Markdown](#template-syntax), it would also work in code blocks, too. - -To avoid your code blocks being compiled by Vue, VuePress will add [v-pre](https://vuejs.org/api/built-in-directives.html#v-pre) directive to your code blocks by default, which can be disabled in config. - -You can add `:v-pre` / `:no-v-pre` mark in your fenced code blocks to override the value set in config. - -::: warning -The template syntax characters, for example, the "Mustache" syntax (double curly braces) might be parsed by the syntax highlighter. Thus, as the following example, `:no-v-pre` might not work well in some languages. - -If you want to make Vue syntax work in those languages anyway, try to disable the default syntax highlighting and implement your own syntax highlighting in client side. -::: - -**Input** - -````md -```md - -1 + 2 + 3 = {{ 1 + 2 + 3 }} -``` - -```md:no-v-pre - -1 + 2 + 3 = {{ 1 + 2 + 3 }} -``` - -```js:no-v-pre -// This won't be compiled correctly because of js syntax highlighting -const onePlusTwoPlusThree = {{ 1 + 2 + 3 }} -``` -```` - -**Output** - -```md - -1 + 2 + 3 = {{ 1 + 2 + 3 }} -``` - -```md:no-v-pre - -1 + 2 + 3 = {{ 1 + 2 + 3 }} -``` - - - -```js -// This won't be compiled correctly because of js syntax highlighting -const onePlusTwoPlusThree = {{ 1 + 2 + 3 }} -``` - -::: tip -This v-pre extension is supported by our built-in plugin. - -Config reference: [markdown.code.vPre.block](../reference/config.md#markdown-code-vpre-block) -::: - -### Import Code Blocks - -You can import code blocks from files with following syntax: - -```md - -@[code](../foo.js) -``` - -If you want to partially import the file: - -```md - -@[code{1-10}](../foo.js) -``` - -The code language is inferred from the file extension, while it is recommended to specify it explicitly: - -```md - -@[code js](../foo.js) -``` - -In fact, the second part inside the `[]` will be treated as the mark of the code fence, so it supports all the syntax mentioned in the above [Code Blocks](#code-blocks) section: - -```md - -@[code js{2,4-5}](../foo.js) -``` - -Here is a complex example: - -- import line 3 to line 10 of the `'../foo.js'` file -- specify the language as `'js'` -- highlight line 3 of the imported code, i.e. line 5 of the `'../foo.js'` file -- disable line numbers - -```md -@[code{3-10} js{3}:no-line-numbers](../foo.js) -``` - -Notice that path aliases are not available in import code syntax. You can use following config to handle path alias yourself: - -```ts -import { getDirname, path } from '@vuepress/utils' - -const __dirname = getDirname(import.meta.url) - -export default { - markdown: { - importCode: { - handleImportPath: (str) => - str.replace(/^@src/, path.resolve(__dirname, 'path/to/src')), - }, - }, -} -``` - -```md - -@[code](@src/foo.js) -``` - -::: tip -This import code extension is supported by our built-in plugin. - -Config reference: [markdown.importCode](../reference/config.md#markdown-importcode) -::: - -## Using Vue in Markdown - -This section will introduce some basic usage of Vue in Markdown. - -Check out [Cookbook > Markdown and Vue SFC](../advanced/cookbook/markdown-and-vue-sfc.md) for more details. - -### Template Syntax - -As we know: - -- HTML is allowed in Markdown. -- Vue template syntax is compatible with HTML. - -That means, [Vue template syntax](https://vuejs.org/guide/essentials/template-syntax.html) is allowed in Markdown. - -**Input** - -```md -One plus one equals: {{ 1 + 1 }} - - span: {{ i }} -``` - -**Output** - -One plus one equals: {{ 1 + 1 }} - - span: {{ i }} - -### Components - -You can use Vue components directly in Markdown. - -**Input** - -```md -This is default theme built-in `` component -``` - -**Output** - -This is default theme built-in `` component - -::: tip -Check out the [Built-in Components](../reference/components.md) for a full list of built-in components. - -Check out the [Default Theme > Built-in Components](../reference/default-theme/components.md) for a full list of default theme built-in components. -::: - -## Custom Markdown Plugins - -Sometimes #940 - -## Cautions - -### Non-Standard HTML Tags - -Non-standard HTML tags would not be recognized as native HTML tags by Vue template compiler. Instead, Vue will try to resolve those tags as Vue components, and obviously these components usually don't exist. For example: - -- Deprecated HTML tags such as [\
](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/center) and [\](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/font). -- [MathML tags](https://developer.mozilla.org/en-US/docs/Web/MathML), which might be used by some markdown-it LaTeX plugin. - -If you want to use those tags anyway, try either of the following workarounds: - -- Adding a [v-pre](https://vuejs.org/api/built-in-directives.html#v-pre) directive to skip the compilation of the element and its children. Notice that the template syntax would also be invalid. -- Using [compilerOptions.isCustomElement](https://vuejs.org/api/application.html#app-config-compileroptions) to tell Vue template compiler not try to resolve them as components. - - For `@bundler-webpack`, set [vue.compilerOptions](../reference/bundler/webpack.md#vue) - - For `@bundler-vite`, set [vuePluginOptions.template.compilerOptions](../reference/bundler/vite.md#vuepluginoptions) diff --git a/docs/guide/migration.md b/docs/guide/migration.md deleted file mode 100644 index f0c15860dc..0000000000 --- a/docs/guide/migration.md +++ /dev/null @@ -1,393 +0,0 @@ -# Migrating from v1 - -::: warning -Plugins and themes of VuePress v1 are not compatible with VuePress v2. You need to update them to corresponding v2 version. -::: - -Some major changes and enhancements of VuePress v2: - -- VuePress v2 is now using Vue 3, so make sure your components and other client files are compatible with Vue 3. -- VuePress v2 is developed with TypeScript, so it provides better TS support now. It's highly recommended to use TypeScript to develop plugins and themes. VuePress config file also supports TypeScript, and you can use `.vuepress/config.ts` directly. -- VuePress v2 supports both Webpack and Vite as bundler. Now Vite is the default bundler, while you can still choose to use Webpack. You can even use Vite in dev mode to get better development experience, and use Webpack in build mode to get better browser compatibility. -- VuePress v2 is now released as pure ESM packages, and CommonJS config files are no longer supported. - -Core ideas and processes of VuePress v2 are the same with v1, while v2 API has been re-designed and becomes more normalized. So you might encounter breaking changes when migrating an existing v1 project to v2. This guide is here to help you migrating v1 sites / plugins / themes to v2. - -- If you are a common user, you need to read the guide [for users](#for-users). -- If you are a plugin author, you need to read the guide [for plugin authors](#for-plugin-authors). -- If you are a theme author, you need to read the guide [for theme authors](#for-theme-authors). - -## For Users - -### User Config Change - -Config file should be in ESM format, and CommonJS format config file is no longer supported. - -```diff -// .vuepress/config.js - -- module.exports = { -- // user config -- } - -+ export default { -+ // user config -+ } -``` - -#### theme - -Using a theme via string is not supported. Import the theme directly. - -```diff -- module.exports = { -- theme: '@vuepress/theme-default', -- themeConfig: { -- // default theme config -- }, -- } - -+ import { defaultTheme } from 'vuepress' -+ export default { -+ theme: defaultTheme({ -+ // default theme config -+ }) -+ } -``` - -#### themeConfig - -Removed. Set config to the theme directly. - -#### plugins - -Using a plugin via string is not supported. Import the plugin directly. - -```diff -- module.exports = { -- plugins: [ -- [ -- '@vuepress/plugin-google-analytics', -- { -- id: 'G-XXXXXXXXXX', -- }, -- ], -- ], -- } - -+ import { googleAnalyticsPlugin } from '@vuepress/plugin-google-analytics' -+ export default { -+ plugins: [ -+ googleAnalyticsPlugin({ -+ id: 'G-XXXXXXXXXX', -+ }), -+ ], -+ } -``` - -#### shouldPrefetch - -Default value is changed from `() => true` to `true`. - -#### extraWatchFiles - -Removed. - -You can watch files manually in [onWatched](../reference/plugin-api.md#onwatched) hook. - -#### patterns - -Renamed to `pagePatterns` - -#### markdown.lineNumbers - -Moved to [markdown.code.lineNumbers](../reference/config.md#markdown-code-linenumbers). - -Default value is changed from `false` to `true`. - -#### markdown.pageSuffix - -Removed. - -#### markdown.externalLinks - -Moved to [markdown.links.externalAttrs](../reference/config.md#markdown-links). - -#### markdown.toc - -Changed. - -See [Config > markdown.toc](../reference/config.md#markdown-toc) - -#### markdown.plugins - -Removed. - -Use markdown-it plugins in [extendsMarkdown](../reference/plugin-api.md#extendsmarkdown) hook. - -#### markdown.extendMarkdown - -Removed. - -Use [extendsMarkdown](../reference/plugin-api.md#extendsmarkdown) hook. - -#### markdown.extractHeaders - -Moved to [markdown.headers](../reference/config.md#markdown-headers). - -#### Webpack Related Configs - -All webpack related configs are moved to options of `@vuepress/bundler-webpack`, including: - -- `postcss` -- `stylus` -- `scss` -- `sass` -- `less` -- `chainWebpack` -- `configureWebpack` -- `evergreen`: default value is changed from `false` to `true` - -```diff -- module.exports = { -- sass: { /* ... */ }, -- } - -+ import { webpackBundler } from '@vuepress/bundler-webpack' -+ export default { -+ bundler: webpackBundler({ -+ sass: { /* ... */ }, -+ }), -+ } -``` - -Please refer to [Guide > Bundler](./bundler.md). - -### Frontmatter Change - -#### meta - -Removed. - -Use [head](../reference/frontmatter.md#head) instead. For example: - -```yaml -head: - - - meta - - name: foo - content: bar - - - link - - rel: canonical - href: foobar - - - script - - {} - - console.log('hello from frontmatter'); -``` - -Has the same structure with: - -```ts -// .vuepress/config.ts -export default { - // ... - head: [ - ['meta', { name: 'foo', content: 'bar' }], - ['link', { rel: 'canonical', href: 'foobar' }], - ['script', {}, `console.log('hello from frontmatter');`], - ], - // ... -} -``` - -### Permalink Patterns Change - -- `:i_month`: removed -- `:i_day`: removed -- `:minutes`: removed (undocumented in v1) -- `:seconds`: removed (undocumented in v1) -- `:regular`: renamed to `:raw` - -See [Frontmatter > permalinkPattern](../reference/frontmatter.md#permalinkpattern). - -### Palette System Change - -The stylus palette system of VuePress v1 (i.e. `styles/palette.styl` and `styles/index.styl`) is no longer provided by VuePress Core. - -The palette system is extracted to [@vuepress/plugin-palette](../reference/plugin/palette.md). - -Theme authors can use their own way to allow users to customize styles, and not be limited with stylus. - -If you are using default theme, the palette system is still available but migrated to SASS, while most variables have been migrated to CSS variables. See [Default Theme > Styles](../reference/default-theme/styles.md). - -### Conventional Files Change - -#### .vuepress/enhanceApp.js - -Renamed to `.vuepress/client.{js,ts}`, and the usage has been changed, too. - -See [Advanced > Cookbook > Usage of Client Config](../advanced/cookbook/usage-of-client-config.md). - -#### .vuepress/components/ - -Files in this directory will not be registered as Vue components automatically. - -You need to use [@vuepress/plugin-register-components](../reference/plugin/register-components.md), or register your components manually in `.vuepress/client.{js,ts}`. - -#### .vuepress/theme/ - -This directory will not be used as local theme implicitly if it is existed. - -You need to import and set your local theme via [theme](../reference/config.md#theme) option. - -### Markdown Change - -- Markdown slot is no longer supported. -- Markdown image syntax does not support webpack aliases anymore. Links without `./` prefix are also treated as relative links, which is aligned with the behavior of the native markdown image syntax. If you want to use aliases in image paths, or use images from external packages, you should use `` tag instead. - -```diff -- ![](@alias/foo.png) -- ![](package-name/bar.png) - -+ -+ -``` - -### CLI Change - -#### eject command - -Removed. - -#### cache options - -- `-c, --cache [cache]`: changed to `--cache `, which means that the shorthand `-c` is not for `cache` option, and the value of `cache` option is not optional. -- `--no-cache`: renamed to `--clean-cache` . - -### Default Theme Change - -#### Built-in Components - -- `` and `` renamed to `` and `` -- `` - - `$badgeErrorColor` palette variable renamed to `$badgeDangerColor` - - `type` prop only accepts `tip`, `warning` and `danger` now - -#### Palette System - -The palette system of default theme has migrated to SASS and CSS variables. - -See [Default Theme > Styles](../reference/default-theme/styles.md). - -#### Theme Config - -Default theme config has been changed a lot. You'd better check the config reference of v2 default theme to migrate it properly. - -See [Default Theme > Config](../reference/default-theme/config.md). - -Here we list some notable changes: - -##### Sidebar Config - -```diff -- sidebar: { -- title: 'Foo Bar', -- path: '/foo/bar.html', -- collapsable: true, -- children: [ -- ['/baz', 'Baz'], -- ], -- } - -+ sidebar: { -+ text: 'Foo Bar', -+ link: '/foo/bar.html', -+ collapsible: true, -+ children: [ -+ { -+ text: 'Baz', -+ link: '/baz', -+ } -+ ], -+ } -``` - -### Official Plugins Change - -Check the v2 docs of official plugins. - -### Community Themes and Plugins - -Themes and plugins of v1 are not compatible with v2. - -Please make sure that those themes and plugins you are using have supported v2, and refer to their own documentation for migration guide. - -## For Plugin Authors - -Some major breaking changes: - -- You cannot use other plugins in your plugin anymore, which avoids lots of potential issues caused by plugin nesting. If your plugin depends on other plugins, you could list them in the docs to ask users import them manually. Alternatively, you can provide users with an array of plugins for convenience. -- Most of the v1 hooks have equivalents in v2. The only exception is `extendsCli`, which has been removed. -- Webpack related hooks are removed, because VuePress Core has decoupled with webpack. You can try to use [extendsBundlerOptions](../reference/plugin-api.md#extendsbundleroptions) hook for similar purpose, and make sure to work with all bundlers. - -For more detailed guide about how to write a plugin in v2, see [Advanced > Writing a Plugin](../advanced/plugin.md). - -### Plugin API Change - -- `plugins`: removed -- `ready`: renamed to `onPrepared` -- `updated`: renamed to `onWatched` -- `generated`: renamed to `onGenerated` -- `additionalPages`: removed, use `app.pages.push(createPage())` in `onInitialized` hook -- `clientDynamicModules`: removed, use `app.writeTemp()` in `onPrepared` hook -- `enhanceAppFiles`: removed, use `clientConfigFile` hook -- `globalUIComponents`: removed, use `clientConfigFile` hook -- `clientRootMixin`: removed, use `clientConfigFile` hook -- `extendMarkdown`: renamed to `extendsMarkdown` -- `chainMarkdown`: removed -- `extendPageData`: renamed to `extendsPage` -- `extendsCli`: removed -- `configureWebpack`: removed -- `chainWebpack`: removed -- `beforeDevServer`: removed -- `afterDevServer`: removed - -See [Plugin API](../reference/plugin-api.md). - -## For Theme Authors - -Although we do not allow using other plugins in a plugin anymore, you can still use plugins in your theme. - -Some major breaking changes: - -- There is no **conventional theme directory structure** anymore. - - The file `theme/enhanceApp.js` will not be used as client app enhance file implicitly. You need to specify it explicitly in `clientConfigFile` hook. - - Files in `theme/global-components/` directory will not be registered as Vue components automatically. You need to use [@vuepress/plugin-register-components](../reference/plugin/register-components.md), or register components manually in `clientConfigFile`. - - Files in `theme/layouts/` directory will not be registered as layout components automatically. You need to specify it explicitly in `layouts` option in `clientConfigFile`. - - Files in `theme/templates/` directory will not be used as dev / ssr template automatically. You need to specify theme explicitly in `templateBuild` and `templateDev` option. - - Always provide a valid js entry file, and do not use `"main": "layouts/Layout.vue"` as the theme entry anymore. -- `themeConfig` is removed from user config and site data. To access the `themeConfig` as you would via `this.$site.themeConfig` in v1, we now recommend using the [@vuepress/plugin-theme-data](../reference/plugin/theme-data.md) plugin and its `useThemeData` composition API. -- Stylus is no longer the default CSS pre-processor, and the stylus palette system is not embedded. If you still want to use similar palette system as v1, [@vuepress/plugin-palette](../reference/plugin/palette.md) may help. -- Markdown code blocks syntax highlighting by Prism.js is not embedded by default. You can use either [@vuepress/plugin-prismjs](../reference/plugin/prismjs.md) or [@vuepress/plugin-shiki](../reference/plugin/shiki.md), or implement syntax highlighting in your own way. -- For scalability concerns, `this.$site.pages` is not available any more. - -For more detailed guide about how to write a theme in v2, see [Advanced > Writing a Theme](../advanced/theme.md). - -### Theme API Change - -#### layouts - -Removed. - -Now you need to specify layout component in the client config file of your theme. - -See [Advanced > Writing a theme](../advanced/theme.md). - -#### extend - -Renamed to `extends`. - -You can still inherit a parent theme with `extends: parentTheme()`, which will extends the plugins, layouts, etc. - -You can refer to [Default Theme > Extending](../reference/default-theme/extending.md) for how to extend default theme. - -The `@theme` and `@parent-theme` aliases are removed by default, but you can still make a extendable theme with similar approach, see [Advanced > Cookbook > Making a Theme Extendable](../advanced/cookbook/making-a-theme-extendable.md). diff --git a/docs/guide/page.md b/docs/guide/page.md deleted file mode 100644 index 2c627c8aea..0000000000 --- a/docs/guide/page.md +++ /dev/null @@ -1,64 +0,0 @@ -# Page - -VuePress is markdown-centered. Each markdown file inside your project is a standalone page. - -## Routing - -By default, the route path of a page is determined by the relative path of your markdown file. - -Assuming this is the directory structure of your markdown files: - -``` -└─ docs - ├─ guide - │ ├─ getting-started.md - │ └─ README.md - ├─ contributing.md - └─ README.md -``` - -Take the `docs` directory as your [sourceDir](../reference/cli.md), e.g. you are running `vuepress dev docs` command. Then the route paths of your markdown files would be: - -| Relative Path | Route Path | -|-----------------------------|-------------------------------| -| `/README.md` | `/` | -| `/index.md` | `/` | -| `/contributing.md` | `/contributing.html` | -| `/guide/README.md` | `/guide/` | -| `/guide/getting-started.md` | `/guide/getting-started.html` | - -::: tip -By default, both `README.md` and `index.md` would be converted to `index.html` and generate a slash-ending route path. However, it might cause conflicts if you want to keep both of the two files. - -In such case, you can set the [pagePatterns](../reference/config.md#pagepatterns) to avoid one of them being processed by VuePress, e.g. use `['**/*.md', '!**/README.md', '!.vuepress', '!node_modules']` to exclude all `README.md` files. - -Also, some symbols like `:` and `+` may have special meanings for vue-router, so you should avoid using them, see [vue-router docs](https://router.vuejs.org/guide/essentials/route-matching-syntax.html) for more details. -::: - -## Frontmatter - -A markdown file could contain a [YAML](https://yaml.org/) frontmatter. The frontmatter must be at the top of the Markdown file and must be wrapped with a couple of triple-dashed lines. Here is a basic example: - -```md ---- -lang: en-US -title: Title of this page -description: Description of this page ---- -``` - -You must have noticed that those fields are similar with the [Site Config](./configuration.md#site-config) in the [Config File](./configuration.md#config-file). You can override `lang`, `title`, `description`, etc., of current page via frontmatter. So you can take frontmatter as page scope config. - -Also, VuePress has built-in support for some frontmatter fields, and your theme may have its own special frontmatter, too. - -::: tip -Check out the [Frontmatter Reference](../reference/frontmatter.md) for a full list of VuePress built-in frontmatter. - -Check out the [Default Theme > Frontmatter Reference](../reference/default-theme/frontmatter.md) for the frontmatter of default theme. -::: - -## Content - -The main content of your page is written in Markdown. VuePress will firstly transform your Markdown to HTML code, then treat the HTML code as `