@duxweb/vela

v0.1.3

Published

2 months ago

A clean Astro documentation framework for Dux projects.

0High
0Medium
0Low

duxweb

astro documentation docs theme mdx

为什么是 Vela

很多文档站最后都会走向两个问题：主题太重不好改，或者每个项目重复维护一套文档布局。Vela 把可复用的文档外壳放进一个包，同时把产品首页和内容结构留给项目自己控制。

公开入口保持很小：

import vela from '@duxweb/vela'

export default defineConfig({
  integrations: [
    vela({
      title: 'Project Docs',
      docs: {...},
    }),
  ],
})

状态

Vela 是 pre-1.0 公开包。Astro 集成、内容路由、MDX、默认布局、侧栏、顶部导航、语言/主题/版本菜单、搜索、元信息、代码复制、Mermaid、默认首页、组件替换和发布构建流程都已经实现。

当前要求 Astro 7+ 和 Node.js 22.12+。

安装

pnpm add @duxweb/vela astro

Vela 会自动安装并注入 @astrojs/mdx。项目只需要定义 docs 内容集合。

快速开始

import { defineConfig } from 'astro/config'
import vela from '@duxweb/vela'

export default defineConfig({
  site: 'https://example.com',
  integrations: [
    vela({
      title: 'Project Docs',
      description: 'Documentation for your project.',
      theme: {
        accent: '#16a34a',
        dark: '#4ade80',
      },
      nav: [
        { label: 'Docs', slug: 'quick-start' },
        { label: 'API', slug: 'reference/api' },
        { label: 'GitHub', href: 'https://github.com/duxweb', external: true },
      ],
      docs: {
        main: {
          match: '/',
          sidebar: [
            {
              label: 'Start',
              items: [
                { label: 'Overview', slug: '' },
                { label: 'Quick Start', slug: 'quick-start' },
              ],
            },
          ],
        },
      },
    }),
  ],
})

创建 src/content.config.ts：

import { defineCollection } from 'astro:content'
import { glob } from 'astro/loaders'
import { velaDocsSchema } from '@duxweb/vela/schema'

export const collections = {
  docs: defineCollection({
    loader: glob({ base: './src/content/docs', pattern: '**/*.{md,mdx}' }),
    schema: velaDocsSchema,
  }),
}

src/content/docs/index.mdx 会变成 /。例如 src/content/docs/zh-cn/index.mdx 会变成 /zh-cn/。

当 defaultLocale 不是 root 时，默认语言目录会被视为根路径。例如 defaultLocale: 'zh-cn' 时，src/content/docs/zh-cn/index.mdx 会变成 /，src/content/docs/zh-cn/guide.mdx 会变成 /guide/。

配置

主题和元信息

vela({
  title: 'Project Docs',
  description: 'Documentation for your project.',
  theme: {
    accent: '#16a34a',
    dark: '#4ade80',
  },
  meta: {
    image: '/og.png',
    imageAlt: 'Project documentation',
    keywords: ['docs', 'project'],
    twitter: '@duxweb',
  },
})

页面 frontmatter 可以覆盖 title、description、image、imageAlt、keywords。

---
title: Quick Start
description: Install and configure the project.
image: /og/quick-start.png
updated: 2026-06-28 18:00
---

首页

Vela 内置默认首页：

vela({
  title: 'Project Docs',
  home: {
    eyebrow: 'Vela',
    badge: 'Reusable docs shell',
    title: 'Documentation that feels calm and direct',
    tagline: 'A polished docs shell for multiple projects.',
    command: 'pnpm add @duxweb/vela',
    actions: [
      { text: 'Start Reading', slug: 'guide', variant: 'primary' },
      { text: 'API', slug: 'api', variant: 'secondary' },
    ],
    features: [
      { label: 'Multiple sidebars', description: 'Switch docs navigation by path.', slug: 'guide' },
    ],
  },
})

项目也可以完全替换首页 Hero：

vela({
  title: 'Project Docs',
  components: {
    Hero: './src/components/HomeHero.astro',
  },
  customCss: ['./src/styles/home.css'],
})

自定义 Hero 会收到 { entry, route } props。首页营销样式建议放在项目里，不放进通用主题。

导航和分区

vela({
  title: 'Project Docs',
  nav: [
    {
      label: 'Docs',
      items: [
        { label: 'Guide', slug: 'guide' },
        { label: 'API', slug: 'api' },
      ],
    },
    { label: 'GitHub', href: 'https://github.com/duxweb/project', external: true },
  ],
  docs: {
    guide: {
      match: '/',
      sidebar: [{ label: 'Start', items: [{ label: 'Overview', slug: '' }] }],
    },
    api: {
      match: '/api',
      sidebar: [{ label: 'API', items: [{ label: 'Options', slug: 'api/options' }] }],
    },
  },
})

slug 会自动加上 Astro base 和当前语言前缀。docs.match 会在移除 base 和语言前缀后匹配，多个分区匹配时最长路径优先。

多语言

vela({
  title: 'Project Docs',
  defaultLocale: 'root',
  locales: {
    root: { label: 'English', lang: 'en' },
    'zh-cn': { label: '简体中文', lang: 'zh-CN' },
  },
  nav: [
    {
      label: 'Docs',
      translations: { 'zh-CN': '文档' },
      slug: 'quick-start',
    },
  ],
  i18n: {
    zh: {
      searchPlaceholder: '搜索当前文档',
      editPage: '在 GitHub 上编辑',
    },
  },
})

内置 UI 文案包含英文、中文、日文、韩文、法文、德文、西班牙文、葡萄牙文、俄文、意大利文和阿拉伯文。缺少的 key 会回退到内置语言，再回退到英文。

单语言站点直接把 defaultLocale 设置成该语言，并只定义一个 locale：

vela({
  defaultLocale: 'zh-cn',
  locales: {
    'zh-cn': { label: '简体中文', lang: 'zh-CN' },
  },
})

搜索、版本和编辑链接

vela({
  title: 'Project Docs',
  search: {
    placeholder: 'Search docs',
    translations: { 'zh-CN': '搜索文档' },
  },
  versions: [
    { label: 'v1.x', href: '/v1/' },
    { label: 'v0.x', href: '/v0/' },
  ],
  editLink: {
    pattern: 'https://github.com/org/repo/edit/main/:path',
    label: 'Edit this page',
    translations: { 'zh-CN': '编辑此页' },
  },
})

编辑链接支持 :path、:id、:slug、:locale 占位符。单个页面可以用 editUrl frontmatter 覆盖。

目录和流程图

vela({
  title: 'Project Docs',
  tableOfContents: {
    minHeadingLevel: 2,
    maxHeadingLevel: 3,
  },
  mermaid: true,
})

设置 tableOfContents: false 可以关闭右侧目录。设置 mermaid: false 可以关闭流程图渲染。

```mermaid
flowchart LR
  Content[Markdown / MDX] --> Vela[Vela route]
  Vela --> Layout[Docs layout]
  Layout --> Page[Static HTML]
```

自定义组件

Vela 暴露可替换的外壳组件：

vela({
  title: 'Project Docs',
  components: {
    Head: './src/components/Head.astro',
    Header: './src/components/Header.astro',
    Sidebar: './src/components/Sidebar.astro',
    Pagination: './src/components/Pagination.astro',
    Hero: './src/components/Hero.astro',
    Search: './src/components/Search.astro',
    VersionSelect: './src/components/VersionSelect.astro',
    EditPage: './src/components/EditPage.astro',
  },
})

大多数项目只需要替换 Hero 并追加 customCss。

MDX 组件与交互预览

Vela 默认向 MDX 注入 DemoFrame、FrameworkTabs、CodeTabs 和 CodePanel，无需逐页 import。项目可追加自己的组件：

vela({
  title: 'Project Docs',
  mdxComponents: {
    ComponentPreview: './src/components/ComponentPreview.astro',
  },
})

components 只替换 Header、Sidebar 等外壳；mdxComponents 只负责文档正文中的演示组件，两者职责独立。

发布导出

| 导出 | 用途 | | :--- | :--- | | @duxweb/vela | Astro 集成和公开配置类型。 | | @duxweb/vela/schema | 内容集合 schema。 | | @duxweb/vela/components/* | 默认 Astro 组件，适合高级覆盖。 | | @duxweb/vela/styles/* | 默认 CSS 资源。 |

本地开发

pnpm install
pnpm check
pnpm build
pnpm build:example
pnpm pack --dry-run

发布

pnpm check
pnpm build
pnpm build:example
pnpm publish

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme