valaxy/write.md at 0578707e457a74647fd94aa2627c1258d90d7eaf

5.1 KiB

Raw Blame History

title

title_zh-CN

APIs

我们提供了一个扩展函数，以供你快速扩展页面信息。

你也可以直接扩展 vite-plugin-pages 插件中的 extendRoute。

// valaxy.config.ts
import { defineTheme } from 'valaxy'
export default defineTheme({
  pages: {
    extendRoute(route, parent) {
      console.log(route)
    },
  },
  extendMd(ctx) {
    console.log(ctx.path)
  },
})

// provided by valaxy, just as a tip
export interface ValaxyConfig {
  vue?: Parameters<typeof Vue>[0]
  components?: Parameters<typeof Components>[0]
  unocss?: UnoCSSConfig
  pages?: Parameters<typeof Pages>[0]
  extendMd?: (ctx: {
    route: {
      meta: { frontmatter?: Record<string, any>; layout?: string }
      path: string
      component: string
    }
    data: Readonly<Record<string, any>>
    excerpt?: string
    path: string
  }) => void
}

::: tip

data解析自 Markdown frontmatter，为原始数据（不可变），将会被合并至 route.meta.frontmatter 中。

:::

开始编写

ValaxyMain

你需要自定义一个 ValaxyMain 组件来决定主题的文章渲染部分。

你可以从 ValaxyMain 的 props 中获取 frontmatter 与 pageData。

<script lang="ts" setup>
import type { PageData, Post } from 'valaxy'

defineProps<{
  frontmatter: Post
  data?: PageData
}>()
</script>

<template>
  <main>
    <slot name="main-content">
      <ValaxyMd :frontmatter="frontmatter">
        <slot name="main-content-md" />
        <slot />
      </ValaxyMd>
    </slot>
  </main>
</template>

示例可参考 ValaxyMain.vue | valaxy-theme-yun

样式

Markdown 样式

Markdown 样式是主题呈现文章样式的部分，需要由主题自定义。

你可以参考 valaxy-theme-press 自定义 Markdown 主题的方式，见 styles/markdown.scss。

如果你想先使用常见的默认样式（后续再进行定制），你可以直接使用 star-markdown-css。使用方式可参见 valaxy-theme-yun/styles

功能

<script setup lang="ts">
import { useOutline } from 'valaxy'
const { headers, handleClick } = useOutline()
</script>

<template>
  <nav aria-labelledby="doc-outline-aria-label">
    <span id="doc-outline-aria-label" class="visually-hidden">
      Table of Contents
    </span>

    <PressOutlineItem
      class="va-toc relative z-1"
      :headers="headers"
      :on-click="handleClick"
      root
    />
  </nav>
</template>

更多可参见 PressOutline | valaxy-theme-press。

Third Plugin

实现评论

作为博客，用户通常会有评论的需求。

而由于评论系统各不相同，如 Hexo 等主题开发者们通常需在主题侧重复实现多款评论系统。这显然是繁琐的。

Valaxy 决定通过插件中心化地提供各类封装好的评论组件和辅助函数。

譬如主题开发者，可以借助 valaxy-addon-waline 来快速实现 Waline 评论系统的集成。
而用户则可以使用相同的配置穿梭漫游于不同的主题之间。

集成参见 valaxy-addon-waline。

FAQ

如果您的主题适配了多个 Addon（如 valaxy-addon-waline/valaxy-addon-twikoo），但用户并非都需要安装。您需要将其添加至 vite.build.rollupOptions.external 中以避免引起编译问题。

譬如 valaxy-theme-yun/valaxy.config.ts:

import { defineValaxyTheme } from 'valaxy'
import type { ThemeConfig } from './types'
import { defaultThemeConfig, generateSafelist } from './node'

export default defineValaxyTheme<ThemeConfig>((options) => {
  return {
    themeConfig: defaultThemeConfig,
    vite: {
      build: {
        rollupOptions: {
          // add on demand external
          external: ['valaxy-addon-twikoo', 'valaxy-addon-waline'],
        },
      },
      plugins: [ThemeVitePlugin(options)],
    },
    unocss: {
      safelist: generateSafelist(options),
    },
  }
})

5.1 KiB Raw Blame History Unescape Escape