From f6b7fb30a823d325b4d7aeb2f1b44958bd4c3db7 Mon Sep 17 00:00:00 2001 From: dopamine Date: Mon, 15 Jul 2024 18:30:10 +0800 Subject: [PATCH] refactor(docs): upgrade vitepress (#17444) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: upgrade vitepress * revert original copy button --------- Co-authored-by: 云游君 --- .gitignore | 1 + .../{config.mts => config/index.mts} | 14 +- docs/.vitepress/config/index.ts | 7 - docs/.vitepress/config/plugins.ts | 11 +- docs/.vitepress/plugins/api-table.ts | 5 - docs/.vitepress/plugins/headers.ts | 24 + docs/.vitepress/plugins/markdown-transform.ts | 2 +- docs/.vitepress/plugins/tag.ts | 28 +- docs/.vitepress/theme/style.css | 3 + docs/.vitepress/utils/highlight.ts | 56 - .../vitepress/components/common/vp-link.vue | 12 +- .../components/demo/vp-source-code.vue | 8 +- .../doc-content/vp-table-of-content.vue | 7 +- .../components/navbar/vp-menu-link.vue | 6 +- .../components/sidebar/vp-sidebar-link.vue | 4 +- .../vitepress/components/vp-app.vue | 1 - .../vitepress/composables/page-nav.ts | 16 +- .../vitepress/composables/sidebar.ts | 15 +- docs/.vitepress/vitepress/styles/code.scss | 370 +- docs/.vitepress/vitepress/utils/index.ts | 35 +- docs/components.d.ts | 2 - docs/package.json | 7 +- docs/unocss.config.ts | 5 +- docs/vite.config.ts | 3 + internal/build-constants/package.json | 9 +- internal/build-utils/package.json | 9 +- pnpm-lock.yaml | 4226 ++++++++++++----- 27 files changed, 3301 insertions(+), 1585 deletions(-) rename docs/.vitepress/{config.mts => config/index.mts} (86%) delete mode 100644 docs/.vitepress/config/index.ts create mode 100644 docs/.vitepress/plugins/headers.ts delete mode 100644 docs/.vitepress/utils/highlight.ts diff --git a/.gitignore b/.gitignore index c720febdf0..8720c7bf73 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ packages/element-plus/version.ts cypress/screenshots/* cypress/videos/* tmp +docs/.vitepress/cache diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config/index.mts similarity index 86% rename from docs/.vitepress/config.mts rename to docs/.vitepress/config/index.mts index e1b9693920..88c42378c2 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config/index.mts @@ -1,8 +1,13 @@ import consola from 'consola' import { REPO_BRANCH, REPO_PATH } from '@element-plus/build-constants' import { docsDirName } from '@element-plus/build-utils' -import { languages } from './utils/lang' -import { features, head, mdPlugin, nav, sidebars } from './config' +import { languages } from '../utils/lang' +import { features } from './features' +import { head } from './head' +import { nav } from './nav' +import { mdPlugin } from './plugins' +import { sidebars } from './sidebars' + import type { UserConfig } from 'vitepress' const buildTransformers = () => { @@ -41,7 +46,7 @@ languages.forEach((lang) => { } }) -export const config: UserConfig = { +const config: UserConfig = { title: 'Element Plus', description: 'A Vue 3 based component library for designers and developers', lastUpdated: true, @@ -53,7 +58,6 @@ export const config: UserConfig = { editLinks: true, editLinkText: 'Edit this page on GitHub', - lastUpdated: 'Last Updated', logo: '/images/element-plus-logo.svg', logoSmall: '/images/element-plus-logo-small.svg', @@ -75,12 +79,10 @@ export const config: UserConfig = { vue: { template: { - ssr: true, compilerOptions: { directiveTransforms: buildTransformers(), }, }, }, } - export default config diff --git a/docs/.vitepress/config/index.ts b/docs/.vitepress/config/index.ts deleted file mode 100644 index ff1b2f98a5..0000000000 --- a/docs/.vitepress/config/index.ts +++ /dev/null @@ -1,7 +0,0 @@ -export * from './analytics' -export * from './features' -export * from './head' -export * from './nav' -export * from './plugins' -export * from './sidebars' -export * from './sponsors' diff --git a/docs/.vitepress/config/plugins.ts b/docs/.vitepress/config/plugins.ts index e32acc2e89..00272394e9 100644 --- a/docs/.vitepress/config/plugins.ts +++ b/docs/.vitepress/config/plugins.ts @@ -1,18 +1,16 @@ import path from 'path' import fs from 'fs' -import MarkdownIt from 'markdown-it' import mdContainer from 'markdown-it-container' import { docRoot } from '@element-plus/build-utils' import externalLinkIcon from '../plugins/external-link-icon' import tableWrapper from '../plugins/table-wrapper' import tooltip from '../plugins/tooltip' import tag from '../plugins/tag' +import headers from '../plugins/headers' import { ApiTableContainer } from '../plugins/api-table' -import { highlight } from '../utils/highlight' import type Token from 'markdown-it/lib/token' import type Renderer from 'markdown-it/lib/renderer' - -const localMd = MarkdownIt().use(tag) +import type MarkdownIt from 'markdown-it' interface ContainerOpts { marker?: string | undefined @@ -27,6 +25,7 @@ interface ContainerOpts { } export const mdPlugin = (md: MarkdownIt) => { + md.use(headers) md.use(externalLinkIcon) md.use(tableWrapper) md.use(tooltip) @@ -53,10 +52,10 @@ export const mdPlugin = (md: MarkdownIt) => { if (!source) throw new Error(`Incorrect source file: ${sourceFile}`) return `` + )}" description="${encodeURIComponent(md.render(description))}">` } else { return '' } diff --git a/docs/.vitepress/plugins/api-table.ts b/docs/.vitepress/plugins/api-table.ts index 0a31ffacf3..d9ff7b526b 100644 --- a/docs/.vitepress/plugins/api-table.ts +++ b/docs/.vitepress/plugins/api-table.ts @@ -1,13 +1,8 @@ -import markdown from 'markdown-it' - import type MarkdownIt from 'markdown-it' -const ApiMd = new markdown() - export const ApiTableContainer = (md: MarkdownIt) => { const fence = md.renderer.rules.fence! - ApiMd.renderer.rules = md.renderer.rules md.renderer.rules.fence = (...args) => { const [tokens, idx, ...rest] = args const [options, env] = rest diff --git a/docs/.vitepress/plugins/headers.ts b/docs/.vitepress/plugins/headers.ts new file mode 100644 index 0000000000..49239a61b5 --- /dev/null +++ b/docs/.vitepress/plugins/headers.ts @@ -0,0 +1,24 @@ +import { resolveHeadersFromTokens, slugify } from '@mdit-vue/shared' +import type MarkdownIt from 'markdown-it' + +/** + * Get markdown headers info + * + * Extract them into env + */ +export default (md: MarkdownIt): void => { + // extract headers to env + const render = md.renderer.render.bind(md.renderer) + + const level = [2, 3, 4, 5, 6] + md.renderer.render = (tokens, options, env) => { + env.headers = resolveHeadersFromTokens(tokens, { + level, + shouldAllowHtml: true, + shouldAllowNested: false, + shouldEscapeText: false, + slugify, + }) + return render(tokens, options, env) + } +} diff --git a/docs/.vitepress/plugins/markdown-transform.ts b/docs/.vitepress/plugins/markdown-transform.ts index 5132e7bf69..21bf63064d 100644 --- a/docs/.vitepress/plugins/markdown-transform.ts +++ b/docs/.vitepress/plugins/markdown-transform.ts @@ -36,7 +36,7 @@ export function MarkdownTransform(): Plugin { headers: [], footers: [], scriptSetups: [ - `const demos = import.meta.globEager('../../examples/${componentId}/*.vue')`, + `const demos = import.meta.glob('../../examples/${componentId}/*.vue', { eager: true })`, ], } diff --git a/docs/.vitepress/plugins/tag.ts b/docs/.vitepress/plugins/tag.ts index 06f538efe6..881ddc5107 100644 --- a/docs/.vitepress/plugins/tag.ts +++ b/docs/.vitepress/plugins/tag.ts @@ -1,22 +1,6 @@ import type MarkdownIt from 'markdown-it' export default (md: MarkdownIt): void => { - /** - * To enable the plugin to be parsed in the demo description, the content is rendered as span instead of ElTag. - */ - md.renderer.rules.tag = (tokens, idx) => { - const token = tokens[idx] - const value = token.content - /** - * Add styles for some special tags - * vitepress/styles/content/tag-content.scss - */ - const tagClass = ['beta', 'deprecated', 'a11y', 'required'].includes(value) - ? value - : '' - return `${value}` - } - md.inline.ruler.before('emphasis', 'tag', (state, silent) => { const tagRegExp = /^\^\(([^)]*)\)/ const str = state.src.slice(state.pos, state.posMax) @@ -28,8 +12,16 @@ export default (md: MarkdownIt): void => { if (!result) return false - const token = state.push('tag', 'tag', 0) - token.content = result[1].trim() + const token = state.push('html_inline', '', 0) + const value = result[1].trim() + /** + * Add styles for some special tags + * vitepress/styles/content/tag-content.scss + */ + const tagClass = ['beta', 'deprecated', 'a11y', 'required'].includes(value) + ? value + : '' + token.content = `${value}` token.level = state.level state.pos += result[0].length diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css index 8d69b96394..eec48cadc8 100644 --- a/docs/.vitepress/theme/style.css +++ b/docs/.vitepress/theme/style.css @@ -64,3 +64,6 @@ transform: rotate(1turn); } } +.doc-content .header-anchor:before { + content: '#'; +} diff --git a/docs/.vitepress/utils/highlight.ts b/docs/.vitepress/utils/highlight.ts deleted file mode 100644 index a07ddc14f0..0000000000 --- a/docs/.vitepress/utils/highlight.ts +++ /dev/null @@ -1,56 +0,0 @@ -// ref https://github.com/vuejs/vitepress/blob/main/src/node/markdown/plugins/highlight.ts -import chalk from 'chalk' -import escapeHtml from 'escape-html' -import prism from 'prismjs' -import consola from 'consola' - -// prism is listed as actual dep so it's ok to require -// eslint-disable-next-line @typescript-eslint/no-var-requires -const loadLanguages = require('prismjs/components/index') - -// required to make embedded highlighting work... -loadLanguages(['markup', 'css', 'javascript']) - -function wrap(code: string, lang: string): string { - if (lang === 'text') { - code = escapeHtml(code) - } - return `
${code}
` -} - -export const highlight = (str: string, lang: string) => { - if (!lang) { - return wrap(str, 'text') - } - lang = lang.toLowerCase() - const rawLang = lang - if (lang === 'vue' || lang === 'html') { - lang = 'markup' - } - if (lang === 'md') { - lang = 'markdown' - } - if (lang === 'ts') { - lang = 'typescript' - } - if (lang === 'py') { - lang = 'python' - } - if (!prism.languages[lang]) { - try { - loadLanguages([lang]) - } catch { - // eslint-disable-next-line no-console - consola.warn( - chalk.yellow( - `[vitepress] Syntax highlight for language "${lang}" is not supported.` - ) - ) - } - } - if (prism.languages[lang]) { - const code = prism.highlight(str, prism.languages[lang], lang) - return wrap(code, rawLang) - } - return wrap(str, 'text') -} diff --git a/docs/.vitepress/vitepress/components/common/vp-link.vue b/docs/.vitepress/vitepress/components/common/vp-link.vue index ac21a04ef4..c40d3f43d4 100644 --- a/docs/.vitepress/vitepress/components/common/vp-link.vue +++ b/docs/.vitepress/vitepress/components/common/vp-link.vue @@ -1,12 +1,10 @@