feat: add editRepoBaseUrl config and -R, --edit-repo cli flag support

.changeset/silent-moles-yell.md

@@ -0,0 +1,5 @@
+---
+"@alauda/doom": patch
+---
+
+feat: add `editRepoBaseUrl` config and `-R, --edit-repo` cli flag support

.github/workflows/gh-pages.yml

@@ -37,7 +37,7 @@ jobs:
           # copy the pdf to the tempdir
           cp -r ./dist/*.pdf $tempdir
           # then build the docs with pdf download link
-          yarn docs:build -d
+          yarn docs:build -d -R
           # copy the pdf back to the dist folder
           cp -r $tempdir/*.pdf ./dist
           # remove the tempdir

docs/start.mdx

@@ -96,6 +96,7 @@ Options:
   -E, --exclude <language...>     Include all languages except the specific language(s), `ru` for example
   -o, --out-dir <path>            Override the `outDir` defined in the config file or the default `dist/{base}/{version}`, the resulting path will be `dist/{outDir}/{version}`
   -r, --redirect <enum>           Whether to redirect to the locale closest to `navigator.language` when the user visits the site, could be `auto`, `never` or `only-default-lang` (default: "only-default-lang")
+  -R, --edit-repo [boolean|url]   Whether to enable or override the `editRepoBaseUrl` config feature, `https://github.com/` prefix could be omitted (default: false)
   -n, --no-open [boolean]         Do not open the browser after starting the server
   -h, --help                      display help for command
 

docs/usage/configuration.md

@@ -202,3 +202,9 @@ translate:
 <%= additionalPrompts %>
   userPrompt: # 可选，用于填充到 `systemPrompt` 中的 `ejs` 模板全局参数
 ```
+
+## 在代码仓库编辑文档 \{#edit-repo}
+
+```yaml
+editRepoBaseUrl: alauda/doom/tree/main/docs # https://github.com/ 前缀可以省略，仅当启用 `-R, --edit-repo` 命令行标志符时生效
+```

doom.config.yml

@@ -19,3 +19,4 @@ reference:
         path: docs/usage/configuration.md#引用文档配置
 sidebar:
   collapsed: false
+editRepoBaseUrl: alauda/doom/tree/main/docs

fixture-docs/doom.config.yml

@@ -45,3 +45,4 @@ releaseNotes:
 internalRoutes:
   - '*/internal/*.mdx'
   - '*/concepts/**'
+editRepoBaseUrl: alauda/doom/tree/main/fixture-docs

src/cli/helpers.ts

@@ -43,3 +43,8 @@ export function escapeMarkdownHeadingIds(content: string): string {
       .replace('\\\\{#', '\\{#'),
   )
 }
+
+export const defaultGitHubUrl = (url: string) =>
+  /^https?:\/\//.test(url)
+    ? url
+    : `https://github.com/${url.replace(/^(\/*github.com)?\/+/i, '')}`

src/cli/index.ts

@@ -13,6 +13,7 @@ import { type FSWatcher, watch } from 'chokidar'
 import { type Command, program } from 'commander'
 import { green } from 'yoctocolors'
 
+import { FALSY_VALUES, TRUTHY_VALUES } from '../shared/index.js'
 import type { GlobalCliOptions, ServeOptions } from '../types.js'
 import { setNodeEnv } from '../utils/index.js'
 
@@ -94,6 +95,13 @@ program
     'Whether to redirect to the locale closest to `navigator.language` when the user visits the site, could be `auto`, `never` or `only-default-lang`',
     'only-default-lang',
   )
+  .option(
+    '-R, --edit-repo [boolean|url]',
+    'Whether to enable or override the `editRepoBaseUrl` config feature, `https://github.com/` prefix could be omitted',
+    (value: string) =>
+      FALSY_VALUES.has(value) ? false : TRUTHY_VALUES.has(value) || value,
+    false,
+  )
   .option(
     '-n, --no-open [boolean]',
     'Do not open the browser after starting the server',

src/cli/load-config.ts

@@ -24,6 +24,7 @@ import {
 } from '@shikijs/transformers'
 import { difference } from 'es-toolkit'
 import rehypeRaw from 'rehype-raw'
+import { cyan } from 'yoctocolors'
 
 import { autoTocPlugin } from '../plugins/auto-toc/index.js'
 import {
@@ -53,14 +54,21 @@ import {
   SITES_FILE,
   YAML_EXTENSIONS,
 } from './constants.js'
+import { defaultGitHubUrl } from './helpers.js'
 
 const DEFAULT_LOGO = '/logo.svg'
 
 const KNOWN_LOCALE_CONFIGS: Partial<
-  Record<string, Omit<LocaleConfig, 'lang'>>
+  Record<
+    string,
+    Omit<LocaleConfig, 'lang' | 'editLink'> & { editLink: { text: string } }
+  >
 > = {
   en: {
     label: 'English',
+    editLink: {
+      text: '📝 Edit this page on GitHub',
+    },
   },
   zh: {
     label: '简体中文',
@@ -70,6 +78,9 @@ const KNOWN_LOCALE_CONFIGS: Partial<
     outlineTitle: '本页概览',
     prevPageText: '上一页',
     nextPageText: '下一页',
+    editLink: {
+      text: '📝 在 GitHub 上编辑此页',
+    },
   },
   ru: {
     label: 'Русский',
@@ -80,6 +91,9 @@ const KNOWN_LOCALE_CONFIGS: Partial<
     outlineTitle: 'Обзор страницы',
     prevPageText: 'Предыдущая страница',
     nextPageText: 'Следующая страница',
+    editLink: {
+      text: '📝 Редактировать эту страницу на GitHub',
+    },
   },
 }
 
@@ -98,6 +112,7 @@ const getCommonConfig = async ({
   include,
   exclude,
   redirect,
+  editRepo,
 }: {
   config: UserConfig
   configFilePath?: string
@@ -112,7 +127,8 @@ const getCommonConfig = async ({
   lazy?: boolean
   include?: string[]
   exclude?: string[]
-  redirect?: 'auto' | 'never'
+  redirect?: 'auto' | 'never' | 'only-default-lang'
+  editRepo?: boolean | string
 }): Promise<UserConfig> => {
   const fallbackToZh = 'lang' in config && !config.lang
   root = resolveDocRoot(CWD, root, config.root)
@@ -126,6 +142,24 @@ const getCommonConfig = async ({
     base = userBase + `${version}/`
   }
 
+  let { editRepoBaseUrl } = config
+
+  const editRepoEnabled = !!editRepo
+
+  if (typeof editRepo === 'string') {
+    editRepoBaseUrl = editRepo
+  }
+
+  if (editRepoEnabled) {
+    if (editRepoBaseUrl) {
+      editRepoBaseUrl = defaultGitHubUrl(editRepoBaseUrl)
+    } else {
+      logger.error(
+        `The \`${cyan('-R, --edit-repo')}\` flag is enabled specifically, but no \`${cyan('editRepoBaseUrl')}\` found, it will take no effect`,
+      )
+    }
+  }
+
   const allLanguages: string[] = []
 
   const locales: LocaleConfig[] = []
@@ -151,6 +185,14 @@ const getCommonConfig = async ({
         lang: name,
         label: name,
         ...KNOWN_LOCALE_CONFIGS[name],
+        editLink:
+          editRepoEnabled && editRepoBaseUrl
+            ? {
+                docRepoBaseUrl: editRepoBaseUrl,
+                ...KNOWN_LOCALE_CONFIGS.en!.editLink,
+                ...KNOWN_LOCALE_CONFIGS[name]?.editLink,
+              }
+            : undefined,
       })
     }
   }
@@ -160,6 +202,8 @@ const getCommonConfig = async ({
     locales.map(({ lang }) => lang),
   )
 
+  const { editLink, ...zhLocale } = KNOWN_LOCALE_CONFIGS.zh!
+
   return {
     userBase,
     root,
@@ -191,7 +235,14 @@ const getCommonConfig = async ({
       // https://github.com/web-infra-dev/rspress/issues/2011
       outline: true,
       localeRedirect: redirect,
-      ...(fallbackToZh ? KNOWN_LOCALE_CONFIGS.zh : { locales }),
+      ...(fallbackToZh
+        ? editRepoEnabled && editRepoBaseUrl
+          ? {
+              ...zhLocale,
+              editLink: { ...editLink, docRepoBaseUrl: editRepoBaseUrl },
+            }
+          : zhLocale
+        : { locales }),
     },
     plugins: [
       apiPlugin({
@@ -288,6 +339,7 @@ export async function loadConfig(
     exclude,
     outDir,
     redirect,
+    editRepo,
   }: GlobalCliOptions = {},
 ): Promise<{
   config: UserConfig
@@ -366,6 +418,7 @@ export async function loadConfig(
     include,
     exclude,
     redirect,
+    editRepo,
   })
 
   base = commonConfig.base!

src/cli/new.ts

@@ -221,7 +221,7 @@ export const newCommand = new Command('new')
       const target = path.resolve(render(layout.target, { parameters }))
       const when = layout.when && render(layout.when, { parameters })
 
-      if (JS_STR_FALSY_VALUES.has(when!)) {
+      if (JS_STR_FALSY_VALUES.has(when)) {
         continue
       }
 

src/shared/constants.ts

@@ -1,8 +1,22 @@
 export const ACP_BASE = '/container_platform/'
 
-export const FALSY_VALUES = new Set(['', '0', 'false', 'no', 'off', 'n', 'f'])
+export const FALSY_VALUES = new Set([
+  null,
+  undefined,
+  '',
+  '0',
+  'false',
+  'no',
+  'off',
+  'n',
+  'f',
+])
+
+export const TRUTHY_VALUES = new Set(['1', 'true', 'yes', 'on', 'y', 't'])
 
 export const JS_STR_FALSY_VALUES = new Set([
+  null,
+  undefined,
   '',
   '0',
   'false',

src/types.ts

@@ -28,7 +28,8 @@ export interface GlobalCliOptions {
   include?: string[]
   exclude?: string[]
   outDir?: string
-  redirect?: 'auto' | 'never'
+  redirect?: 'auto' | 'never' | 'only-default-lang'
+  editRepo?: boolean | string
 }
 
 export interface TranslateOptions {
@@ -49,6 +50,7 @@ declare module '@rspress/shared' {
     internalRoutes?: string[]
     translate?: TranslateOptions
     shiki?: PluginShikiOptions
+    editRepoBaseUrl?: string
   }
 }