feat(build): switch to vite 3, support clean urls and esm mode (vuejs#856)

Author: brc-dd

.github/contributing.md

@@ -48,7 +48,7 @@ The easiest way to start testing out VitePress is to tweak the VitePress docs. Y
 $ pnpm run docs
 ```
 
-After executing the above command, visit http://localhost:3000 and try modifying the source code. You'll get live update.
+After executing the above command, visit http://localhost:5173 and try modifying the source code. You'll get live update.
 
 If you don't need docs site up and running, you may start VitePress local dev environment with `pnpm run dev`.
 

.github/workflows/release-tag.yml

@@ -1,17 +1,18 @@
+name: Release
+
 on:
   push:
     tags:
       - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
 
-name: Create Release
-
 jobs:
-  build:
-    name: Create Release
+  release:
     runs-on: ubuntu-latest
+
     steps:
-      - name: Checkout code
-        uses: actions/checkout@master
+      - name: Checkout
+        uses: actions/checkout@v3
+
       - name: Create Release for Tag
         id: release_tag
         uses: yyx990803/release-tag@master

.github/workflows/test.yml

@@ -16,17 +16,17 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+
     strategy:
       matrix:
-        node-version: [14, 16]
+        node-version: [14, 16, 18]
+
     steps:
       - name: Checkout
         uses: actions/checkout@v3
 
       - name: Install pnpm
-        uses: pnpm/[email protected]
-        with:
-          version: 7.0.1
+        uses: pnpm/action-setup@v2
 
       - name: Set node version to ${{ matrix.node_version }}
         uses: actions/setup-node@v3

.gitignore

@@ -10,3 +10,5 @@ dist
 node_modules
 pnpm-global
 TODOs.md
+.temp
+*.tgz

.prettierignore

@@ -1,4 +1,3 @@
-/docs
 *.md
 *.vue
 dist

client.d.ts

@@ -2,4 +2,4 @@
 // be able to reference vite/client in project root.
 /// <reference types="vite/client" />
 
-export * from './dist/client'
+export * from './dist/client/index.js'

docs/.vitepress/config.ts

@@ -1,5 +1,4 @@
 import { defineConfig } from '../../src/node'
-
 import { version } from '../../package.json'
 
 export default defineConfig({
@@ -8,6 +7,7 @@ export default defineConfig({
   description: 'Vite & Vue powered static site generator.',
 
   lastUpdated: true,
+  cleanUrls: 'without-subfolders',
 
   themeConfig: {
     nav: nav(),
@@ -58,9 +58,9 @@ function nav() {
         {
           text: 'Contributing',
           link: 'https://github.com/vuejs/vitepress/blob/main/.github/contributing.md'
-        },
-      ],
-    },
+        }
+      ]
+    }
   ]
 }
 

docs/config/app-configs.md

@@ -211,3 +211,28 @@ export default {
   titleTemplate: 'Vite & Vue powered static site generator'
 }
 ```
+
+## cleanUrls (Experimental)
+
+- Type: `'disabled' | 'without-subfolders' | 'with-subfolders'`
+- Default: `'disabled'`
+
+Allows removing trailing `.html` from URLs and, optionally, generating clean directory structure. Available modes:
+
+|          Mode          |   Page    |  Generated Page   |     URL     |
+| :--------------------: | :-------: | :---------------: | :---------: |
+|      `'disabled'`      | `/foo.md` |    `/foo.html`    | `/foo.html` |
+| `'without-subfolders'` | `/foo.md` |    `/foo.html`    |   `/foo`    |
+|  `'with-subfolders'`   | `/foo.md` | `/foo/index.html` |   `/foo`    |
+
+::: warning
+
+Enabling this may require additional configuration on your hosting platform. For it to work, your server must serve the generated page on requesting the URL (see above table) **without a redirect**.
+
+:::
+
+```ts
+export default {
+  cleanUrls: 'with-subfolders'
+}
+```

docs/config/introduction.md

@@ -11,6 +11,10 @@ Place your configuration file at `.vitepress/config.js`. This is where all ViteP
 └─ package.json
 ```
 
+::: tip
+You can also use any of `.ts`, `.cjs`, `.mjs`, `.cts`, `.mts` as the config file extension.
+:::
+
 VitePress comes with 2 types of configs. One is the [App Configs](./app-configs) which configures the site's fundamental features such as setting title of the site, or customize how markdown parser works. Second is the [Theme Config](./theme-configs) which configures the theme of the site, for example, adding a sidebar, or add features such as "Edit this page on GitHub" link.
 
 There's also another configuration you may do in [Frontmatter](./frontmatter-configs). Frontmatter configs can override global configs defined on App Configs or Theme Configs for that specific page. However, there're several options that are only available at frontmatter as well.

docs/guide/deploying.md

@@ -37,7 +37,7 @@ If your site is to be served at a subdirectory (`https://example.com/subdir/`),
   $ yarn docs:serve
   ```
 
-  The `serve` command will boot up a local static web server that will serve the files from `.vitepress/dist` at `http://localhost:5000`. It's an easy way to check if the production build looks fine in your local environment.
+  The `serve` command will boot up a local static web server that will serve the files from `.vitepress/dist` at `http://localhost:4173`. It's an easy way to check if the production build looks fine in your local environment.
 
 - You can configure the port of the server by passing `--port` as an argument.
 

docs/guide/getting-started.md

@@ -31,30 +31,13 @@ $ yarn add --dev vitepress vue
 ::: details Getting missing peer deps warnings?
 `@docsearch/js` has certain issues with its peer dependencies. If you see some commands failing due to them, you can try this workaround for now:
 
-On Yarn v2/v3, add this inside your rc file (`.yarnrc.yml` by default):
-
-```yaml
-packageExtensions:
-  '@docsearch/react@*':
-    peerDependenciesMeta:
-      '@types/react':
-        optional: true
-      'react':
-        optional: true
-      'react-dom':
-        optional: true
-```
-
-On PNPM, add this in your `package.json`:
+If using PNPM, add this in your `package.json`:
 
 ```json
 "pnpm": {
   "peerDependencyRules": {
     "ignoreMissing": [
-      "@algolia/client-search",
-      "@types/react",
-      "react",
-      "react-dom"
+      "@algolia/client-search"
     ]
   }
 }
@@ -90,7 +73,7 @@ Serve the documentation site in the local server.
 $ yarn docs:dev
 ```
 
-VitePress will start a hot-reloading development server at `http://localhost:3000`.
+VitePress will start a hot-reloading development server at `http://localhost:5173`.
 
 ## Step. 4: Add more pages
 
@@ -104,7 +87,7 @@ Let's add another page to the site. Create a file name `getting-started.md` alon
 └─ package.json
 ```
 
-Then, try to access `http://localhost:3000/getting-started` and you should see the content of `getting-started` is shown.
+Then, try to access `http://localhost:5173/getting-started.html` and you should see the content of `getting-started.md` is shown.
 
 This is how VitePress works basically. The directory structure corresponds with the URL path. You add files, and just try to access it.
 

docs/guide/migration-from-vitepress-0.md

@@ -12,7 +12,7 @@ If you're coming from VitePress 0.x version, there're several breaking changes d
   - `children` key is now named `items`.
   - Top level item may not contain `link` at the moment. We're planning to bring it back.
 - `repo`, `repoLabel`, `docsDir`, `docsBranch`, `editLinks`, `editLinkText` are removed in favor of more flexible api.
-  - For adding GitHub link with icon to the nav, use [Social Links](./theme-nav.html#navigation-links) feature.
+  - For adding GitHub link with icon to the nav, use [Social Links](./theme-nav#navigation-links) feature.
   - For adding "Edit this page" feature, use [Edit Link](./theme-edit-link) feature.
 - `lastUpdated` option is now split into `config.lastUpdated` and `themeConfig.lastUpdatedText`.
 - `carbonAds.carbon` is changed to `carbonAds.code`.

docs/guide/migration-from-vuepress.md

@@ -4,7 +4,7 @@
 
 ### Images
 
-Unlike VuePress, VitePress handles [`base`](/guide/asset-handling.html#base-url) of your config automatically when you use static image.
+Unlike VuePress, VitePress handles [`base`](./asset-handling#base-url) of your config automatically when you use static image.
 
 Hence, now you can render images without `img` tag.
 
@@ -14,7 +14,7 @@ Hence, now you can render images without `img` tag.
 ```
 
 ::: warning
-For dynamic images you still need `withBase` as shown in [Base URL guide](/guide/asset-handling.html#base-url).
+For dynamic images you still need `withBase` as shown in [Base URL guide](./asset-handling#base-url).
 :::
 
 Use `<img.*withBase\('(.*)'\).*alt="([^"]*)".*>` regex to find and replace it with `![$2]($1)` to replace all the images with `![](...)` syntax.

docs/guide/theme-introduction.md

@@ -38,6 +38,7 @@ interface Theme {
   Layout: Component // Vue 3 component
   NotFound?: Component
   enhanceApp?: (ctx: EnhanceAppContext) => void
+  setup?: () => void
 }
 
 interface EnhanceAppContext {
@@ -65,6 +66,11 @@ export default {
     // router is VitePress' custom router. `siteData` is
     // a `ref` of current site-level metadata.
   }
+
+  setup() {
+    // this function will be executed inside VitePressApp's
+    // setup hook. all composition APIs are available here.
+  }
 }
 ```
 

docs/package.json

@@ -1,4 +1,6 @@
 {
   "private": true,
-  "name": "vitepress-docs"
+  "devDependencies": {
+    "vitepress": "workspace:*"
+  }
 }

examples/configured/.vitepress/config.js

@@ -1,4 +1,4 @@
-import { defineConfig } from '../../../src/node'
+import { defineConfig } from 'vitepress'
 
 export default defineConfig({
   title: 'Configured Example',