@alauda/doom 0.8.2 → 0.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/cli/index.js CHANGED
@@ -26,22 +26,23 @@ program
26
26
  .configureHelp({
27
27
  showGlobalOptions: true,
28
28
  })
29
- .option('-c, --config [config]', 'Specify the path to the config file')
29
+ .option('-c, --config <config>', 'Specify the path to the config file')
30
30
  .option('-v <version>', 'Specify the version of the documentation')
31
31
  .option('-p, --prefix <prefix>', 'Specify the prefix of the documentation base')
32
32
  .option('-f, --force [boolean]', 'Force to fetch latest reference remotes or scaffolding templates, otherwise use local cache', (value) => !!value && value !== 'false', false)
33
+ .option('-i, --ignore [boolean]', 'Ignore internal routes', (value) => !!value && value !== 'false', false)
33
34
  .command('dev', { isDefault: true })
34
35
  .description('Start the development server')
35
36
  .argument('[root]', 'Root directory of the documentation')
36
- .option('--port [port]', 'Port number')
37
37
  .option('--host [host]', 'Host name')
38
+ .option('--port [port]', 'Port number')
38
39
  .action(async function (root) {
39
40
  setNodeEnv('development');
40
41
  let devServer;
41
42
  let cliWatcher;
42
- const { config: configFile, v: version, prefix, force, ...server } = this.optsWithGlobals();
43
+ const { port, host, ...globalOptions } = this.optsWithGlobals();
43
44
  const startDevServer = async () => {
44
- const { config, filepath } = await loadConfig(root, configFile, prefix, version, force);
45
+ const { config, filepath } = await loadConfig(root, globalOptions);
45
46
  const docDirectory = config.root;
46
47
  try {
47
48
  devServer = await dev({
@@ -49,7 +50,7 @@ program
49
50
  appDirectory: CWD,
50
51
  docDirectory,
51
52
  extraBuilderConfig: {
52
- server,
53
+ server: { host, port },
53
54
  },
54
55
  });
55
56
  }
@@ -104,8 +105,7 @@ program
104
105
  .argument('[root]', 'Root directory of the documentation')
105
106
  .action(async function (root) {
106
107
  setNodeEnv('production');
107
- const { config: configFile, prefix, v: version, force, } = this.optsWithGlobals();
108
- const { config } = await loadConfig(root, configFile, prefix, version, force);
108
+ const { config } = await loadConfig(root, this.optsWithGlobals());
109
109
  const docDirectory = config.root;
110
110
  const runBuild = () => build({
111
111
  config,
@@ -123,15 +123,16 @@ program
123
123
  .alias('serve')
124
124
  .description('Preview the built documentation')
125
125
  .argument('[root]', 'Root directory of the documentation')
126
- .option('--port [port]', 'Port number', '4173')
127
126
  .option('--host [host]', 'Host name')
127
+ .option('--port [port]', 'Port number', '4173')
128
128
  .action(async function (root) {
129
129
  setNodeEnv('production');
130
- const { config: configFile, prefix, v: version, force, ...server } = this.optsWithGlobals();
131
- const { config } = await loadConfig(root, configFile, prefix, version, force);
130
+ const { port, host, ...globalOptions } = this.optsWithGlobals();
131
+ const { config } = await loadConfig(root, globalOptions);
132
132
  await serve({
133
133
  config,
134
- ...server,
134
+ host,
135
+ port,
135
136
  });
136
137
  });
137
138
  program.addCommand(newCommand);
@@ -1,5 +1,5 @@
1
- import { type DoomConfig } from '../utils/index.js';
2
- export declare function loadConfig(root?: string, configFile?: string, prefix?: string, version?: string, force?: boolean): Promise<{
1
+ import { type DoomConfig, GlobalCliOptions } from '../utils/index.js';
2
+ export declare function loadConfig(root?: string, { config: configFile, prefix, v: version, ignore, force, }?: GlobalCliOptions): Promise<{
3
3
  config: DoomConfig;
4
4
  filepath?: string;
5
5
  }>;
@@ -19,10 +19,11 @@ const zhLocaleConfig = {
19
19
  prevPageText: '上一页',
20
20
  nextPageText: '下一页',
21
21
  };
22
- const getCommonConfig = (config, cliRoot, configFilePath, version, force) => {
22
+ const getCommonConfig = (config, cliRoot, configFilePath, version, ignore, force) => {
23
23
  const fallbackToZh = 'lang' in config && config.lang == null;
24
24
  const root = resolveDocRoot(CWD, cliRoot, config.root);
25
25
  const localBasePath = configFilePath ? path.dirname(configFilePath) : root;
26
+ const excludeRoutes = (ignore && config.internalRoutes) || [];
26
27
  return {
27
28
  root,
28
29
  lang: fallbackToZh ? 'zh' : config.lang,
@@ -34,6 +35,7 @@ const getCommonConfig = (config, cliRoot, configFilePath, version, force) => {
34
35
  'doom.config.*',
35
36
  '**/assets/**/*',
36
37
  '**/*.d.ts',
38
+ ...excludeRoutes,
37
39
  ],
38
40
  },
39
41
  markdown: {
@@ -61,7 +63,10 @@ const getCommonConfig = (config, cliRoot, configFilePath, version, force) => {
61
63
  ...config.api,
62
64
  localBasePath,
63
65
  }),
64
- autoSidebarPlugin(config.sidebar),
66
+ autoSidebarPlugin({
67
+ ...config.sidebar,
68
+ excludeRoutes,
69
+ }),
65
70
  globalPlugin({
66
71
  sites: config.sites,
67
72
  version,
@@ -110,7 +115,7 @@ const getCommonConfig = (config, cliRoot, configFilePath, version, force) => {
110
115
  const findConfig = (basePath) => {
111
116
  return DEFAULT_EXTENSIONS.map((ext) => basePath + ext).find(fs.existsSync);
112
117
  };
113
- export async function loadConfig(root, configFile, prefix, version, force) {
118
+ export async function loadConfig(root, { config: configFile, prefix, v: version, ignore, force, } = {}) {
114
119
  let configFilePath;
115
120
  if (configFile) {
116
121
  configFilePath = path.resolve(configFile);
@@ -160,7 +165,7 @@ export async function loadConfig(root, configFile, prefix, version, force) {
160
165
  }
161
166
  }
162
167
  const normalizedVersion = normalizeVersion(version);
163
- const commonConfig = getCommonConfig(config, root, configFilePath, normalizedVersion, force);
168
+ const commonConfig = getCommonConfig(config, root, configFilePath, normalizedVersion, ignore, force);
164
169
  const mergedConfig = mergeRsbuildConfig(commonConfig, config, {
165
170
  root: commonConfig.root,
166
171
  });
@@ -1,5 +1,6 @@
1
1
  import { type RspressPlugin } from '@rspress/core';
2
2
  export interface AutoSidebarPluginOptions {
3
+ excludeRoutes?: string[];
3
4
  collapsed?: boolean;
4
5
  }
5
- export declare const autoSidebarPlugin: ({ collapsed, }?: AutoSidebarPluginOptions) => RspressPlugin;
6
+ export declare const autoSidebarPlugin: ({ excludeRoutes, collapsed, }?: AutoSidebarPluginOptions) => RspressPlugin;
@@ -141,21 +141,21 @@ import { walk } from './walk.js';
141
141
  // }
142
142
  // ]
143
143
  // ```
144
- function processLocales(langs, versions, root, defaultLang, defaultVersion, extensions, collapsed) {
144
+ function processLocales(langs, versions, root, defaultLang, defaultVersion, extensions, excludeRoutes, collapsed) {
145
145
  return Promise.all(langs.map(async (lang) => {
146
146
  const walks = versions.length
147
147
  ? await Promise.all(versions.map((version) => {
148
148
  const routePrefix = addTrailingSlash(`${version === defaultVersion ? '' : `/${version}`}${lang === defaultLang ? '' : `/${lang}`}`);
149
- return walk(path.join(root, version, lang), routePrefix, root, extensions, collapsed);
149
+ return walk(path.join(root, version, lang), routePrefix, root, extensions, excludeRoutes, collapsed);
150
150
  }))
151
151
  : [
152
- await walk(path.join(root, lang), addTrailingSlash(lang === defaultLang ? '' : `/${lang}`), root, extensions, collapsed),
152
+ await walk(path.join(root, lang), addTrailingSlash(lang === defaultLang ? '' : `/${lang}`), root, extensions, excludeRoutes, collapsed),
153
153
  ];
154
154
  return combineWalkResult(walks, versions);
155
155
  }));
156
156
  }
157
157
  const defaultExtensions = ['.mdx', '.md', '.tsx', '.jsx', '.ts', '.js'];
158
- export const autoSidebarPlugin = ({ collapsed, } = {}) => {
158
+ export const autoSidebarPlugin = ({ excludeRoutes, collapsed, } = {}) => {
159
159
  return {
160
160
  name: 'doom-auto-sidebar',
161
161
  async config(config, utils) {
@@ -163,6 +163,7 @@ export const autoSidebarPlugin = ({ collapsed, } = {}) => {
163
163
  config.themeConfig = config.themeConfig || {};
164
164
  config.themeConfig.locales =
165
165
  config.themeConfig.locales || config.locales || [];
166
+ const root = config.root;
166
167
  const langs = config.themeConfig.locales.map((locale) => locale.lang);
167
168
  const hasLocales = langs.length > 0;
168
169
  const hasLang = Boolean(config.lang);
@@ -171,7 +172,7 @@ export const autoSidebarPlugin = ({ collapsed, } = {}) => {
171
172
  const { default: defaultVersion = '' } = config.multiVersion || {};
172
173
  const { extensions = defaultExtensions } = config.route || {};
173
174
  if (hasLocales) {
174
- const metaInfo = await processLocales(langs, versions, config.root, defaultLang, defaultVersion, extensions, collapsed);
175
+ const metaInfo = await processLocales(langs, versions, root, defaultLang, defaultVersion, extensions, excludeRoutes, collapsed);
175
176
  config.themeConfig.locales = config.themeConfig.locales.map((item, index) => ({
176
177
  ...item,
177
178
  ...metaInfo[index],
@@ -188,9 +189,9 @@ export const autoSidebarPlugin = ({ collapsed, } = {}) => {
188
189
  const walks = versions.length
189
190
  ? await Promise.all(versions.map((version) => {
190
191
  const routePrefix = addTrailingSlash(version === defaultVersion ? '' : `/${version}`);
191
- return walk(path.join(config.root, version), routePrefix, config.root, extensions, collapsed);
192
+ return walk(path.join(root, version), routePrefix, config.root, extensions, excludeRoutes, collapsed);
192
193
  }))
193
- : [await walk(config.root, '/', config.root, extensions, collapsed)];
194
+ : [await walk(root, '/', root, extensions, excludeRoutes, collapsed)];
194
195
  const combined = combineWalkResult(walks, versions);
195
196
  config.themeConfig = { ...config.themeConfig, ...combined };
196
197
  }
@@ -7,11 +7,11 @@ export interface DoomSidebarGroup extends Omit<SidebarGroup, 'items'> {
7
7
  items: DoomSidebar[];
8
8
  weight?: number;
9
9
  }
10
- export declare function scanSideMeta(workDir: string, rootDir: string, docsDir: string, routePrefix: string, extensions: string[], ignoredDirs: string[]): Promise<{
10
+ export declare function scanSideMeta(workDir: string, rootDir: string, docsDir: string, routePrefix: string, extensions: string[], ignoredDirs: string[], excludeRoutes: string[]): Promise<{
11
11
  index?: DoomSidebarItem;
12
12
  others: DoomSidebar[];
13
13
  }>;
14
- export declare function walk(workDir: string, routePrefix: string | undefined, docsDir: string, extensions: string[], collapsed?: boolean): Promise<{
14
+ export declare function walk(workDir: string, routePrefix: string | undefined, docsDir: string, extensions: string[], excludeRoutes?: string[], collapsed?: boolean): Promise<{
15
15
  nav: never[];
16
16
  sidebar: {
17
17
  [x: string]: DoomSidebar[];
@@ -1,7 +1,9 @@
1
+ import path from 'node:path';
1
2
  import { isExternalUrl, removeLeadingSlash, removeTrailingSlash, slash, withBase, } from '@rspress/shared';
2
3
  import fs from '@rspress/shared/fs-extra';
3
4
  import { logger } from '@rspress/shared/logger';
4
- import path from 'node:path';
5
+ import { unset } from 'es-toolkit/compat';
6
+ import picomatch from 'picomatch';
5
7
  import { detectFilePath, extractInfoFromFrontmatter } from './utils.js';
6
8
  const sidebarSorter = (a, b) => {
7
9
  const aWeight = 'weight' in a && a.weight != null ? a.weight : 100;
@@ -9,19 +11,29 @@ const sidebarSorter = (a, b) => {
9
11
  return aWeight - bWeight;
10
12
  };
11
13
  /**
12
- * Split sideMeta into two parts: `index` and `others` and sort `others` by weight
14
+ * 1. Split sideMeta into two parts: `index` and `others` and sort `others` by weight
15
+ * 2. filter out `excludeRoutes`
13
16
  */
14
- const splitSideMeta = (sideMeta, extensions) => {
17
+ const processSideMeta = (sideMeta, extensions, excludeRoutes) => {
15
18
  const result = sideMeta.reduce((acc, curr) => {
16
- let fileParts;
17
- if ('_fileKey' in curr &&
18
- !('items' in curr) &&
19
- !acc.index &&
20
- (fileParts = curr._fileKey?.split('/')) &&
21
- extensions.some((ext) => fileParts.at(-1) === `index${ext}`)) {
19
+ if (!curr) {
20
+ return acc;
21
+ }
22
+ if (!('_fileKey' in curr) || !curr._fileKey || 'items' in curr) {
23
+ acc.others.push(curr);
24
+ return acc;
25
+ }
26
+ const ignored = excludeRoutes.some((glob) => picomatch.isMatch(curr._fileKey, glob));
27
+ let filePart;
28
+ if (!acc.index &&
29
+ (filePart = curr._fileKey.split('/').at(-1)) &&
30
+ extensions.some((ext) => filePart === `index${ext}`)) {
22
31
  acc.index = curr;
32
+ if (ignored) {
33
+ curr.link = '';
34
+ }
23
35
  }
24
- else {
36
+ else if (!ignored) {
25
37
  acc.others.push(curr);
26
38
  }
27
39
  return acc;
@@ -29,7 +41,7 @@ const splitSideMeta = (sideMeta, extensions) => {
29
41
  result.others.sort(sidebarSorter);
30
42
  return result;
31
43
  };
32
- export async function scanSideMeta(workDir, rootDir, docsDir, routePrefix, extensions, ignoredDirs) {
44
+ export async function scanSideMeta(workDir, rootDir, docsDir, routePrefix, extensions, ignoredDirs, excludeRoutes) {
33
45
  if (!(await fs.exists(workDir))) {
34
46
  logger.error('[plugin-auto-sidebar]', `Generate sidebar meta error: ${workDir} not exists`);
35
47
  }
@@ -125,7 +137,7 @@ export async function scanSideMeta(workDir, rootDir, docsDir, routePrefix, exten
125
137
  }
126
138
  if (type === 'dir') {
127
139
  const subDir = path.resolve(workDir, name);
128
- const { index, others: subSidebar } = await scanSideMeta(subDir, rootDir, docsDir, routePrefix, extensions, ['assets']);
140
+ const { index, others: subSidebar } = await scanSideMeta(subDir, rootDir, docsDir, routePrefix, extensions, ['assets'], excludeRoutes);
129
141
  const realPath = await detectFilePath(subDir, extensions);
130
142
  const group = {
131
143
  text: label,
@@ -138,7 +150,15 @@ export async function scanSideMeta(workDir, rootDir, docsDir, routePrefix, exten
138
150
  context,
139
151
  _fileKey: realPath ? path.relative(docsDir, realPath) : '',
140
152
  };
141
- return index ? { ...group, ...index } : group;
153
+ const sidebarItem = index ? { ...group, ...index } : group;
154
+ if (!subSidebar.length) {
155
+ if (index) {
156
+ unset(sidebarItem, 'items');
157
+ return sidebarItem;
158
+ }
159
+ return;
160
+ }
161
+ return sidebarItem;
142
162
  }
143
163
  if (type === 'divider') {
144
164
  return {
@@ -157,12 +177,12 @@ export async function scanSideMeta(workDir, rootDir, docsDir, routePrefix, exten
157
177
  tag,
158
178
  };
159
179
  }));
160
- return splitSideMeta(sidebarFromMeta, extensions);
180
+ return processSideMeta(sidebarFromMeta, extensions, excludeRoutes);
161
181
  }
162
182
  // Start walking from the doc directory, scan the `_meta.json` file in each subdirectory
163
183
  // and generate the nav and sidebar config
164
- export async function walk(workDir, routePrefix = '/', docsDir, extensions, collapsed) {
165
- const { index, others } = await scanSideMeta(workDir, workDir, docsDir, routePrefix, extensions, ['assets', 'public', 'shared']);
184
+ export async function walk(workDir, routePrefix = '/', docsDir, extensions, excludeRoutes = [], collapsed) {
185
+ const { index, others } = await scanSideMeta(workDir, workDir, docsDir, routePrefix, extensions, ['assets', 'public', 'shared'], excludeRoutes);
166
186
  const sidebars = index ? [index, ...others] : others;
167
187
  if (collapsed != null) {
168
188
  for (const sidebarItem of sidebars) {
@@ -175,8 +195,9 @@ export async function walk(workDir, routePrefix = '/', docsDir, extensions, coll
175
195
  const sidebarConfig = {
176
196
  [routePrefix]: sidebars,
177
197
  };
178
- if (removeTrailingSlash(routePrefix)) {
179
- sidebarConfig[removeTrailingSlash(routePrefix)] = sidebars;
198
+ const simpleRoutePrefix = removeTrailingSlash(routePrefix);
199
+ if (simpleRoutePrefix) {
200
+ sidebarConfig[simpleRoutePrefix] = sidebars;
180
201
  }
181
202
  return {
182
203
  nav: [],
@@ -1,5 +1,5 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
2
  export const Callouts = ({ children }) => {
3
- return _jsx("div", { className: "my-4 leading-7 doom-callouts", children: children });
3
+ return _jsx("div", { className: "doom-callouts", children: children });
4
4
  };
5
5
  export default Callouts;
@@ -3,12 +3,20 @@ import type { ApiPluginOptions } from '../plugins/api/types.js';
3
3
  import type { AutoSidebarPluginOptions } from '../plugins/index.js';
4
4
  import type { ReferenceItem, ReleaseNotesOptions } from '../plugins/replace/types.js';
5
5
  import type { DoomSite } from '../shared/index.js';
6
+ export interface GlobalCliOptions {
7
+ config?: string;
8
+ prefix?: string;
9
+ v?: string;
10
+ ignore?: boolean;
11
+ force?: boolean;
12
+ }
6
13
  export interface DoomConfig extends UserConfig {
7
14
  api?: ApiPluginOptions;
8
15
  sites?: DoomSite[];
9
16
  reference?: ReferenceItem[];
10
17
  sidebar?: AutoSidebarPluginOptions;
11
18
  releaseNotes?: ReleaseNotesOptions;
19
+ internalRoutes?: string[];
12
20
  }
13
21
  export type ContentProcessor = {
14
22
  type: 'ejsTemplate';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alauda/doom",
3
- "version": "0.8.2",
3
+ "version": "0.8.3",
4
4
  "type": "module",
5
5
  "description": "Doctor Doom making docs.",
6
6
  "repository": {
@@ -48,6 +48,7 @@
48
48
  "ejs": "^3.1.10",
49
49
  "es-toolkit": "^1.31.0",
50
50
  "openapi-types": "^12.1.3",
51
+ "picomatch": "^4.0.2",
51
52
  "react-markdown": "^8.0.7",
52
53
  "rehype-raw": "^6.1.1",
53
54
  "remark-frontmatter": "^4.0.1",
@@ -68,6 +69,7 @@
68
69
  "@types/eslint__js": "^8.42.3",
69
70
  "@types/fs-extra": "^11.0.4",
70
71
  "@types/node": "^18.19.70",
72
+ "@types/picomatch": "^3.0.1",
71
73
  "@types/react-dom": "^18.3.5",
72
74
  "@types/swagger2openapi": "^7.0.4",
73
75
  "eslint": "^9.17.0",
@@ -64,6 +64,10 @@ td {
64
64
  }
65
65
 
66
66
  .doom-callouts {
67
+ margin-top: 1rem;
68
+ margin-bottom: 1rem;
69
+ line-height: 1.75rem;
70
+
67
71
  > ol {
68
72
  counter-reset: callouts;
69
73
  list-style-type: none;