feat: support srcDir config option

docs/config/basics.md

@@ -1,5 +1,9 @@
 # App Config: Basics
 
+::: tip
+The config reference is incomplete since the config format may still receive further changes. For a complete reference of the current available options, refer to [config.ts](https://github.com/vuejs/vitepress/blob/master/src/node/config.ts#L15).
+:::
+
 ## base
 
 - Type: `string`

docs/guide/markdown.md

@@ -364,7 +364,7 @@ It also supports [line highlighting](#line-highlighting-in-code-blocks):
 <!--lint enable strong-marker-->
 
 ::: tip
-The value of `@` corresponds to `process.cwd()`.
+The value of `@` corresponds to the source root. By default it's the VitePress project root, unless `srcDir` is configured.
 :::
 
 You can also use a [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) to only include the corresponding part of the code file. You can provide a custom region name after a `#` following the filepath (`snippet` by default):

src/node/build/bundle.ts

@@ -15,7 +15,7 @@ export async function bundle(
   config: SiteConfig,
   options: BuildOptions
 ): Promise<[RollupOutput, RollupOutput, Record<string, string>]> {
-  const root = config.root
+  const { root, srcDir } = config
   const pageToHashMap = Object.create(null)
 
   // define custom rollup input
@@ -28,14 +28,14 @@ export async function bundle(
   config.pages.forEach((file) => {
     // page filename conversion
     // foo/bar.md -> foo_bar.md
-    input[slash(file).replace(/\//g, '_')] = path.resolve(root, file)
+    input[slash(file).replace(/\//g, '_')] = path.resolve(srcDir, file)
   })
 
   // resolve options to pass to vite
   const { rollupOptions } = options
 
   const resolveViteConfig = (ssr: boolean): ViteUserConfig => ({
-    root,
+    root: srcDir,
     base: config.site.base,
     logLevel: 'warn',
     plugins: createVitePressPlugin(root, config, ssr, pageToHashMap),

src/node/build/render.ts

@@ -103,7 +103,7 @@ function resolvePageImports(
   // find the page's js chunk and inject script tags for its imports so that
   // they are start fetching as early as possible
   const srcPath = normalizePath(
-    fs.realpathSync(path.resolve(config.root, page))
+    fs.realpathSync(path.resolve(config.srcDir, page))
   )
   const pageChunk = result.output.find(
     (chunk) => chunk.type === 'chunk' && chunk.facadeModuleId === srcPath

src/node/config.ts

@@ -30,11 +30,19 @@ export interface UserConfig<ThemeConfig = any> {
    */
   vite?: ViteConfig
   customData?: any
+
+  srcDir?: string
+  srcExclude?: string[]
+
+  /**
+   * @deprecated use `srcExclude` instead
+   */
   exclude?: string[]
 }
 
 export interface SiteConfig<ThemeConfig = any> {
   root: string
+  srcDir: string
   site: SiteData<ThemeConfig>
   configPath: string
   themeDir: string
@@ -56,6 +64,8 @@ export async function resolveConfig(
   const userConfig = await resolveUserConfig(root)
   const site = await resolveSiteData(root, userConfig)
 
+  const srcDir = path.resolve(root, userConfig.srcDir || '.')
+
   // resolve theme path
   const userThemeDir = resolve(root, 'theme')
   const themeDir = (await fs.pathExists(userThemeDir))
@@ -64,11 +74,15 @@ export async function resolveConfig(
 
   const config: SiteConfig = {
     root,
+    srcDir,
     site,
     themeDir,
     pages: await globby(['**.md'], {
-      cwd: root,
-      ignore: ['**/node_modules', ...(userConfig.exclude || [])]
+      cwd: srcDir,
+      ignore: [
+        '**/node_modules',
+        ...(userConfig.srcExclude || userConfig.exclude || [])
+      ]
     }),
     configPath: resolve(root, 'config.js'),
     outDir: resolve(root, 'dist'),

src/node/markdown/markdown.ts

@@ -42,7 +42,7 @@ export interface MarkdownRenderer {
 }
 
 export const createMarkdownRenderer = (
-  root: string,
+  srcDir: string,
   options: MarkdownOptions = {}
 ): MarkdownRenderer => {
   const md = MarkdownIt({
@@ -56,7 +56,7 @@ export const createMarkdownRenderer = (
   md.use(componentPlugin)
     .use(highlightLinePlugin)
     .use(preWrapperPlugin)
-    .use(snippetPlugin, root)
+    .use(snippetPlugin, srcDir)
     .use(hoistPlugin)
     .use(containerPlugin)
     .use(extractHeaderPlugin)

src/node/markdown/plugins/snippet.ts

@@ -78,7 +78,7 @@ function findRegion(lines: Array<string>, regionName: string) {
   return null
 }
 
-export const snippetPlugin = (md: MarkdownIt, root: string) => {
+export const snippetPlugin = (md: MarkdownIt, srcDir: string) => {
   const parser: RuleBlock = (state, startLine, endLine, silent) => {
     const CH = '<'.charCodeAt(0)
     const pos = state.bMarks[startLine] + state.tShift[startLine]
@@ -107,12 +107,13 @@ export const snippetPlugin = (md: MarkdownIt, root: string) => {
      *
      * captures: ['/path/to/file.extension', 'extension', '#region', '{meta}']
      */
-    const rawPathRegexp = /^(.+(?:\.([a-z]+)))(?:(#[\w-]+))?(?: ?({\d+(?:[,-]\d+)*}))?$/
+    const rawPathRegexp =
+      /^(.+(?:\.([a-z]+)))(?:(#[\w-]+))?(?: ?({\d+(?:[,-]\d+)*}))?$/
 
     const rawPath = state.src
       .slice(start, end)
       .trim()
-      .replace(/^@/, root)
+      .replace(/^@/, srcDir)
       .trim()
     const [filename = '', extension = '', region = '', meta = ''] = (
       rawPathRegexp.exec(rawPath) || []

src/node/markdownToVue.ts

@@ -19,18 +19,19 @@ interface MarkdownCompileResult {
 
 export function createMarkdownToVueRenderFn(
   root: string,
+  srcDir: string,
   options: MarkdownOptions = {},
   pages: string[]
 ) {
-  const md = createMarkdownRenderer(root, options)
+  const md = createMarkdownRenderer(srcDir, options)
   pages = pages.map((p) => slash(p.replace(/\.md$/, '')))
 
   return (
     src: string,
     file: string,
     publicDir: string
   ): MarkdownCompileResult => {
-    const relativePath = slash(path.relative(root, file))
+    const relativePath = slash(path.relative(srcDir, file))
 
     const cached = cache.get(src)
     if (cached) {
@@ -58,7 +59,7 @@ export function createMarkdownToVueRenderFn(
         const resolved = slash(
           url.startsWith('/')
             ? url.slice(1)
-            : path.relative(root, path.resolve(dir, url))
+            : path.relative(srcDir, path.resolve(dir, url))
         )
         if (
           !pages.includes(resolved) &&

src/node/plugin.ts

@@ -26,6 +26,7 @@ const isPageChunk = (
 export function createVitePressPlugin(
   root: string,
   {
+    srcDir,
     configPath,
     alias,
     markdown,
@@ -37,7 +38,12 @@ export function createVitePressPlugin(
   ssr = false,
   pageToHashMap?: Record<string, string>
 ): Plugin[] {
-  const markdownToVue = createMarkdownToVueRenderFn(root, markdown, pages)
+  const markdownToVue = createMarkdownToVueRenderFn(
+    root,
+    srcDir,
+    markdown,
+    pages
+  )
 
   const vuePlugin = createVuePlugin({
     include: [/\.vue$/, /\.md$/],
@@ -204,7 +210,7 @@ export function createVitePressPlugin(
           type: 'custom',
           event: 'vitepress:pageData',
           data: {
-            path: `/${slash(path.relative(root, file))}`,
+            path: `/${slash(path.relative(srcDir, file))}`,
             pageData
           }
         })

src/node/server.ts

@@ -9,7 +9,7 @@ export async function createServer(
   const config = await resolveConfig(root)
 
   return createViteServer({
-    root,
+    root: config.srcDir,
     base: config.site.base,
     // logLevel: 'warn',
     plugins: createVitePressPlugin(root, config),