Building Vue3 Component Library from Scratch #9 Setting Up and Deploying Documentation with VitePress

#vitepress #vue

Setting Up Component Library Documentation with VitePress

When our component library is complete, a detailed usage document is indispensable. This article will introduce how to quickly build a component library documentation site with VitePress and deploy it to GitHub.

Installation

Firstly, create 'site' folder, execute pnpm init, and then install vitepress and vue.

pnpm install -D vitepress vue

After the installation is complete, create docs/index.md file.

# Hello StellarNovaUI

Then, add new scripts command in the package.json.

"scripts": {
  "docs:dev": "vitepress dev docs",
  "docs:build": "vitepress build docs",
  "docs:preview": "vitepress preview docs"
},

Execute pnpm run docs:dev.

Navigation Bar Configuration

Create config.js in the docs/.vitepress directory.

export default {
  title: 'StellarNovaUI',
  base: process.env.NODE_ENV === 'production' ? '/stellarnovaui/' : '/',
  themeConfig: {
    nav: [{ text: 'Document', link: '/guide/introduce' }],
    sidebar: {
      '/': [
        {
          text: 'Introduction',
          items: [
            {
              text: 'Introduce',
              link: '/guide/introduce'
            },
            {
              text: 'Quick Start',
              link: '/guide/quickstart'
            }
          ]
        },
        {
          text: 'Development',
          items: [
            {
              text: 'Directory Structure',
              link: '/develop/'
            },
            {
              text: 'Component Development',
              link: '/develop/component'
            },
            {
              text: 'Global Components',
              link: '/develop/global'
            },

            {
              text: 'Build and Deploy',
              link: '/develop/build'
            }
          ]
        },
        {
          text: 'Components',
          items: [
            {
              text: 'Button',
              link: '/components/button/'
            },
          ]
        }
      ]
    },
    socialLinks: [{ icon: 'github', link: 'https://github.com/markliu2013/stellarnovaui' }]
  }
};

we add two navigation bars and a GitHub address. Restart the project and you can see that the navigation bar.

However, clicking on 'Guide' and 'Components' results is 404 error, because we have not yet created these directories and files. Therefore, we need to create guide/index.md and components/button/index.md in the docs directory. Click again to navigate to the corresponding page.

Import Component Library

Since we are building a component library documentation site, we definitely need to import our component library. Here, we also import the local component library, so we add a 'site' directory in the pnpm workspace pnpm-workspace.yaml.

packages:
  - "packages/**"
  - "play"
  - "site"

Then under the 'site' directory, install stellarnovaui with pnpm add stellarnovaui, and create theme/index.js in the docs directory to import our component library.

import DefaultTheme from "vitepress/theme";
import stellarnovaui from "stellarnovaui"
export default {
    ...DefaultTheme,
    enhanceApp: async ({ app }) => {
        // app is the Vue 3 app instance from `createApp()`. router is VitePress'
        // custom router. `siteData`` is a `ref`` of current site-level metadata.
        app.use(stellarnovaui);

    },
};

Go back to components/button/index.md and try using our button component directly.

## Button

<sn-button>Default Button</sn-button>

<sn-button type="primary">Default Button</sn-button>

You can see that our component is now working.

At the same time, we can also add code to display the effect, such as changing button/index.md to:

## Button

<sn-button>Default Button</sn-button>

<sn-button type="primary">Default Button</sn-button>

::: details Show Code

html
Default Button Default Button

:::

Deploy

After the packaging is complete, you can deploy it to your own server, or you can choose to deploy it to a GitHub site. Here, I will introduce how to deploy it to a GitHub site.

Firstly, create a new organization called 'stellarnovaui', then create a new repository called 'stellarnovaui' under the organization.

Then commit the site/docs/.vitepress/dist to this repository.

Click on 'settings', select the branch and directory to deploy, here it's the root directory, and save it.

In the end, the address to access our site is stellarnovaui.github.io/stellarnovaui/, so when packaging, the base in site/docs/.vitepress/config.js should be /stellarnovaui/.

export default {
  title: 'StellarNovaUI',
  base: process.env.NODE_ENV === 'production' ? '/stellarnovaui/' : '/',
  ...
}

After completing the above steps, you can visit our site. The site updates in real time, any changes to your repository will be reflected on the site.

Note: If you encounter a 404 error when visiting, it may be that your base configuration is incorrect.

The final source code: https://github.com/markliu2013/StellarNovaUI