Component documentation and preview effects

First of all, I will list some of the most popular document presentation frameworks

  • story-book
  • vue-press
  • dumi

Each of these document presentation frameworks can be used to present components, but each has its own set of rules and additional learning costs. So I chose not to use these, and instead built a document preview application from the project itself that I created with Vite in the previous section.

Build the document preview application

We can only see the following results for our current startup project

Compared to mainstream component library applications, we need to achieve the following minimum requirements:

  1. A navigation menu for components
  2. A preview of the component
  3. Component instance code
  4. Introduction to components (configuration items, events, extra notes, etc.)

1. Add the navigation menu of the component

Here we refer to vue-Router, and here the V4 version is chosen. It also references Ant-design-vue as the UI library

yarn add vue-router@4 -D
yarn add ant-design-vue@next -D
Copy the code

Add a folder under the SRC directory

- router // Used for route configuration - page // Used for compiling preview pagesCopy the code

Add a HelloPage to the Page page

import { defineComponent } from 'vue';
import { Hello } from 'mis-design';

const HelloPage = defineComponent({
  setup() {
    return () = > (<Hello title="123"></Hello>); }});export default HelloPage;

Copy the code

Configure the routing

import { createRouter, createWebHistory } from 'vue-router';

import Hello from '.. /page/Hello'

const routes = [{
    path: '/'.component: Hello
}]

const router = createRouter({
    history:createWebHistory(),
    routes
})

export default  router;
Copy the code

Modify the main ts

import { createApp } from 'vue'
import App from './App.vue'
import MyUI from '.. /packages/components'
import Routes from './router'
import 'ant-design-vue/dist/antd.css'

createApp(App).use(Routes).use(MyUI).mount('#app')

Copy the code

Modify app.vue, change page layout, add menu bar, etc. Start by creating a new menus.tsx in the Page folder

import { defineComponent, watch, reactive } from 'vue';
import { Menu } from 'ant-design-vue';
import { RouterLink, useRoute } from 'vue-router';

interface IMenuItem {
  name: string; zh? :string;
  path: string;
}

const menuMap: IMenuItem[] = [
  {
    name: 'Hello'.path: '/'.zh: 'Welcome page',},];const menus = defineComponent({
  setup() {
    const route = useRoute();
    const state = reactive({
      currentKey: [] as string[],}); watch(route,(value) = > {
      const keys = value.path;
      state.currentKey = [keys];
      console.log(state.currentKey);
    });
    return () = > (
      <Menu mode="inline" selectedKeys={state.currentKey}>
        {menuMap.map((item) => (
          <Menu.Item key={item.path}>
            <RouterLink to={item.path}>
              {item.name}
              &nbsp;{item.zh}
            </RouterLink>
          </Menu.Item>
        ))}
      </Menu>); }});export default menus;

Copy the code

app.vue

<script setup lang="ts">
import { Layout } from 'ant-design-vue'
import Menus from './page/Menus'
import { RouterView } from 'vue-router'
const { Header, Sider, Content } = Layout;
import './style/index.css'
// import { Button } from './components/index'
// This starter template is using Vue 3 <script setup> SFCs
// Check out https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup
</script>

<template>
  <Layout style="height:100%">
    <Header style="text-align:left;">
      <h1 style="color:#fff; display: flex; align-items: center;">
        MY-UI
      </h1>
    </Header>
    <Layout>
      <Sider>
        <Menus />
      </Sider>
      <Content>
        <RouterView />
      </Content>
    </Layout>
  </Layout>
</template>
Copy the code

2. Component preview + Documentation MD

The HelloPage above gives you a preview of how the Hello component will look, but that’s the basics. Next we need to document the component

// packages/components/Hello/readme.md
# Hello

# configuration items| | parameters shows that the default value | | type version | | | -- - | -- - | -- -- -- -- -- - | -- -- -- -- -- - | -- - | | in the | -- - | string | - | - |Copy the code

Next, let md be displayed on the page. There is a very useful library called viet-plugin-md. Change viet.config.ts

import Markdown from 'vite-plugin-md'
export default defineConfig({
  plugins: [
    vue({ include: [/\.vue$/./\.md$/] }),
    vueJsx(),
    Markdown()
  ],
}
Copy the code

TSX is used to display our component + source + MD. To highlight the source, we need prismJS

yarn add prismjs -D
Copy the code
// Preview.tsx
import { defineComponent, onMounted } from 'vue';
import { Collapse } from 'ant-design-vue';
import Prism from 'prismjs';
import 'prismjs/themes/prism-coy.css';

const Preview = defineComponent({
  props: ['sourceCode'.'language'.'md'].setup(props, { slots }) {
    onMounted(() = > {
      Prism.highlightAll();
    });

    return () = > (
      <div>
        <Collapse>
          <Collapse.Panel
            style={{
              textAlign: 'left'}}header={
              <div
                style={{
                  background: '#fff',
                  padding: '16px'}}onClick={(e)= > e.stopPropagation()}
              >
                {slots.default && slots.default()}
              </div>
            }
          >
            <pre class="language-html">
              <code class={props.language| | 'language-javascript'} >
                {props.sourceCode}
              </code>
            </pre>
          </Collapse.Panel>
        </Collapse>

        {props.md}
      </div>); }});export default Preview;

Copy the code

Finally, let’s modify the original Page/ hello.tsx

import { defineComponent } from 'vue';
import { Hello } from '.. /.. /packages/components';
import MD from '.. /.. /packages/components/Hello/readme.md';

import Preview from './Preview';

const HelloPage = defineComponent({
  setup() {
    return () = > (
      <div>
        
            <Preview sourceCode={` <Hello title="123"></Hello>`} md={<MD />} ><Hello title="123"></Hello>
            </Preview>

      </div>); }});export default HelloPage;

Copy the code

The hello. TSX reference path to the Hello component is a bit ugly, so let’s change it to

import { Hello } from 'my-ui';
import MD from 'my-ui/Hello/readme.md';
Copy the code

In this case, you need to configure resolve. Alias for vite.config.ts and add paths corresponding to tsconfig.json

// vite.config.ts
resolve: {
    alias: {
      'my-ui': '/packages/components'}}Copy the code
{
  "compilerOptions": {
    "baseUrl": ". /"."paths": {
      "my-ui": ["packages/components"]."my-ui/*": ["packages/components/*"]}}}Copy the code

Finally, optimize the markdown presentation by adding a style file style/index.css

.markdown-body {
  padding: 16px;
}
.markdown-body h1 {
  text-align: left;
}
.markdown-body table {
    width: 100%;
    min-width: 720px;
    margin: 2em 0;
    font-size: 13px;
    font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, Courier,
      monospace;
    line-height: 1.5;
    border: 1px solid #e8e8e8;
  }
  .markdown-body table th..markdown-body table td {
    padding: 12px;
    border-color: #e8e8e8;
    border-width: 1px 0;
  }
  .markdown-body table th {
    padding-top: 14px;
    border-width: 0 0 2px 0;
    background-color: #e8e8e8;
  }
  .markdown-body table tbody tr {
    -webkit-transition: all 0.3 s;
    transition: all 0.3 s;
  }
  .markdown-body table tbody tr:hover {
    background: rgba(60.90.100.0.04);
  }
  .markdown-body table td:first-child {
    width: 20%;
    color: # 595959;
    font-weight: 600;
  }
  .markdown-body table td:nth-child(3) {
    width: 22%;
    color: #c41d7f;
    font-size: 13px;
    word-break: break-all;
  }
  .markdown-body table td:nth-child(4) {
    width: 16%;
    font-size: 13px;
  }
  .markdown-body hr {
    margin: 12px 0;
  }
  
Copy the code

The final effect is achieved!

It may be relatively ugly, but the styling and preview page can be tweaked

subsequent

There are still some things that can be done about the component library

  • internationalization
  • Component creation scaffolding
  • Realize real-time modification preview of components, etc