DOCSEARCHbyAlgolia
Submit Docs

Lumen VitePress Theme

website·Indexed 30 days ago

https://lumen.theojs.net

A plugin and theme for VitePress (@theojs/lumen) that provides a suite of UI components including Notice, Underline, Footer, Aside, and Link Cards (Pill, BoxCube, Card). It includes support for theme customization via CSS variables, Iconify integration, and built-in tools for site analytics (Google Analytics, Baidu Analytics, Umami).

Tokens
13.4K
Snippets
76
Records
86
Agent score
56%

What's inside Lumen

  1. Integrate Baidu Analytics into VitePress

    Use baiduAnalytics to load the tracking script and trackPageview to report page views during client-side routing changes. Because VitePress uses a single-page app architecture, you must manually trigger trackPageview within the router.onAfterRouteChange hook to ensure accurate tracking across navigation.
    import type { EnhanceAppContext } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import { baiduAnalytics, trackPageview } from '@theojs/lumen'

const baiduId = '******'

export default {
  extends: DefaultTheme,
  enhanceApp: ({ router }: EnhanceAppContext) => {
    baiduAnalytics({ baiduId })

    const previousAfterRouteChange = router.onAfterRouteChange
    router.onAfterRouteChange = async (to) => {
      await previousAfterRouteChange?.(to)
      trackPageview(baiduId, to)
    }
  }
}

  2. Add custom links and branding to VitePress sidebars using the Aside component

    The Aside component from the @theojs/lumen plugin allows developers to integrate custom links, promotional information, or brand logos directly into a VitePress sidebar to enhance user experience and site branding.

  3. Integrate Google Analytics into VitePress

    Use the googleAnalytics function from @theojs/lumen within the enhanceApp hook of your VitePress theme configuration. The analytics script is only loaded in production builds and will not send data during development.
    import DefaultTheme from 'vitepress/theme'
import { googleAnalytics } from '@theojs/lumen'

export default {
  extends: DefaultTheme,
  enhanceApp() {
    googleAnalytics({ id: 'G-******' })
  }
}

  4. Add dynamic underlines to the VitePress home page hero section

    The Underline component creates a dynamic underline effect by targeting the hero section of the VitePress home layout. It reads the text and textsuffix properties from the page's frontmatter to split the title and apply the underline to the first part.

    Constraints:

    • Must be used with layout: home.
    • Place the <Underline /> component in the page body.
    • It replaces the default VitePress Hero title node; it may not work if the Hero DOM structure is heavily customized.
    # index.md
---
layout: home

hero:
  name: Lumen
  text: Enhanced # The part that will be underlined
  textsuffix: Theme # The part following the underline
  tagline: ✨ 专为 VitePress 打造的主题美化与 Vue 扩展组件库
---
<Underline />

  5. Integrate the Aside component into VitePress sidebar

    To add the Aside component to your VitePress sidebar, you must override the Layout in your theme configuration and use the aside-ads-before slot. This allows you to inject custom links or promotional content before the main sidebar navigation.
    // .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import { h } from 'vue'
import { Aside } from '@theojs/lumen'
import { Aside_Data } from '../data/AsideData'

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'aside-ads-before': () => h(Aside, { Aside_Data })
    })
  }
}

  6. Register CopyText component in VitePress

    To use the CopyText component globally in a VitePress project, import it from @theojs/lumen and register it within the enhanceApp function in your theme configuration. You can assign it a custom global alias such as Copy.
    import type { EnhanceAppContext } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import { CopyText } from '@theojs/lumen'

export default {
  extends: DefaultTheme,
  enhanceApp: ({ app }: EnhanceAppContext) => {
    app.component('Copy', CopyText)
  }
}

  7. Integrate Umami Analytics into VitePress

    Use the umamiAnalytics function in the enhanceApp hook. This script is only loaded in production builds. You can provide a single configuration object or an array of configuration objects to track multiple sites simultaneously.
    import DefaultTheme from 'vitepress/theme'
import { umamiAnalytics } from '@theojs/lumen'

export default {
  extends: DefaultTheme,
  enhanceApp() {
    umamiAnalytics({
      id: '***-***-***-***',
      src: 'https://*******',
      domains: 'your.domain.com' // Optional
    })
  }
}

  8. Add image captions to VitePress using @mdit/plugin-figure

    To support image descriptions (figcaption) in VitePress, install the @mdit/plugin-figure plugin and register it within the VitePress markdown configuration.
    # Install the plugin
pnpm add -D @mdit/plugin-figure
    // .vitepress/config.mts
import { defineConfig } from 'vitepress'
import { figure } from '@mdit/plugin-figure'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(figure)
    }
  }
})

  9. Install @theojs/lumen plugin

    The @theojs/lumen plugin can be installed using pnpm, npm, or yarn.
    # Using pnpm
pnpm add @theojs/lumen

# Using npm
npm install @theojs/lumen

# Using yarn
yarn add @theojs/lumen

  10. Implement multi-language (i18n) support for Aside data

    The AsideItem type supports two i18n strategies:

    1. Global i18n object: The entire data set is wrapped in an i18n object where keys are language codes (e.g., root, en) and values are arrays of items.
    2. Per-item i18n: Each item contains its own i18n property to override specific fields (like promo or name) for different languages.
    import type { AsideItem } from '@theojs/lumen'

// Strategy 1: Global i18n structure
export const Global_i18n_Data: AsideItem = {
  i18n: {
    root: [{ promo: '活动标题', link: 'https://example.com/' }],
    en: [{ promo: 'Promotion Title', link: 'https://example.com/' }]
  }
}

// Strategy 2: Per-item i18n structure
export const Item_i18n_Data: AsideItem = [
  {
    promo: '活动标题',
    link: 'https://example.com/',
    i18n: {
      en: { promo: 'Promotion title' }
    }
  },
  {
    name: '普通链接',
    link: 'https://example.com/',
    i18n: {
      en: { name: 'Link' }
    }
  }
]

  11. Integrate the Notice component into VitePress layout

    To add the Notice announcement component to your VitePress homepage, import the Notice component from @theojs/lumen and inject it into the home-hero-info-before slot of the default theme layout using Vue's h function.
    // .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import { h } from 'vue'
import { Notice } from '@theojs/lumen'

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'home-hero-info-before': () => h(Notice)
    })
  }
}

  12. Implement i18n for Aside sidebar components

    The Aside component supports internationalization (i18n) at both the top-level array and individual item levels. The component resolves content using the following priority:

    1. It selects the top-level array corresponding to the current language.
    2. It performs a shallow merge of the current language fields for each item to override base configurations.
    3. Fields not overridden by the translation inherit the base configuration.
    4. Nested objects are entirely replaced by the translation value.

    Behavioral constraints:

    • If the top-level array for the current language is missing, the entry will not be displayed.
    • If an individual item lacks a translation for the current language, it retains its original base data.