mt51 - Build doc site

README.md

@@ -1,33 +1,33 @@
 # **Vant React**
 
-[![npm version](https://badge.fury.io/js/vant-react.svg)](https://badge.fury.io/js/vant-react)
-[![NPM](https://img.shields.io/npm/l/vant-react)](LICENSE)
-![Test CI](https://github.com/mxdi9i7/vant-react/workflows/Test%20CI/badge.svg)
-[![Netlify Status](https://api.netlify.com/api/v1/badges/30ddabc0-3eb6-4530-ab08-58db247a2b48/deploy-status)](https://vant.bctc.io)
-[![Storybook](https://cdn.jsdelivr.net/gh/storybookjs/brand@master/badge/badge-storybook.svg)](https://vant.bctc.io)
+<img src="https://badge.fury.io/js/vant-react.svg" alt="npm version" style="width: 126px; height: 20px;" />
+<img src="https://img.shields.io/npm/l/vant-react" alt="NPM" style="width: 78px" />
+<img src="https://github.com/mxdi9i7/vant-react/workflows/Test%20CI/badge.svg" alt="Test CI" style="width: 126px; height: 20px;" />
+<img src="https://api.netlify.com/api/v1/badges/30ddabc0-3eb6-4530-ab08-58db247a2b48/deploy-status" alt="Netlify Status" style="width: 126px; height: 20px;" />
+<img src="https://cdn.jsdelivr.net/gh/storybookjs/brand@master/badge/badge-storybook.svg" alt="Storybook" style="width: 82px; height: 20px;" />
 
 Lightweight Mobile UI Components built on Typescript and React in under 2kb!
 
-## **Features**
+### **Features**
 
 - Support Typescript
 - 60+ Reusable components
 - 100% Storybook coverage: [https://vant.bctc.io](https://vant.bctc.io)
 - Extensive documentation and demos
 
-## Install
+### Install
 
-```text
+``` bash
 # Using npm
 npm i vant-react -S
 
 # Using yarn
 yarn add vant-react
 ```
 
-## Quickstart
+### Quickstart
 
-```text
+``` js
 import React from 'react';
 import { Button } from 'vant-react';
 import 'vant-react/dist/index.css';

docs/changelog.zh-CN.md

@@ -0,0 +1 @@
+## 更新日志

docs/contribute.zh-CN.md

@@ -0,0 +1 @@
+## 如何参与

docs/locale.zh-CN.md

@@ -0,0 +1 @@
+## 国际化

docs/markdown.zh-CN.md

@@ -0,0 +1,23 @@
+## 组件文档如何编写
+
+### 介绍
+
+文档网站分为文档展示和demo展示，文档通过收集组件目录下的 `README.[locale].md`, ` locale ` 的值是国际化的标识，和 ` ./site/configs/nav.config.js ` 中的 ` key `保持一致。
+
+### 使用
+
+文档网站替换了storybook 自带的文档生成，在运行 ` yarn storybook ` 自动收集文档和demo的信息，生成对应的页面，并且自动在浏览器中打开页面，对于开发过程中的使用基本上没有太大的影响
+
+### 添加文档配置
+
+在` ./site/configs/nav.config.js ` 添加新的文档页面配置，包括标题和` path `，标题会在左侧导航展示，` path`用来生成页面路由.
+
+### 添加文档文件
+
+在组件目录中新增 `README.zh-CN.md`，用来展示组件文档，使用 ` markdown ` 文件语法。
+
+### 添加文档 demo 文件
+
+在组件目录中新增 ` demo/index.tsx ` 作为文档的页面，然后就可以愉快的编写 demo 了。
+由于每次在运行` yarn storybook `时才会收集所有文档信息生成文档配置，所以每次新增的文档文件需要重新运行` yarn storybook `。
+

docs/quickstart.zh-CN.md

@@ -0,0 +1,24 @@
+## 快速上手
+
+### Install
+
+``` bash
+# Using npm
+npm i vant-react -S
+
+# Using yarn
+yarn add vant-react
+```
+
+### Quickstart
+
+``` js
+import React from 'react';
+import { Button } from 'vant-react';
+import 'vant-react/dist/index.css';
+
+const App = () => {
+    return (
+        <Button text='Hello World' />
+    );
+};

package.json

@@ -20,11 +20,10 @@
     "test:lint": "run-s lint",
     "test:unit": "cross-env CI=1 react-scripts test --env=jsdom --passWithNoTests",
     "test:watch": "react-scripts test --env=jsdom",
-    "predeploy": "cd example && yarn install && yarn run build",
-    "deploy": "gh-pages -d example/build",
+    "deploy": "cd site && yarn deploy",
     "lint": "eslint --ext .tsx ./src",
     "lint:watch": "esw --watch --fix --ext .tsx ./src",
-    "storybook": "start-storybook -p 9009",
+    "storybook": "cd site && yarn dev && start-storybook",
     "build-storybook": "build-storybook"
   },
   "peerDependencies": {

site/.editorconfig

@@ -0,0 +1,23 @@
+root = true
+
+[*]
+indent_style = space
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.js]
+indent_size = 2
+
+[*.vue]
+indent_size = 2
+
+[*.css]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

site/.eslintrc.js

@@ -0,0 +1,8 @@
+module.exports = {
+  root: true,
+  env: {
+    browser: true,
+  },
+  extends: ['../eslintrc.react.js.base.js'],
+  ignorePatterns: ['node_modules/', 'dist/', 'src/nav.js'],
+};

site/.gitignore

@@ -0,0 +1,5 @@
+dist
+node_modules
+configs/site-desktop-shared.js
+configs/site-mobile-shared.js
+.awcache

site/README.md

@@ -0,0 +1,19 @@
+## 开发
+
+```bash
+yarn
+
+npm run dev
+```
+
+浏览器打开[http://127.0.0.1:4396](http://127.0.0.1:4396)
+
+## 部署
+
+`yarn run deploy`
+
+默认情况下生成的静态文件会部署到当前仓库的 `gh-pages` 分支上，环境变量来修改仓库。
+
+## Notes
+
+Github doesn't support SPAs, the `404.html` is a workaround. Do NOT remove it.

site/babel.config.js

@@ -0,0 +1,40 @@
+module.exports = function(api) {
+  api.cache(true);
+
+  const envSpecificPlugins =
+    process.env.NODE_ENV === 'development'
+      ? ['react-loadable/babel', 'react-hot-loader/babel']
+      : [];
+
+  return {
+    presets: [
+      [
+        '@babel/preset-env',
+        {
+          useBuiltIns: 'entry',
+          corejs: 3,
+        },
+      ],
+      '@babel/preset-react',
+    ],
+
+    plugins: [
+      'transform-property-literals',
+      'transform-member-expression-literals',
+      '@babel/plugin-proposal-export-namespace-from',
+      '@babel/plugin-proposal-export-default-from',
+      '@babel/plugin-proposal-class-properties',
+      '@babel/plugin-syntax-dynamic-import',
+      [
+        '@babel/plugin-transform-runtime',
+        {
+          corejs: false,
+          helpers: true,
+          regenerator: true,
+          useESModules: false,
+        },
+      ],
+      ...envSpecificPlugins,
+    ],
+  };
+};

site/configs/doc.config.js

@@ -0,0 +1,6 @@
+import pkgJson from '../../package.json';
+
+export const { version } = pkgJson;
+
+export const versions = [version];
+

site/configs/nav.config.js

@@ -0,0 +1,119 @@
+
+const github = 'https://github.com/mxdi9i7/vant-react';
+
+module.exports = {
+  'zh-CN': {
+    header: {
+      logo: {
+        image: 'https://img.yzcdn.cn/vant/logo.png',
+        title: 'Vant React',
+        href: '#/'
+      },
+      nav: {
+        lang: {
+          text: 'En',
+          from: 'zh-CN',
+          to: 'en-US'
+        },
+        logoLink: [
+          {
+            image: 'https://b.yzcdn.cn/vant/logo/github.svg',
+            url: 'github'
+          }
+        ]
+      }
+    },
+
+    nav: [
+      {
+        name: '开发指南',
+        list: [
+          {
+            title: '快速上手',
+            path: 'quickstart',
+          },
+          {
+            title: '更新日志',
+            path: 'changelog',
+          },
+          {
+            title: '如何参与',
+            path: 'contribute',
+          },
+          {
+            title: '文档规范',
+            path: 'markdown',
+          },
+          {
+            title: '国际化',
+            path: 'locale',
+          }
+        ],
+      },
+      {
+        name: '基础组件',
+        list: [
+          {
+            title: 'Button 按钮',
+            path: 'button',
+          },
+          {
+            title: 'Cell 单元格',
+            path: 'cell',
+          },
+          {
+            title: 'Field 输入框',
+            path: 'field',
+          },
+          {
+            title: 'Icon 图标',
+            path: 'icons',
+          },
+          {
+            title: 'Navbar 导航栏',
+            path: 'navbar',
+          },
+          {
+            title: 'Popup 弹出层',
+            path: 'popup',
+          },
+          {
+            title: 'Rate 评分',
+            path: 'rate',
+          },
+          {
+            title: 'Search 搜索',
+            path: 'search',
+          },
+          {
+            title: 'Tag 标记',
+            path: 'tag',
+          }
+        ],
+      },
+    ]
+  },
+  'en-US': {
+    header: {
+      logo: {
+        image:
+          'https://img.yzcdn.cn/vant/logo.png',
+        title: 'Vant React',
+        href: '#/'
+      },
+      nav: {
+        lang: {
+          text: '中文',
+          from: 'en-US',
+          to: 'zh-CN'
+        },
+        logoLink: [
+          {
+            image: 'https://b.yzcdn.cn/vant/logo/github.svg',
+            url: 'github'
+          }
+        ]
+      }
+    },
+  }
+};

site/constants.js

@@ -0,0 +1,8 @@
+exports.prefix = getPrefix();
+
+function getPrefix() {
+  if (process.env.NODE_ENV === 'production') {
+    return '/vant-react/';
+  }
+  return '/';
+}

site/markdown-loader/card-wrapper.js

@@ -0,0 +1,16 @@
+module.exports = function cardWrapper(html) {
+  const group = html
+    .replace(/<h3/g, ':::<h3')
+    .replace(/<h2/g, ':::<h2')
+    .split(':::');
+
+  return group
+    .map(fragment => {
+      if (fragment.indexOf('<h3') !== -1) {
+        return `<div class="card">${fragment}</div>`;
+      }
+
+      return fragment;
+    })
+    .join('');
+};

site/markdown-loader/highlight.js

@@ -0,0 +1,9 @@
+const hljs = require('highlight.js');
+
+module.exports = function highlight(str, lang) {
+  if (lang && hljs.getLanguage(lang)) {
+    return hljs.highlight(lang, str, true).value;
+  }
+
+  return '';
+};