@alauda/doom 0.2.7 → 0.3.1

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.
Files changed (32) hide show
  1. package/lib/cli/load-config.js +21 -4
  2. package/lib/cli/shiki/index.d.ts +1 -0
  3. package/lib/cli/shiki/index.js +1 -0
  4. package/lib/cli/shiki/transformers/callouts.d.ts +7 -0
  5. package/lib/cli/shiki/transformers/callouts.js +16 -0
  6. package/lib/cli/shiki/transformers/index.d.ts +1 -0
  7. package/lib/cli/shiki/transformers/index.js +1 -0
  8. package/lib/cli/shiki/types.d.ts +14 -0
  9. package/lib/cli/shiki/types.js +1 -0
  10. package/lib/cli/shiki/utils.d.ts +4 -0
  11. package/lib/cli/shiki/utils.js +47 -0
  12. package/lib/plugins/auto-sidebar/walk.js +5 -0
  13. package/lib/plugins/index.d.ts +2 -1
  14. package/lib/plugins/index.js +2 -1
  15. package/lib/plugins/shiki/highlighter.d.ts +5 -0
  16. package/lib/plugins/shiki/highlighter.js +15 -0
  17. package/lib/plugins/shiki/index.d.ts +22 -0
  18. package/lib/plugins/shiki/index.js +61 -0
  19. package/lib/plugins/shiki/rehypePlugin.d.ts +9 -0
  20. package/lib/plugins/shiki/rehypePlugin.js +47 -0
  21. package/lib/plugins/shiki/transformers/callouts.d.ts +6 -0
  22. package/lib/plugins/shiki/transformers/callouts.js +10 -0
  23. package/lib/plugins/shiki/transformers/index.d.ts +2 -0
  24. package/lib/plugins/shiki/transformers/index.js +2 -0
  25. package/lib/plugins/shiki/transformers/line-number.d.ts +7 -0
  26. package/lib/plugins/shiki/transformers/line-number.js +13 -0
  27. package/lib/runtime/components/Callouts.d.ts +6 -0
  28. package/lib/runtime/components/Callouts.js +5 -0
  29. package/lib/runtime/components/index.d.ts +1 -0
  30. package/lib/runtime/components/index.js +1 -0
  31. package/package.json +9 -7
  32. package/styles/global.scss +46 -0
@@ -1,13 +1,14 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
1
3
  import { nodeTypes } from '@mdx-js/mdx';
2
4
  import { addLeadingSlash, addTrailingSlash, removeLeadingSlash, } from '@rspress/core';
3
5
  import { pluginPreview } from '@rspress/plugin-preview';
4
6
  import { logger } from '@rspress/shared/logger';
7
+ import { transformerMetaHighlight, transformerMetaWordHighlight, transformerNotationDiff, transformerNotationErrorLevel, transformerNotationFocus, transformerNotationHighlight, transformerNotationWordHighlight, transformerRemoveNotationEscape, } from '@shikijs/transformers';
5
8
  import getPort from 'get-port';
6
- import fs from 'node:fs';
7
- import path from 'node:path';
8
9
  import rehypeRaw from 'rehype-raw';
9
10
  import { parse } from 'yaml';
10
- import { apiPlugin, autoSidebarPlugin, globalPlugin } from '../plugins/index.js';
11
+ import { apiPlugin, autoSidebarPlugin, createTransformerCallouts, globalPlugin, shikiPlugin, } from '../plugins/index.js';
11
12
  import { pkgResolve } from '../utils/helpers.js';
12
13
  import { CWD, DEFAULT_CONFIG_NAME, DEFAULT_EXTENSIONS, I18N_FILE, YAML_EXTENSIONS, } from './constants.js';
13
14
  const DEFAULT_LOGO = '/logo.svg';
@@ -61,9 +62,25 @@ const getCommonConfig = async (config) => {
61
62
  },
62
63
  defaultRenderMode: 'pure',
63
64
  }),
65
+ apiPlugin(),
64
66
  autoSidebarPlugin(),
65
67
  globalPlugin(),
66
- apiPlugin(),
68
+ shikiPlugin({
69
+ langs: ['dockerfile', 'go', 'jsonc'],
70
+ transformers: [
71
+ // builtin transformers
72
+ transformerMetaHighlight(),
73
+ transformerMetaWordHighlight(),
74
+ transformerNotationDiff(),
75
+ transformerNotationErrorLevel(),
76
+ transformerNotationFocus(),
77
+ transformerNotationHighlight(),
78
+ transformerNotationWordHighlight(),
79
+ transformerRemoveNotationEscape(),
80
+ // custom transformers
81
+ createTransformerCallouts(),
82
+ ],
83
+ }),
67
84
  ],
68
85
  builderConfig: {
69
86
  server: {
@@ -0,0 +1 @@
1
+ export * from './transformers/index.js';
@@ -0,0 +1 @@
1
+ export * from './transformers/index.js';
@@ -0,0 +1,7 @@
1
+ import { PluginShikiOptions } from '@rspress/plugin-shiki';
2
+ import { IRangeTransformerOptions } from '../types.js';
3
+ export interface ITransformerCalloutsOptions extends IRangeTransformerOptions {
4
+ classActivePre?: string;
5
+ classActiveLine?: string;
6
+ }
7
+ export declare const createTransformerCallouts: (options?: ITransformerCalloutsOptions) => Exclude<PluginShikiOptions["transformers"], undefined>[0];
@@ -0,0 +1,16 @@
1
+ import { addClass, checkClass, createRangeTransformer } from '../utils.js';
2
+ export const createTransformerCallouts = (options = {}) => {
3
+ const { classActiveLine = 'callout', classActivePre = 'has-callouts' } = options;
4
+ return {
5
+ name: 'shiki-transformer:callouts',
6
+ preTransformer: createRangeTransformer({
7
+ callout: classActiveLine,
8
+ }, options),
9
+ postTransformer({ code }) {
10
+ if (!checkClass(code, classActiveLine)) {
11
+ return code;
12
+ }
13
+ return addClass(code, classActivePre, 'pre');
14
+ },
15
+ };
16
+ };
@@ -0,0 +1 @@
1
+ export * from './callouts.js';
@@ -0,0 +1 @@
1
+ export * from './callouts.js';
@@ -0,0 +1,14 @@
1
+ import type { HtmlRendererOptions } from 'shiki';
2
+ export type TLineOptions = NonNullable<HtmlRendererOptions['lineOptions']>;
3
+ export interface ITransformerResult {
4
+ code: string;
5
+ lineOptions: TLineOptions;
6
+ }
7
+ export interface ITransformerOptions {
8
+ code: string;
9
+ lang: string;
10
+ }
11
+ export type TPreTransformer = (options: ITransformerOptions) => ITransformerResult;
12
+ export interface IRangeTransformerOptions {
13
+ tagRegExp?: RegExp;
14
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,4 @@
1
+ import type { IRangeTransformerOptions, TPreTransformer } from './types.js';
2
+ export declare function createRangeTransformer(classMap: Record<string, string | string[]>, options?: IRangeTransformerOptions): TPreTransformer;
3
+ export declare const checkClass: (code: string, className: string | string[]) => boolean;
4
+ export declare function addClass(code: string, classes: string | string[], tag?: string): string;
@@ -0,0 +1,47 @@
1
+ export function createRangeTransformer(classMap, options = {}) {
2
+ return ({ code }) => {
3
+ // https://regex101.com/r/mUxvfx/1
4
+ const tagRE = options.tagRegExp ??
5
+ /(?:#|\/\/|\/\*{1,2}) *\[!code ([\w+-]+)(?::(\d+))?] *(?:\*{1,2}\/)?/;
6
+ const lineOptions = [];
7
+ const tags = Object.keys(classMap);
8
+ const codeFormat = code
9
+ .split('\n')
10
+ .map((lineOfCode, lineNumber) => {
11
+ const [match, tag, range] = lineOfCode.match(tagRE) ?? [];
12
+ if (!match) {
13
+ return lineOfCode;
14
+ }
15
+ if (!tags.includes(tag)) {
16
+ return lineOfCode;
17
+ }
18
+ for (const [rangeOffset] of Array.from({
19
+ length: Number(range ?? 1),
20
+ }).entries()) {
21
+ lineOptions.push({
22
+ line: lineNumber + rangeOffset + 1,
23
+ classes: typeof classMap[tag] === 'string'
24
+ ? [classMap[tag]]
25
+ : classMap[tag],
26
+ });
27
+ }
28
+ return lineOfCode.replace(tagRE, '');
29
+ })
30
+ .join('\n');
31
+ return {
32
+ code: codeFormat,
33
+ lineOptions,
34
+ };
35
+ };
36
+ }
37
+ export const checkClass = (code, className) => {
38
+ const classes = Array.isArray(className) ? className.join(' ') : className;
39
+ return code.search(classes) !== -1;
40
+ };
41
+ export function addClass(code, classes, tag) {
42
+ const classRE = new RegExp(`<${tag ?? 'w+'}[^>]*class="([\\w+-:;\\/* ]*)"`);
43
+ classes = Array.isArray(classes) ? classes : [classes];
44
+ return code.replace(classRE, (match, previousClasses) => {
45
+ return match.replace(previousClasses, `${previousClasses} ${classes.join(' ')}`.trim());
46
+ });
47
+ }
@@ -187,6 +187,11 @@ export async function walk(workDir, routePrefix = '/', docsDir, extensions) {
187
187
  });
188
188
  const { index, others } = await scanSideMeta(workDir, workDir, docsDir, routePrefix, extensions, ['assets', 'public', 'shared']);
189
189
  const sidebars = index ? [index, ...others] : others;
190
+ for (const sidebarItem of sidebars) {
191
+ if ('items' in sidebarItem && sidebarItem.items.length) {
192
+ sidebarItem.collapsed = false;
193
+ }
194
+ }
190
195
  // Every sub dir will represent a group of sidebar
191
196
  const sidebarConfig = {
192
197
  [routePrefix]: sidebars,
@@ -1,3 +1,4 @@
1
+ export * from './api/index.js';
1
2
  export * from './auto-sidebar/index.js';
2
3
  export * from './global/index.js';
3
- export * from './api/index.js';
4
+ export * from './shiki/index.js';
@@ -1,3 +1,4 @@
1
+ export * from './api/index.js';
1
2
  export * from './auto-sidebar/index.js';
2
3
  export * from './global/index.js';
3
- export * from './api/index.js';
4
+ export * from './shiki/index.js';
@@ -0,0 +1,5 @@
1
+ import { type BuiltinLanguage, type BuiltinTheme, type Highlighter, type BundledHighlighterOptions as ShikiHighlighterOptions, type ShikiTransformer } from 'shiki';
2
+ export interface HighlighterOptions extends ShikiHighlighterOptions<BuiltinLanguage, BuiltinTheme> {
3
+ transformers?: ShikiTransformer[];
4
+ }
5
+ export declare function getHighlighter(options: HighlighterOptions): Promise<Highlighter>;
@@ -0,0 +1,15 @@
1
+ import { createHighlighter as createShikiHighlighter, } from 'shiki';
2
+ export async function getHighlighter(options) {
3
+ const highlighter = await createShikiHighlighter(options);
4
+ const baseTransformers = options.transformers ?? [];
5
+ return {
6
+ ...highlighter,
7
+ codeToHtml: (code, htmlOptions) => {
8
+ const transformers = htmlOptions.transformers ?? [];
9
+ return highlighter.codeToHtml(code, {
10
+ ...htmlOptions,
11
+ transformers: [...baseTransformers, ...transformers],
12
+ });
13
+ },
14
+ };
15
+ }
@@ -0,0 +1,22 @@
1
+ import type { RspressPlugin } from '@rspress/shared';
2
+ import { type BuiltinLanguage, type BuiltinTheme, type ShikiTransformer, type SpecialLanguage } from 'shiki';
3
+ export interface PluginShikiOptions {
4
+ /**
5
+ * Code highlighting theme, @see https://shiki.style/themes
6
+ */
7
+ theme?: BuiltinTheme | 'css-variables';
8
+ /**
9
+ * Code highlighting language, @see https://shiki.style/languages
10
+ */
11
+ langs?: Array<BuiltinLanguage | SpecialLanguage>;
12
+ /**
13
+ * Custom shiki transformer, @see https://shiki.style/guide/transformers
14
+ */
15
+ transformers?: ShikiTransformer[];
16
+ }
17
+ export declare const SHIKI_DEFAULT_HIGHLIGHT_LANGUAGES: BuiltinLanguage[];
18
+ /**
19
+ * The plugin is used to add the last updated time to the page.
20
+ */
21
+ export declare function shikiPlugin({ theme, langs, transformers, }?: PluginShikiOptions): RspressPlugin;
22
+ export * from './transformers/index.js';
@@ -0,0 +1,61 @@
1
+ import { dirname, join } from 'node:path';
2
+ import { fileURLToPath } from 'node:url';
3
+ import { createCssVariablesTheme, } from 'shiki';
4
+ import { rehypePluginShiki } from './rehypePlugin.js';
5
+ import { SHIKI_TRANSFORMER_LINE_NUMBER, createTransformerLineNumber, } from './transformers/line-number.js';
6
+ import { getHighlighter } from './highlighter.js';
7
+ const __filename = fileURLToPath(import.meta.url);
8
+ const __dirname = dirname(__filename);
9
+ export const SHIKI_DEFAULT_HIGHLIGHT_LANGUAGES = [
10
+ 'js',
11
+ 'ts',
12
+ 'jsx',
13
+ 'tsx',
14
+ 'json',
15
+ 'css',
16
+ 'scss',
17
+ 'less',
18
+ 'xml',
19
+ 'diff',
20
+ 'yaml',
21
+ 'md',
22
+ 'mdx',
23
+ 'bash',
24
+ ];
25
+ const cssVariablesTheme = createCssVariablesTheme({
26
+ name: 'css-variables',
27
+ variablePrefix: '--shiki-',
28
+ variableDefaults: {},
29
+ fontStyle: true,
30
+ });
31
+ /**
32
+ * The plugin is used to add the last updated time to the page.
33
+ */
34
+ export function shikiPlugin({ theme = 'css-variables', langs = [], transformers = [], } = {}) {
35
+ return {
36
+ name: 'doom-shiki',
37
+ async config(config) {
38
+ config.markdown = config.markdown || {};
39
+ // Shiki will be integrated by rehype plugin, so we should use the javascript version markdown compiler.
40
+ config.markdown.mdxRs = false;
41
+ config.markdown.codeHighlighter = 'shiki';
42
+ config.markdown.rehypePlugins = config.markdown.rehypePlugins || [];
43
+ if (config.markdown.showLineNumbers &&
44
+ !transformers.some((transformerItem) => transformerItem.name === SHIKI_TRANSFORMER_LINE_NUMBER)) {
45
+ transformers.push(createTransformerLineNumber());
46
+ }
47
+ const highlighter = await getHighlighter({
48
+ themes: [cssVariablesTheme],
49
+ langs: [...SHIKI_DEFAULT_HIGHLIGHT_LANGUAGES, ...langs],
50
+ transformers,
51
+ });
52
+ config.markdown.rehypePlugins.push([
53
+ rehypePluginShiki,
54
+ { highlighter, theme },
55
+ ]);
56
+ return config;
57
+ },
58
+ globalStyles: join(__dirname, './shiki.css'),
59
+ };
60
+ }
61
+ export * from './transformers/index.js';
@@ -0,0 +1,9 @@
1
+ import type { Plugin } from 'unified';
2
+ import type { Root } from 'hast';
3
+ import type { BuiltinTheme, Highlighter } from 'shiki';
4
+ interface Options {
5
+ highlighter: Highlighter;
6
+ theme: BuiltinTheme;
7
+ }
8
+ export declare const rehypePluginShiki: Plugin<[Options], Root>;
9
+ export {};
@@ -0,0 +1,47 @@
1
+ import { visit } from 'unist-util-visit';
2
+ import { fromHtml } from 'hast-util-from-html';
3
+ // TODO: migrate to official @shikijs/rehype plugin after upgrading unified/remark/rehype packages
4
+ export const rehypePluginShiki = ({ highlighter, theme }) => (tree) => {
5
+ visit(tree, 'element', (node, index, parent) => {
6
+ // <pre><code>...</code></pre>
7
+ if (node.tagName === 'pre' &&
8
+ node.children[0]?.type === 'element' &&
9
+ node.children[0].tagName === 'code') {
10
+ const codeNode = node.children[0];
11
+ const codeContent = codeNode.children[0].value;
12
+ const codeClassName = codeNode.properties?.className?.toString() || '';
13
+ const codeMeta = codeNode.properties?.meta?.toString() || '';
14
+ // for example: language-js {1,2,3-5}
15
+ const lang = codeClassName.split(' ')[0].split('-')[1];
16
+ if (!lang) {
17
+ return;
18
+ }
19
+ const highlightedCode = highlighter.codeToHtml(codeContent, {
20
+ lang,
21
+ theme,
22
+ meta: {
23
+ __raw: codeMeta,
24
+ },
25
+ });
26
+ const fragmentAst = fromHtml(highlightedCode, { fragment: true });
27
+ const preElement = fragmentAst.children[0];
28
+ const codeElement = preElement.children[0];
29
+ codeElement.properties.className = `language-${lang}`;
30
+ codeElement.properties.meta = codeMeta;
31
+ const codeLines = codeElement.children;
32
+ // Strip the final empty span
33
+ const lastLine = codeLines[codeLines.length - 1];
34
+ if (lastLine.children.length === 0) {
35
+ codeLines.pop();
36
+ }
37
+ parent?.children.splice(index, 1, {
38
+ type: 'element',
39
+ tagName: 'pre',
40
+ properties: {
41
+ className: 'code',
42
+ },
43
+ children: fragmentAst.children,
44
+ });
45
+ }
46
+ });
47
+ };
@@ -0,0 +1,6 @@
1
+ import type { ShikiTransformer } from 'shiki';
2
+ export interface ITransformerCalloutsOptions {
3
+ classActivePre?: string;
4
+ classActiveLine?: string;
5
+ }
6
+ export declare const createTransformerCallouts: (options?: ITransformerCalloutsOptions) => ShikiTransformer;
@@ -0,0 +1,10 @@
1
+ import { transformerNotationMap } from '@shikijs/transformers';
2
+ export const createTransformerCallouts = (options = {}) => {
3
+ const { classActiveLine = 'callout', classActivePre = 'has-callouts' } = options;
4
+ return transformerNotationMap({
5
+ classMap: {
6
+ callout: classActiveLine,
7
+ },
8
+ classActivePre,
9
+ }, 'shiki-transformer:callouts');
10
+ };
@@ -0,0 +1,2 @@
1
+ export * from './callouts.js';
2
+ export * from './line-number.js';
@@ -0,0 +1,2 @@
1
+ export * from './callouts.js';
2
+ export * from './line-number.js';
@@ -0,0 +1,7 @@
1
+ import type { ShikiTransformer } from 'shiki';
2
+ export interface ITransformerLineNumberOptions {
3
+ classActivePre?: string;
4
+ classActiveLine?: string;
5
+ }
6
+ export declare const SHIKI_TRANSFORMER_LINE_NUMBER = "shiki-transformer:line-number";
7
+ export declare function createTransformerLineNumber(options?: ITransformerLineNumberOptions): ShikiTransformer;
@@ -0,0 +1,13 @@
1
+ export const SHIKI_TRANSFORMER_LINE_NUMBER = 'shiki-transformer:line-number';
2
+ export function createTransformerLineNumber(options = {}) {
3
+ const { classActiveLine = 'line-number', classActivePre = 'has-line-number', } = options;
4
+ return {
5
+ name: SHIKI_TRANSFORMER_LINE_NUMBER,
6
+ pre(pre) {
7
+ return this.addClassToHast(pre, classActivePre);
8
+ },
9
+ line(node) {
10
+ this.addClassToHast(node, classActiveLine);
11
+ },
12
+ };
13
+ }
@@ -0,0 +1,6 @@
1
+ import { ReactNode } from 'react';
2
+ export interface CalloutsProps {
3
+ children: ReactNode;
4
+ }
5
+ export declare const Callouts: ({ children }: CalloutsProps) => import("react/jsx-runtime").JSX.Element;
6
+ export default Callouts;
@@ -0,0 +1,5 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ export const Callouts = ({ children }) => {
3
+ return _jsx("p", { className: "my-4 leading-7 doom-callouts", children: children });
4
+ };
5
+ export default Callouts;
@@ -1,3 +1,4 @@
1
+ export * from './Callouts.js';
1
2
  export * from './K8sCrd.js';
2
3
  export * from './Overview.js';
3
4
  export * from './QuickNav.js';
@@ -1,3 +1,4 @@
1
+ export * from './Callouts.js';
1
2
  export * from './K8sCrd.js';
2
3
  export * from './Overview.js';
3
4
  export * from './QuickNav.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alauda/doom",
3
- "version": "0.2.7",
3
+ "version": "0.3.1",
4
4
  "type": "module",
5
5
  "description": "Doctor Doom making docs.",
6
6
  "repository": {
@@ -38,31 +38,33 @@
38
38
  },
39
39
  "dependencies": {
40
40
  "@openapi-contrib/openapi-schema-to-json-schema": "^5.1.0",
41
- "@rspress/core": "^1.37.4",
42
- "@rspress/plugin-preview": "^1.37.4",
41
+ "@rspress/core": "^1.38.0",
42
+ "@rspress/plugin-preview": "^1.38.0",
43
+ "@shikijs/transformers": "^1.24.2",
43
44
  "chokidar": "^4.0.1",
44
45
  "clsx": "^2.1.1",
45
46
  "commander": "^12.1.0",
46
- "es-toolkit": "^1.29.0",
47
+ "es-toolkit": "^1.30.1",
47
48
  "get-port": "^7.1.0",
48
49
  "react-markdown": "^8.0.7",
49
50
  "rehype-raw": "^6.1.1",
50
51
  "remark-gfm": "^3.0.1",
52
+ "shiki": "^1.24.2",
51
53
  "swagger2openapi": "^7.0.8",
52
54
  "tinyglobby": "^0.2.10",
53
55
  "yaml": "^2.6.1",
54
56
  "yoctocolors": "^2.1.1"
55
57
  },
56
58
  "devDependencies": {
57
- "@eslint/js": "^9.16.0",
59
+ "@eslint/js": "^9.17.0",
58
60
  "@swc-node/register": "^1.10.9",
59
61
  "@swc/core": "1.10.1",
60
62
  "@types/eslint__js": "^8.42.3",
61
63
  "@types/fs-extra": "^11.0.4",
62
64
  "@types/node": "~18.17.19",
63
65
  "@types/swagger2openapi": "^7.0.4",
64
- "eslint": "^9.16.0",
65
- "lint-staged": "^15.2.10",
66
+ "eslint": "^9.17.0",
67
+ "lint-staged": "^15.2.11",
66
68
  "npm-run-all2": "^7.0.1",
67
69
  "openapi-types": "^12.1.3",
68
70
  "prettier": "^3.4.2",
@@ -37,3 +37,49 @@ td {
37
37
  }
38
38
  }
39
39
  }
40
+
41
+ @mixin callout {
42
+ counter-increment: callouts;
43
+ content: counter(callouts);
44
+ border-radius: 50%;
45
+ background-color: #06c;
46
+ color: #fff;
47
+ width: 20px;
48
+ height: 20px;
49
+ display: inline-flex;
50
+ justify-content: center;
51
+ align-items: center;
52
+ }
53
+
54
+ .has-callouts .rspress-code-content {
55
+ counter-reset: callouts;
56
+
57
+ .line.callout {
58
+ &:after {
59
+ @include callout;
60
+ }
61
+ }
62
+ }
63
+
64
+ .doom-callouts {
65
+ > ol {
66
+ counter-reset: callouts;
67
+ list-style-type: none;
68
+
69
+ > li {
70
+ margin-left: -1.25rem;
71
+
72
+ &:before {
73
+ @include callout;
74
+ margin-right: 0.75rem;
75
+ }
76
+
77
+ > {
78
+ ul,
79
+ ol {
80
+ margin-left: 1.25rem;
81
+ }
82
+ }
83
+ }
84
+ }
85
+ }