support custom theme ci

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # HOW TO CONTRIBUTE
 
-* 1. Welcome your pr! Before pr, talk about situations in the [issue](https://github.com/MuYunyun/create-react-doc/issues/new) firstly. If the situation is reasonable, go to the next step;
-* 2. Switch to the new branch based main, submit the pr with after finishing the feature.
+1. Welcome your pr! Before pr, talk about situations in the [issue](https://github.com/MuYunyun/create-react-doc/issues/new) firstly. If the situation is reasonable, go to the next step;
+2. Switch to the new branch based main, submit the pr to branch `qa/latest` after finishing development.
 
 ## DEV
 
@@ -14,3 +14,11 @@ $ yarn && yarn bootstrap && yarn start
 ```
 
 And now you can see the document is running at http://localhost:3000.
+
+## Test
+
+After merging pr to qa/latest and publish beta package. You should verify the feature/bugfix with following bash:
+
+```js
+yarn add create-react-doc@beta
+```

config.yml

@@ -5,12 +5,13 @@ title: Create React Doc
 
 # Menu dir
 ## you can also set detailed dir, such as BasicSkill/css
-menu: docs/快速上手.md,docs/站点发布.md,docs/config.yml.md,docs/高阶用法.md,docs/其它工具.md
+menu: docs/快速上手.md,docs/站点发布.md,docs/config.yml.md,docs/高阶用法.md,docs/自定义主题.md,docs/其它工具.md
 ## set init open menu keys
 # menuOpenKeys:
 
 # site theme
-theme: crd-seed
+devTheme: packages/crd-seed/index
+# theme: crd-seed
 
 # Github
 ## if you want to editing pages on github, you should config these arguments.

docs/config.yml.md

@@ -4,15 +4,16 @@
 
 它支持的属性如下
 
-|     属性名     |             作用              |    类型     |   默认   |
-| :------------: | :---------------------------: | :---------: | :------: |
-|     title      |            站点名             |   string    |          |
-|      menu      | 作为站点菜单的文件/文件夹路径 |   string    |          |
-|  menuOpenKeys  |   默认展开菜单的文件夹路径    |   string    |          |
-|     theme      |           使用主题            |   string    | crd-seed |
-|      user      |         Github 用户名         |   string    |          |
-|      repo      |         Github 项目名         |   string    |          |
-|    language    |           站点语言            | en \| zh-cn |    en    |
-| github-ribbons | 是否在右上角显示 github 丝带  |   boolean   |  false   |
+|     属性名     |               作用                |    类型     |   默认   |
+| :------------: | :-------------------------------: | :---------: | :------: |
+|     title      |              站点名               |   string    |          |
+|      menu      |   作为站点菜单的文件/文件夹路径   |   string    |          |
+|  menuOpenKeys  |     默认展开菜单的文件夹路径      |   string    |          |
+|      user      |           Github 用户名           |   string    |          |
+|      repo      |           Github 项目名           |   string    |          |
+|    language    |             站点语言              | en \| zh-cn |    en    |
+| github-ribbons |   是否在右上角显示 github 丝带    |   boolean   |  false   |
+|     theme      |             使用主题              |   string    | crd-seed |
+|    devTheme    | 开发自定义主题时, 需设置其为 true |   string    | ./index  |
 
 详细用法可以参考 [config.yml]](https://github.com/MuYunyun/blog/blob/main/config.yml)。

docs/自定义主题.md

@@ -1,7 +1,89 @@
-### 替换主题
+### 使用自定义主题
 
-在 `config.yml` 文件中的 theme 替换为你想使用的主题即可。
+切换主题非常简单, 只需要将根目录文件 `config.yml` 中的 `theme` 更改为您想使用的主题即可。
 
 ```diff
 + theme: custom-theme
+```
+
+### 如何开发自定义主题包
+
+create-react-doc 脚手架提供了脚本命令 `react-doc theme` 用来一键创建主题包开发环境。
+
+![](http://with.muyunyun.cn/2e4a4b11f96c0d38759700c05fe96267.gif)
+
+```bash
+// 安装 create-react-doc
+yarn add create-react-doc -g
+// 执行 `react-doc theme` 并输入主题包名字
+react-doc theme
+```
+
+进入到所创建主题目录, 执行 `yarn && yarn start`, 浏览器会自动打开浏览器, 并在屏幕中央显示 `Welcome to your own theme`。
+
+![](http://with.muyunyun.cn/1721111f30373c7dbca268db4b0d824f.jpg)
+
+恭喜你, 此时你已经将主题开发环境配置完成。接着便可以开始愉快地定制个人主题了。
+
+在所创建的主题项目中支持使用 `React 17` 以及 `less` 语法。
+
+```js
+import { Switch, Route } from 'react-router-dom'
+import styles from './index.less'
+
+const CustomTheme = (props: CustomThemeProps) => {
+  return (
+    <Switch>
+      <Route
+        path="/"
+        render={() => <div className={styles.center}>Welcome to your own theme</div>}
+      />
+    </Switch>
+  )
+}
+
+export default CustomTheme
+```
+
+CustomThemeProps 的接口类型定义如下, 自定义主题时可以自由使用它们。
+
+```js
+interface CustomThemeProps {
+  menuSource: {
+    // 文件名称 eg: '快速上手.md'
+    name: string
+    // 文件扩展名 eg: '.md'
+    extension: string
+    // 文件路径 eg: '/docs/快速上手.md'
+    path: string
+    // 路由路径 eg: ‘/快速上手’
+    routePath: string
+    // 文件大小 eg: 924
+    size: number
+    // 文件类型 eg: 'file'
+    type: string
+    // 文件创建日期 eg: '2020-11-11'
+    birthtime: string
+    // 文件修改日期 eg: '2021-01-14'
+    mtime: string
+  }[]
+}
+```
+
+此外在自定义主题文件中可以自由使用由 webpack 注入的 `DOCSCONFIG` 对象中的变量, DOCSCONFIG 中的变量与项目根目录中的 `config.yml` 文件变量一一对应。
+
+比如 `config.yml` 配置如下所示:
+
+```bash
+menu: Introduction
+theme: crd-seed
+user: muyunyun
+repo: https://github.com/MuYunyun/create-react-doc
+language: en
+```
+
+则主题项目中则可以通过如下方式获取到 `config.yml` 配置属性。
+
+```js
+const { menu, theme, user,  } = DOCSCONFIG || {}
 ```

injectLogic/index.js

@@ -1,33 +1,33 @@
 /* eslint-disable no-empty */
 // perf inject logic only once
-const inject = () => {};
+const inject = () => {}
 
 // perf injectWithPathname logic every pathname changes
 const injectWithPathname = (pathname) => {
   // demo for using mathjax. see https://github.com/MuYunyun/create-react-doc/issues/63
-  if (pathname !== '/高阶用法') return;
+  if (pathname !== '/高阶用法') return
   window.MathJax = {
     tex: {
       inlineMath: [['$', '$'], ['\\(', '\\)']],
     },
     svg: {
       fontCache: 'global',
     },
-  };
-  const script = document.createElement('script');
-  script.src = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js';
-  const tag = 'mathjax';
-  script.id = tag;
-  script.async = true;
-  const scriptNode = document.getElementById(tag);
+  }
+  const script = document.createElement('script')
+  script.src = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js'
+  const tag = 'mathjax'
+  script.id = tag
+  script.async = true
+  const scriptNode = document.getElementById(tag)
   try {
     if (!scriptNode) {
-      document.head.appendChild(script);
+      document.head.appendChild(script)
     } else {
-      scriptNode.remove();
-      document.head.appendChild(script);
+      scriptNode.remove()
+      document.head.appendChild(script)
     }
   } catch (error) {}
-};
+}
 
-module.exports = { inject, injectWithPathname };
+module.exports = { inject, injectWithPathname }

lerna.json

@@ -7,7 +7,7 @@
       ]
     },
     "publish": {
-      "allowBranch": "main",
+      "allowBranch": ["main", "qa/latest"],
       "message": "chore: publish"
     }
   },

packages/create-react-doc/index.js

@@ -4,13 +4,15 @@ const path = require('path')
 const program = require('commander')
 const {
   initProject,
+  initTheme,
   initCache,
   Deploy,
   paths,
   getDocsConfig,
   Servers,
   Build,
 } = require('crd-scripts')
+const input = require('@inquirer/input')
 const pkg = require('./package.json')
 
 program
@@ -19,6 +21,7 @@ program
   .option('start', 'Documents generated.')
   .option('build', 'Build the documents generated.')
   .option('deploy', 'Deploy site to gh-pages.')
+  .option('theme', 'Create a new theme')
   .option('-o, --output <path>', 'Writes the compiled file to the disk directory.', '.crd-dist')
   .option('-p, --port [number]', 'The port.', 3000)
   .option('--host [host]', 'The host.', '0.0.0.0')
@@ -34,7 +37,23 @@ program
   })
   // the third value in process.argv is the value we want.
   .parse(process.argv)
-if (!program.start && !program.build && !program.deploy) return initProject(program)
+
+const { start, build, deploy, theme } = program
+
+if (!start && !build && !deploy && !theme) return initProject(program)
+
+if (theme) {
+  return input({
+    message: "What's the theme name?",
+    validate: (inputThemeName) => {
+      if (inputThemeName.length === 0) return 'Please input correct theme name'
+      return true
+    },
+  }).then((themeName) => {
+    initTheme(themeName)
+  })
+}
+
 // create-react-doc tool root dir.
 // program.crdPath = path.join(__dirname, '../');
 // all markdown dir
@@ -44,7 +63,7 @@ program.output = path.join(process.cwd(), program.output)
 const docsConfig = getDocsConfig()
 
 // assign all the markdown dir
-if (program.start || program.build) {
+if (start || build) {
   fs.existsSync(paths.docsReadme) &&
     program.markdownPaths.push(paths.docsReadme)
 
@@ -56,13 +75,13 @@ if (program.start || program.build) {
       )
 }
 
-if (program.build && fs.pathExistsSync(paths.docsBuildDist)) {
+if (build && fs.pathExistsSync(paths.docsBuildDist)) {
   // clean dir
   fs.emptyDirSync(paths.docsBuildDist)
 }
 
 // deploy code to special git repo and branch.
-if (program.deploy) {
+if (deploy) {
   return Deploy(program, docsConfig)
 }
 
@@ -81,7 +100,7 @@ program.markdownPaths.forEach((item) => {
 if (isExists) {
   fs.ensureDirSync(paths.cacheDirPath)
   initCache(program, () => {
-    if (program.build) {
+    if (build) {
       Build(program)
     } else {
       Servers(program)

packages/create-react-doc/package.json

@@ -24,6 +24,7 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@inquirer/input": "^0.0.13-alpha.0",
     "commander": "^2.12.2",
     "crd-scripts": "^0.2.27",
     "crd-templates": "^0.2.26",

packages/scripts/index.js

@@ -1,4 +1,5 @@
 const initProject = require('./src/commands/initProject')
+const initTheme = require('./src/commands/initTheme')
 const initCache = require('./src/utils/initCache')
 const Servers = require('./src/server')
 const Build = require('./src/build')
@@ -8,6 +9,7 @@ const { getDocsConfig } = require('./src/utils')
 
 module.exports = {
   initProject,
+  initTheme,
   initCache,
   Servers,
   Build,

packages/scripts/src/commands/initProject.js

@@ -21,11 +21,13 @@ module.exports = function (params) {
     fs.ensureDirSync(outDir)
   }
 
+  const defaultTemplatePath = `${paths.templatePath}/default`
+
   // copy template, see https://github.com/MuYunyun/create-react-doc/issues/50
-  if (!fs.pathExistsSync(paths.defaultTemplatePath)) {
+  if (!fs.pathExistsSync(defaultTemplatePath)) {
     execSync('mkdir temp && cd temp && yarn add crd-templates -D')
   }
-  copyTemplate(paths.defaultTemplatePath, outDir, {
+  copyTemplate(defaultTemplatePath, outDir, {
     name: projectName,
     crdVersion: CRD_VERSION,
   }, (err, createdFiles) => {
@@ -34,7 +36,7 @@ module.exports = function (params) {
       log(`  ${'create'.green} ${createdFile.replace(paths.projectPath, '')}`)
     })
     // this is to hack https://github.com/yoshuawuyts/copy-template-dir/issues/16
-    execSync(`cp -r ${paths.defaultTemplatePath}/.github ${outDir}`)
+    execSync(`cp -r ${defaultTemplatePath}/.github ${outDir}`)
     execSync('rm -rf temp')
     log('\n  initialization finished!\n'.green)
     const cmdstr = `cd ${projectName} && yarn && yarn start`.cyan

packages/scripts/src/commands/initTheme.js

@@ -0,0 +1,43 @@
+/**
+ * This file is to init theme quickly.
+ */
+const path = require('path')
+const { execSync } = require('child_process')
+const fs = require('fs-extra')
+const copyTemplate = require('copy-template-dir')
+const paths = require('../conf/path')
+
+const log = console.log; // eslint-disable-line
+
+// eslint-disable-next-line no-unused-vars
+module.exports = function (themeName) {
+  const outDir = path.join(paths.projectPath, themeName)
+
+  const crdpkg = require(paths.crdPackage); // eslint-disable-line
+  // replace the last vertion with x, so it'll install autoly when the last vertion changes.
+  const CRD_VERSION = crdpkg.version.split('.').slice(0, 2).concat('x').join('.')
+
+  // clear output dir
+  if (!fs.pathExistsSync(outDir)) {
+    fs.ensureDirSync(outDir)
+  }
+
+  const defaultTemplatePath = `${paths.templatePath}/theme/default`
+
+  if (!fs.pathExistsSync(defaultTemplatePath)) {
+    execSync('mkdir temp && cd temp && yarn add crd-templates -D')
+  }
+  copyTemplate(defaultTemplatePath, outDir, {
+    name: themeName,
+    crdVersion: CRD_VERSION,
+  }, (err, createdFiles) => {
+    if (err) return log(`Copy Tamplate Error: ${err} !!!`.red)
+    createdFiles.sort().forEach((createdFile) => {
+      log(`  ${'create'.green} ${createdFile.replace(paths.projectPath, '')}`)
+    })
+    execSync('rm -rf temp')
+    log('\n  initialization finished!\n'.green)
+    const cmdstr = `cd ${themeName} && yarn && yarn start`.cyan
+    log(`  Run the ${cmdstr} to start the website.\n\n`)
+  })
+}