VitePress 在 Next.js 子目录的部署尝试

过去， fonts.zeoseven.com/docs/ 是那瀑布式布局和一个简易的首屏目录，我自己都感觉非常难用 ...

#开始

npm install -D vitepress

以 Next.js 为基础，首先直接在项目根目录创建一个 /docs 文件夹，用于存放 Markdown(.md) 文件以提供给 VitePress 。

现在，新建一个 /.vitepress/config.js 文件，以配置 VitePress 。

import { defineConfig } from "vitepress";

export default defineConfig({
    base: "/docs/", /* 可以更改为你想要的子目录名称 */
    srcDir: "docs", /* Markdown 文件所在目录，项目根目录下的 /docs */
    outDir: "out/docs" /* 输出到 Next.js 输出目录下的 docs/ */
});

可以在 vitepress.dev 找到来自官方的站点配置文档。

#目录风格模仿

模仿 Next.js 的 /_next 风格将 VitePress 的静态文件设置到 /_assets 目录，这是可选的。

{
    assetsDir: "_assets"
}

结合之前的配置，这将让 VitePress 构建的静态文件输出到 out/docs/_assets 。

#站点地图

VitePress 有开箱即用的 Sitemap 生成，当部署在子目录中时，可以添加上子目录，需要注意尾随斜杠。

{
    sitemap: {
        hostname: "https://example.com/docs/"
    }
}

不过，输出的 sitemap.xml 将出现在 /docs/sitemap.xml 而不是根目录，需要在根目录 Next.js 的公共目录 /public/sitemap.xml 创建一个索引，索引指向 /docs/sitemap.xml 。

<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <sitemap>
        <loc>https://example.com/docs/sitemap.xml</loc>
    </sitemap>
</sitemapindex>

不过据 vitepress.dev ，目前它还只是实验性功能。

#搜索

同样， VitePress 有开箱即用的本地搜索功能。

{
    themeConfig: {
        search: {
            provider: "local"
        }
    }
}

可以在 vitepress.dev 找到来自官方的站点配置文档。

#package.json scripts

{
    "scripts": {
        "dev": "next dev",
        "dev:docs": "vitepress",
        "build": "next build && vitepress build",
        "build:docs": "vitepress build"
    }
}

现在，就可以使用 npm run dev:docs 启动 VitePress 的开发服务器，并且根路径就是 /docs/ 。

当 npm run build 执行完毕时，/out/ 中将包含 docs/ 和 docs/_assets/。

很明显， VitePress 对子目录部署有着专门的兼容性优化 ...