docs: add docs (close #36)

.github/workflows/check.yml

@@ -11,13 +11,7 @@ on:
 
 jobs:
   check:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-        node: ['18', '20']
-
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v4
@@ -40,6 +34,11 @@ jobs:
       - name: Linter Test
         run: pnpm lint
 
+      - name: Docs Test
+        run: |
+          pnpm --filter @vuepress/ecosystem-docs docs:build
+          pnpm --filter @vuepress/ecosystem-docs docs:build-webpack
+
       - name: Unit Test
         run: pnpm test:unit
 

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Deploy Ecosystem Docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy-github-docs:
+    name: Deploy ecosystem docs to Github Pages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Build Project
+        run: pnpm build
+
+      - name: Docs build
+        env:
+          BASE: /ecosystem/
+          NODE_OPTIONS: --max_old_space_size=8192
+        run: pnpm --filter @vuepress/ecosystem-docs docs:build
+
+      - name: Deploy docs
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: docs/.vuepress/dist
+          single-commit: true

.github/workflows/release.yml

@@ -25,3 +25,39 @@ jobs:
           tag_name: ${{ github.ref }}
           body: |
             Please refer to [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details.
+
+  deploy-docs:
+    name: Deploy ecosystem docs to Netlify
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install deps
+        run: pnpm install --frozen-lockfile
+
+      - name: Build Project
+        run: pnpm build
+
+      - name: Docs build
+        env:
+          NODE_OPTIONS: --max_old_space_size=8192
+        run: pnpm --filter @vuepress/ecosystem-docs docs:build
+
+      - name: Deploy docs
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: netlify
+          folder: docs/.vuepress/dist
+          single-commit: true

docs/.vuepress/components/NpmBadge.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps({
+  package: {
+    type: String,
+    required: true,
+  },
+  distTag: {
+    type: String,
+    required: false,
+    default: 'next',
+  },
+})
+
+const badgeLink = computed(
+  () => `https://www.npmjs.com/package/${props.package}`,
+)
+const badgeLabel = computed(() => {
+  if (props.distTag) {
+    return `${props.package}@${props.distTag}`
+  }
+  return props.package
+})
+const badgeImg = computed(
+  () =>
+    `https://badgen.net/npm/v/${props.package}/${
+      props.distTag
+    }?label=${encodeURIComponent(badgeLabel.value)}`,
+)
+</script>
+
+<template>
+  <a
+    class="npm-badge"
+    :href="badgeLink"
+    :title="package"
+    target="_blank"
+    rel="noopener noreferrer"
+  >
+    <img :src="badgeImg" :alt="package" />
+  </a>
+</template>
+
+<style scoped>
+.npm-badge {
+  margin-right: 0.5rem;
+}
+</style>

docs/.vuepress/config.ts

@@ -0,0 +1,131 @@
+import { createRequire } from 'node:module'
+import process from 'node:process'
+import { viteBundler } from '@vuepress/bundler-vite'
+import { webpackBundler } from '@vuepress/bundler-webpack'
+// import { docsearchPlugin } from '@vuepress/plugin-docsearch'
+import { registerComponentsPlugin } from '@vuepress/plugin-register-components'
+import { shikiPlugin } from '@vuepress/plugin-shiki'
+import { defineUserConfig } from 'vuepress'
+import type { UserConfig } from 'vuepress'
+import { getDirname, path } from 'vuepress/utils'
+import { head } from './configs/index.js'
+import theme from './theme.js'
+
+const __dirname = getDirname(import.meta.url)
+const require = createRequire(import.meta.url)
+
+const isProd = process.env.NODE_ENV === 'production'
+
+export default defineUserConfig({
+  // set site base to default value
+  base: (process.env.BASE as `/${string}/` | '/') || '/',
+
+  // extra tags in `<head>`
+  head,
+
+  // site-level locales config
+  locales: {
+    '/': {
+      lang: 'en-US',
+      title: 'VuePress Ecosystem',
+      description: 'VuePress official themes plugins',
+    },
+    '/zh/': {
+      lang: 'zh-CN',
+      title: 'VuePress 生态系统',
+      description: 'VuePress 官方主题和插件',
+    },
+  },
+
+  // specify bundler via environment variable
+  bundler:
+    process.env.DOCS_BUNDLER === 'webpack' ? webpackBundler() : viteBundler(),
+
+  // configure markdown
+  markdown: {
+    importCode: {
+      handleImportPath: (importPath) => {
+        // handle @vuepress packages import path
+        if (importPath.startsWith('@vuepress/')) {
+          const packageName = importPath.match(/^(@vuepress\/[^/]*)/)![1]
+          return importPath
+            .replace(
+              packageName,
+              path.dirname(require.resolve(`${packageName}/package.json`)),
+            )
+            .replace('/src/', '/lib/')
+            .replace(/hotKey\.ts$/, 'hotKey.d.ts')
+        }
+        return importPath
+      },
+    },
+  },
+
+  // configure default theme
+  theme,
+
+  // use plugins
+  plugins: [
+    // docsearchPlugin({
+    //   appId: '34YFD9IUQ2',
+    //   apiKey: '9a9058b8655746634e01071411c366b8',
+    //   indexName: 'vuepress',
+    //   searchParameters: {
+    //     facetFilters: ['tags:v2'],
+    //   },
+    //   locales: {
+    //     '/zh/': {
+    //       placeholder: '搜索文档',
+    //       translations: {
+    //         button: {
+    //           buttonText: '搜索文档',
+    //           buttonAriaLabel: '搜索文档',
+    //         },
+    //         modal: {
+    //           searchBox: {
+    //             resetButtonTitle: '清除查询条件',
+    //             resetButtonAriaLabel: '清除查询条件',
+    //             cancelButtonText: '取消',
+    //             cancelButtonAriaLabel: '取消',
+    //           },
+    //           startScreen: {
+    //             recentSearchesTitle: '搜索历史',
+    //             noRecentSearchesText: '没有搜索历史',
+    //             saveRecentSearchButtonTitle: '保存至搜索历史',
+    //             removeRecentSearchButtonTitle: '从搜索历史中移除',
+    //             favoriteSearchesTitle: '收藏',
+    //             removeFavoriteSearchButtonTitle: '从收藏中移除',
+    //           },
+    //           errorScreen: {
+    //             titleText: '无法获取结果',
+    //             helpText: '你可能需要检查你的网络连接',
+    //           },
+    //           footer: {
+    //             selectText: '选择',
+    //             navigateText: '切换',
+    //             closeText: '关闭',
+    //             searchByText: '搜索提供者',
+    //           },
+    //           noResultsScreen: {
+    //             noResultsText: '无法找到相关结果',
+    //             suggestedQueryText: '你可以尝试查询',
+    //             reportMissingResultsText: '你认为该查询应该有结果？',
+    //             reportMissingResultsLinkText: '点击反馈',
+    //           },
+    //         },
+    //       },
+    //     },
+    //   },
+    // }),
+    registerComponentsPlugin({
+      componentsDir: path.resolve(__dirname, './components'),
+    }),
+    // only enable shiki plugin in production mode
+    isProd
+      ? shikiPlugin({
+          langs: ['bash', 'diff', 'json', 'md', 'ts', 'vue'],
+          theme: 'dark-plus',
+        })
+      : [],
+  ],
+}) as UserConfig

docs/.vuepress/configs/head.ts

@@ -0,0 +1,40 @@
+import type { HeadConfig } from 'vuepress/core'
+
+export const head: HeadConfig[] = [
+  [
+    'link',
+    {
+      rel: 'icon',
+      type: 'image/png',
+      sizes: '16x16',
+      href: `/images/icons/favicon-16x16.png`,
+    },
+  ],
+  [
+    'link',
+    {
+      rel: 'icon',
+      type: 'image/png',
+      sizes: '32x32',
+      href: `/images/icons/favicon-32x32.png`,
+    },
+  ],
+  ['link', { rel: 'manifest', href: '/manifest.webmanifest' }],
+  ['meta', { name: 'application-name', content: 'VuePress' }],
+  ['meta', { name: 'apple-mobile-web-app-title', content: 'VuePress' }],
+  ['meta', { name: 'apple-mobile-web-app-status-bar-style', content: 'black' }],
+  [
+    'link',
+    { rel: 'apple-touch-icon', href: `/images/icons/apple-touch-icon.png` },
+  ],
+  [
+    'link',
+    {
+      rel: 'mask-icon',
+      href: '/images/icons/safari-pinned-tab.svg',
+      color: '#3eaf7c',
+    },
+  ],
+  ['meta', { name: 'msapplication-TileColor', content: '#3eaf7c' }],
+  ['meta', { name: 'theme-color', content: '#3eaf7c' }],
+]

docs/.vuepress/configs/index.ts

@@ -0,0 +1,3 @@
+export * from './head.js'
+export * from './navbar/index.js'
+export * from './sidebar/index.js'

docs/.vuepress/configs/navbar/en.ts

@@ -0,0 +1,52 @@
+import type { NavbarConfig } from '@vuepress/theme-default'
+
+export const navbarEn: NavbarConfig = [
+  {
+    text: 'Themes',
+    children: [
+      {
+        text: 'Default Theme',
+        link: '/themes/default/',
+      },
+    ],
+  },
+  {
+    text: 'Plugins',
+    children: [
+      {
+        text: 'Common Features',
+        children: [
+          '/plugins/back-to-top',
+          '/plugins/container',
+          '/plugins/external-link-icon',
+          '/plugins/google-analytics',
+          '/plugins/medium-zoom',
+          '/plugins/nprogress',
+          '/plugins/register-components',
+        ],
+      },
+      {
+        text: 'Content Search',
+        children: ['/plugins/docsearch', '/plugins/search'],
+      },
+      {
+        text: 'PWA',
+        children: ['/plugins/pwa', '/plugins/pwa-popup'],
+      },
+      {
+        text: 'Syntax Highlighting',
+        children: ['/plugins/prismjs', '/plugins/shiki'],
+      },
+      {
+        text: 'Theme Development',
+        children: [
+          '/plugins/active-header-links',
+          '/plugins/git',
+          '/plugins/palette',
+          '/plugins/theme-data',
+          '/plugins/toc',
+        ],
+      },
+    ],
+  },
+]

docs/.vuepress/configs/navbar/index.ts

@@ -0,0 +1,2 @@
+export * from './en.js'
+export * from './zh.js'