From 7c507b7090564b56b64cd7be799ecb312b7c1ba6 Mon Sep 17 00:00:00 2001 From: Kia King Ishii Date: Thu, 26 May 2022 01:17:07 +0900 Subject: [PATCH] feat: add docs, styles, and such --- docs/config/app-configs.md | 50 +++++++++++++++++++ docs/guide/api.md | 2 +- docs/guide/markdown-extensions.md | 30 +++++------ .../styles/components/vp-doc.css | 26 +++++----- src/client/theme-default/styles/vars.css | 6 +++ src/node/markdown/plugins/highlight.ts | 5 +- 6 files changed, 88 insertions(+), 31 deletions(-) diff --git a/docs/config/app-configs.md b/docs/config/app-configs.md index 51632242..b1cf0d8f 100644 --- a/docs/config/app-configs.md +++ b/docs/config/app-configs.md @@ -81,6 +81,56 @@ export default { } ``` +## markdown + +- Type: `MarkdownOption` + +Configre Markdown parser options. VitePress uses [Markdown-it](https://github.com/markdown-it/markdown-it) as the parser, and [Shiki](https://shiki.matsu.io/) to highlight language syntax. Inside this option, you may pass various Markdown related options to fit your needs. + +```js +export default { + markdown: { + theme: 'material-palenight', + lineNumbers: true + } +} +``` + +Below shows the the full option you may define within this object. + +```ts +interface MarkdownOptions extends MarkdownIt.Options { + // Syntax highlight theme for Shiki. + // See: https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes + theme?: Shiki.Theme + + // Enable line numbers in code block. + lineNumbers?: boolean + + // markdown-it-anchor plugin options. + // See: https://github.com/valeriangalliat/markdown-it-anchor + anchor?: { + permalink?: anchor.AnchorOptions['permalink'] + } + + // markdown-it-attrs plugin options. + // See: https://github.com/arve0/markdown-it-attrs + attrs?: { + leftDelimiter?: string + rightDelimiter?: string + allowedAttributes?: string[] + } + + // markdown-it-table-of-contents cplugin options + // https://github.com/Oktavilla/markdown-it-table-of-contents + toc?: any + + // Configure the Markdown-it instance to fully customize + // how it works. + config?: (md: MarkdownIt) => void +} +``` + ## appearance - Type: `boolean` diff --git a/docs/guide/api.md b/docs/guide/api.md index a2d2f5f5..28eeb0c0 100644 --- a/docs/guide/api.md +++ b/docs/guide/api.md @@ -16,9 +16,9 @@ interface VitePressData { page: Ref theme: Ref // themeConfig from .vitepress/config.js frontmatter: Ref + lang: Ref title: Ref description: Ref - lang: Ref localePath: Ref } ``` diff --git a/docs/guide/markdown-extensions.md b/docs/guide/markdown-extensions.md index a566881c..0e10ba20 100644 --- a/docs/guide/markdown-extensions.md +++ b/docs/guide/markdown-extensions.md @@ -211,17 +211,6 @@ export default { ``` ```` -**Output** - -```js -export default { - name: 'MyComponent' - // ... -} -``` - -**Input** - ```` ```html
    @@ -234,14 +223,25 @@ export default { **Output** +```js +export default { + name: 'MyComponent' + // ... +} +``` + ```html
      -
    • {{ todo.text }}
      • +
    • + {{ todo.text }} +
    ``` A [list of valid languages](https://github.com/shikijs/shiki/blob/main/docs/languages.md) is available on Shiki’s repository. +You may also customize syntax highlight theme in app config. Please see [`markdown` options](../config/app-configs#markdown) for more details. + ## Line Highlighting in Code Blocks **Input** @@ -287,7 +287,7 @@ export default { // Highlighted This line isn't highlighted, but this and the next 2 are.`, motd: 'VitePress is awesome', - lorem: 'ipsum', + lorem: 'ipsum' } } } @@ -315,13 +315,15 @@ export default { // Highlighted You can enable line numbers for each code blocks via config: ```js -module.exports = { +export default { markdown: { lineNumbers: true } } ``` +Please see [`markdown` options](../config/app-configs#markdown) for more details. + ## Import Code Snippets You can import code snippets from existing files via following syntax: diff --git a/src/client/theme-default/styles/components/vp-doc.css b/src/client/theme-default/styles/components/vp-doc.css index 23bf73e3..c0dc4afd 100644 --- a/src/client/theme-default/styles/components/vp-doc.css +++ b/src/client/theme-default/styles/components/vp-doc.css @@ -303,7 +303,7 @@ position: relative; z-index: 1; margin: 0; - padding: 14px 24px; + padding: 16px 24px; background: transparent; overflow-x: auto; } @@ -322,49 +322,49 @@ top: 0; bottom: 0; left: 0; - padding: 13px 0 11px; + padding-top: 16px; width: 100%; - font-family: var(--vp-font-family-mono); line-height: var(--vp-code-line-height); + font-family: var(--vp-font-family-mono); font-size: var(--vp-code-font-size); user-select: none; overflow: hidden; } .vp-doc .highlight-lines .highlighted { - background-color: rgba(0, 0, 0, 0.3); + background-color: var(--vp-code-line-highlight-color); transition: background-color 0.5s; } -.dark .vp-doc .highlight-lines .highlighted { - background-color: rgba(255, 255, 255, 0.05); -} - .vp-doc div[class*='language-'].line-numbers-mode { padding-left: 32px; } +.vp-doc div[class*='language-'].line-numbers-mode pre { + padding-left: 16px; +} + .vp-doc .line-numbers-wrapper { position: absolute; top: 0; bottom: 0; left: 0; z-index: 3; - border-right: 1px solid var(--vp-c-divider-light); - padding: 13px 0 11px; + border-right: 1px solid var(--vp-c-divider-dark-2); + padding-top: 16px; width: 32px; text-align: center; font-family: var(--vp-font-family-mono); line-height: var(--vp-code-line-height); font-size: var(--vp-code-font-size); - color: var(--vp-c-text-3); + color: var(--vp-code-line-number-color); transition: border-color 0.5s, color 0.5s; } .vp-doc [class*='language-']:before { position: absolute; - top: 4px; - right: 10px; + top: 6px; + right: 12px; z-index: 2; font-size: 12px; font-weight: 500; diff --git a/src/client/theme-default/styles/vars.css b/src/client/theme-default/styles/vars.css index f2dd9530..706e7453 100644 --- a/src/client/theme-default/styles/vars.css +++ b/src/client/theme-default/styles/vars.css @@ -187,10 +187,16 @@ --vp-code-block-color: var(--vp-c-text-dark-1); --vp-code-block-bg: #292d3e; + + --vp-code-line-highlight-color: rgba(0, 0, 0, 0.5); + + --vp-code-line-number-color: var(--vp-c-text-dark-3); } .dark { --vp-code-block-bg: var(--vp-c-bg-alt); + + --vp-code-line-number-color: var(--vp-c-text-dark-3); } /** diff --git a/src/node/markdown/plugins/highlight.ts b/src/node/markdown/plugins/highlight.ts index 279e8eb9..291267c3 100644 --- a/src/node/markdown/plugins/highlight.ts +++ b/src/node/markdown/plugins/highlight.ts @@ -1,9 +1,8 @@ import escapeHtml from 'escape-html' +import { getHighlighter } from 'shiki' export const highlight = async (theme = 'material-palenight') => { - const highlighter = await require('shiki').getHighlighter({ - theme - }) + const highlighter = await getHighlighter({ theme }) return (str: string, lang: string) => { if (!lang || lang === 'text') {