From ac8619f841862b8629ea0416ba2f188faceebc70 Mon Sep 17 00:00:00 2001 From: Sascha <43013380+szsascha@users.noreply.github.com> Date: Mon, 31 Oct 2022 11:04:34 +0100 Subject: [PATCH] feat(theme): add built-in global component `Badge` (#1239) Co-authored-by: richardo2016 Co-authored-by: Kia Ishii Co-authored-by: Divyansh Singh <40380293+brc-dd@users.noreply.github.com> --- docs/.vitepress/config.ts | 1 + docs/guide/theme-badge.md | 83 +++++++++++++++++++ docs/guide/theme-introduction.md | 10 ++- docs/guide/using-vue.md | 5 +- .../theme-default/components/VPBadge.vue | 55 ++++++++++++ src/client/theme-default/index.ts | 6 +- src/client/theme-default/styles/vars.css | 36 ++++++++ theme.d.ts | 2 + 8 files changed, 192 insertions(+), 6 deletions(-) create mode 100644 docs/guide/theme-badge.md create mode 100644 src/client/theme-default/components/VPBadge.vue diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 72498f2c17c8..53a706804f46 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -108,6 +108,7 @@ function sidebarGuide() { { text: 'Layout', link: '/guide/theme-layout' }, { text: 'Home Page', link: '/guide/theme-home-page' }, { text: 'Team Page', link: '/guide/theme-team-page' }, + { text: 'Badge', link: '/guide/theme-badge' }, { text: 'Footer', link: '/guide/theme-footer' }, { text: 'Search', link: '/guide/theme-search' }, { text: 'Carbon Ads', link: '/guide/theme-carbon-ads' } diff --git a/docs/guide/theme-badge.md b/docs/guide/theme-badge.md new file mode 100644 index 000000000000..99b43151c03f --- /dev/null +++ b/docs/guide/theme-badge.md @@ -0,0 +1,83 @@ +# Badge + +The badge lets you add status to your headers. For example, it could be useful to specify the section's type, or supported version. + +## Usage + +You may use the `Badge` component which is globally available. + +```html +### Title +### Title +### Title +### Title +``` + +Code above renders like: + +### Title +### Title +### Title +### Title + +## Custom Children + +`` accept `children`, which will be displayed in the badge. + +```html +### Title custom element +``` + +### Title custom element + +## Customize Type Color + +you can customize `background-color` of typed `` by override css vars. The following is he default values. + +```css +:root { + --vp-badge-info-border: var(--vp-c-divider-light); + --vp-badge-info-text: var(--vp-c-text-2); + --vp-badge-info-bg: var(--vp-c-white-soft); + + --vp-badge-tip-border: var(--vp-c-green-dimm-1); + --vp-badge-tip-text: var(--vp-c-green-darker); + --vp-badge-tip-bg: var(--vp-c-green-dimm-3); + + --vp-badge-warning-border: var(--vp-c-yellow-dimm-1); + --vp-badge-warning-text: var(--vp-c-yellow-darker); + --vp-badge-warning-bg: var(--vp-c-yellow-dimm-3); + + --vp-badge-danger-border: var(--vp-c-red-dimm-1); + --vp-badge-danger-text: var(--vp-c-red-darker); + --vp-badge-danger-bg: var(--vp-c-red-dimm-3); +} + +.dark { + --vp-badge-info-border: var(--vp-c-divider-light); + --vp-badge-info-bg: var(--vp-c-black-mute); + + --vp-badge-tip-border: var(--vp-c-green-dimm-2); + --vp-badge-tip-text: var(--vp-c-green-light); + + --vp-badge-warning-border: var(--vp-c-yellow-dimm-2); + --vp-badge-warning-text: var(--vp-c-yellow-light); + + --vp-badge-danger-border: var(--vp-c-red-dimm-2); + --vp-badge-danger-text: var(--vp-c-red-light); +} +``` + +## `` + +`` component accepts following props: + +```ts +interface Props { + // When `` is passed, this value gets ignored. + text?: string + + // Defaults to `tip`. + type?: 'info' | 'tip' | 'warning' | 'danger' +} +``` diff --git a/docs/guide/theme-introduction.md b/docs/guide/theme-introduction.md index 4d125a2fb93d..c59585b045bb 100644 --- a/docs/guide/theme-introduction.md +++ b/docs/guide/theme-introduction.md @@ -10,6 +10,7 @@ VitePress comes with its default theme providing many features out of the box. L - [Layout](./theme-layout) - [Home Page](./theme-home-page) - [Team Page](./theme-team-page) +- [Badge](./theme-badge) - [Footer](./theme-footer) - [Search](./theme-search) - [Carbon Ads](./theme-carbon-ads) @@ -109,9 +110,12 @@ import DefaultTheme from 'vitepress/theme' export default { ...DefaultTheme, - enhanceApp({ app }) { - // register global components - app.component('MyGlobalComponent', /* ... */) + enhanceApp(ctx) { + // extend default theme custom behaviour. + DefaultTheme.enhanceApp(ctx) + + // register your custom global components + ctx.app.component('MyGlobalComponent' /* ... */) } } ``` diff --git a/docs/guide/using-vue.md b/docs/guide/using-vue.md index 998d3aa86386..600600eab2ae 100644 --- a/docs/guide/using-vue.md +++ b/docs/guide/using-vue.md @@ -113,8 +113,9 @@ import DefaultTheme from 'vitepress/theme' export default { ...DefaultTheme, - enhanceApp({ app }) { - app.component('VueClickAwayExample', VueClickAwayExample) + enhanceApp(ctx) { + DefaultTheme.enhanceApp(ctx) + ctx.app.component('VueClickAwayExample', VueClickAwayExample) } } ``` diff --git a/src/client/theme-default/components/VPBadge.vue b/src/client/theme-default/components/VPBadge.vue new file mode 100644 index 000000000000..0d7d20d4dfdf --- /dev/null +++ b/src/client/theme-default/components/VPBadge.vue @@ -0,0 +1,55 @@ + + + + + diff --git a/src/client/theme-default/index.ts b/src/client/theme-default/index.ts index 7b7921283586..a0815806df60 100644 --- a/src/client/theme-default/index.ts +++ b/src/client/theme-default/index.ts @@ -8,6 +8,7 @@ import './styles/components/vp-doc.css' import './styles/components/vp-sponsor.css' import { Theme } from 'vitepress' +import VPBadge from './components/VPBadge.vue' import Layout from './Layout.vue' import NotFound from './NotFound.vue' @@ -22,7 +23,10 @@ export { default as VPTeamMembers } from './components/VPTeamMembers.vue' const theme: Theme = { Layout, - NotFound + NotFound, + enhanceApp: ({ app }) => { + app.component('Badge', VPBadge) + } } export default theme diff --git a/src/client/theme-default/styles/vars.css b/src/client/theme-default/styles/vars.css index f736d93f08a4..e7c41ca161e7 100644 --- a/src/client/theme-default/styles/vars.css +++ b/src/client/theme-default/styles/vars.css @@ -370,3 +370,39 @@ --vp-home-hero-image-background-image: none; --vp-home-hero-image-filter: none; } + +/** + * Component: Badge + * -------------------------------------------------------------------------- */ + +:root { + --vp-badge-info-border: var(--vp-c-divider-light); + --vp-badge-info-text: var(--vp-c-text-2); + --vp-badge-info-bg: var(--vp-c-white-soft); + + --vp-badge-tip-border: var(--vp-c-green-dimm-1); + --vp-badge-tip-text: var(--vp-c-green-darker); + --vp-badge-tip-bg: var(--vp-c-green-dimm-3); + + --vp-badge-warning-border: var(--vp-c-yellow-dimm-1); + --vp-badge-warning-text: var(--vp-c-yellow-darker); + --vp-badge-warning-bg: var(--vp-c-yellow-dimm-3); + + --vp-badge-danger-border: var(--vp-c-red-dimm-1); + --vp-badge-danger-text: var(--vp-c-red-darker); + --vp-badge-danger-bg: var(--vp-c-red-dimm-3); +} + +.dark { + --vp-badge-info-border: var(--vp-c-divider-light); + --vp-badge-info-bg: var(--vp-c-black-mute); + + --vp-badge-tip-border: var(--vp-c-green-dimm-2); + --vp-badge-tip-text: var(--vp-c-green-light); + + --vp-badge-warning-border: var(--vp-c-yellow-dimm-2); + --vp-badge-warning-text: var(--vp-c-yellow-light); + + --vp-badge-danger-border: var(--vp-c-red-dimm-2); + --vp-badge-danger-text: var(--vp-c-red-light); +} diff --git a/theme.d.ts b/theme.d.ts index 553f02a04b5e..1848e45bcc50 100644 --- a/theme.d.ts +++ b/theme.d.ts @@ -1,5 +1,6 @@ // so that users can do `import DefaultTheme from 'vitepress/theme'` import type { DefineComponent } from 'vue' +import { EnhanceAppContext } from './dist/client/index.js' // TODO: add props for these export const VPHomeHero: DefineComponent @@ -14,6 +15,7 @@ export const VPTeamMembers: DefineComponent declare const theme: { Layout: DefineComponent NotFound: DefineComponent + enhanceApp: (ctx: EnhanceAppContext) => void } export default theme