support generating uuid

README.md

@@ -1,3 +1,6 @@
+<!--
+abbrlink: s31w9gd1
+-->
                                                      _.-"\
                                                 _.-"      \
                                               ,-"          \
@@ -29,11 +32,13 @@
 * 开箱即用: 通过指定目录或文档, 一键生成文档、博客站点, 无需关心站点环境配置信息。
 * 性能: 通过`预渲染`、`懒加载`大幅提升站点加载速度。
 * 基于 mdx: 支持在 markdown 中`书写 React 组件`、数学公式等。
-* 搜索引擎优化: `支持 SEO`, 让文档更易被搜索。相关文档: [SEO 在 SPA 站点中的实践](https://github.com/MuYunyun/blog/issues/84)
-* 个性化: 支持[自定义主题](http://muyunyun.cn/create-react-doc/%E4%B8%BB%E9%A2%98/%E8%87%AA%E5%AE%9A%E4%B9%89%E4%B8%BB%E9%A2%98)。
+* 搜索引擎优化:
+  * 支持 SEO, 让文档更易被搜索。
+  * 支持短链，以让链接持久化。
+* 个性化: 支持[自定义主题](https://muyunyun.cn/create-react-doc/9f41fc98)。
 * 工作流: 集成 Github action, 支持自动化打包、发布站点。
 
-> [快速上手](http://muyunyun.cn/create-react-doc/%E5%BF%AB%E9%80%9F%E4%B8%8A%E6%89%8B)
+> [快速上手](https://muyunyun.cn/create-react-doc/290a4219)
 
 ## 主题
 
@@ -49,9 +54,9 @@ create-react-doc 提供了官方默认主题 [crd-seed](https://github.com/MuYun
 * [blog](https://github.com/MuYunyun/blog), [站点](http://muyunyun.cn/blog)
   * ![](http://with.muyunyun.cn/ec330b8ac2175c828be41f446f9f9619.jpg)
   * ![](http://with.muyunyun.cn/2e7440e4256debda2d73a4e6392c7146.jpg-300)
-* [diana](https://github.com/MuYunyun/diana), [站点](https://muyunyun.cn/diana/)
+* [diana](https://github.com/MuYunyun/diana)
 
-如果您想定制化或者分享个人主题, 可以参考[自定义主题](http://muyunyun.cn/create-react-doc/自定义主题)章节。
+如果您想定制化或者分享个人主题, 可以参考[自定义主题](https://muyunyun.cn/create-react-doc/9f41fc98)。
 
 ## 快速上手
 
@@ -87,7 +92,7 @@ yarn create react-doc doc
 
 ## 站点发布
 
-在 [快速上手](http://muyunyun.cn/create-react-doc/快速上手) 一节中介绍了如何快速搭建站点, 本节将介绍如何将搭建好的站点打包、发布到 gh-pages。
+在 [快速上手](https://muyunyun.cn/create-react-doc/290a4219) 一节中介绍了如何快速搭建站点, 本节将介绍如何将搭建好的站点打包、发布到 gh-pages。
 
 ### 自动打包发布到 gh-pages (推荐)
 
@@ -106,4 +111,13 @@ git remote add origin https://github.com/用户或组织名/项目名.git
 git push -u origin main
 ```
 
-> 更多内容可以访问 [站点发布](http://muyunyun.cn/create-react-doc/站点发布)、[高阶用法](http://muyunyun.cn/create-react-doc/高阶用法)、[其它工具](http://muyunyun.cn/create-react-doc/其它工具) 等章节。
+## 更多内容
+
+* [站点发布](http://muyunyun.cn/create-react-doc/ude9296y)
+* [高阶用法](http://muyunyun.cn/create-react-doc/9v9ug9h8)
+* [其它工具](http://muyunyun.cn/create-react-doc/292h2c5k)
+* [Front-matter](http://muyunyun.cn/create-react-doc/49g6b239)
+
+## 扩展阅读
+
+* [SEO 在 SPA 站点中的实践](https://github.com/MuYunyun/blog/issues/84)

config.yml

@@ -1,4 +1,4 @@
-# create-react-doc configuration, see https://github.com/MuYunyun/create-react-doc##config.yml
+# create-react-doc configuration.
 
 # Site
 title: Create React Doc
@@ -33,9 +33,11 @@ domain: https://muyunyun.cn
 seo:
   google: true
 
-
 # Available values: en | zh-cn
 language: en
 
 # Inject Custom Logic
-inject: injectLogic/index.js
+inject: injectLogic/index.js
+
+# Use abbrlink
+abbrlink: true

docs/Front-matter.md

@@ -17,3 +17,25 @@ abbrlink: 290a4219
 | 参数     | 描述                                                            | 默认值 |
 | :------- | :-------------------------------------------------------------- | :----- |
 | abbrlink | 短链。用于指定页面路由展示为指定短链，使用短链有助于 SEO 搜索。 |        |
+
+## 链接持久化
+
+如果存在以下场景需求，可以考虑使用短链作为 URL 展示以进行优化。
+
+* 需要链接持久化以更好地 SEO。
+* URL 链接中存在中文会被转码展示。
+* 经常调整文档的路径与文件名。
+
+### 如何使用短链
+
+在 `config.yml` 增加配置 `abbrlink: true`
+
+```diff
++ abbrlink: true
+```
+
+随后在控制台执行 `react-doc generate` 即可给 menu 配置属性中的所有文章目录文件加上短链资源。
+
+```bash
+react-doc generate // 一键给所有文章加上短链
+```

docs/主题/默认主题.md

@@ -1,3 +1,7 @@
+<!--
+abbrlink: 85li8wdd
+-->
+
 ## 默认主题
 
 create-react-doc 的默认主题为 [crd-seed](https://github.com/MuYunyun/create-react-doc/tree/main/packages/crd-seed)。该主题有以下特性:

docs/书写组件.md

@@ -1,3 +1,7 @@
+<!--
+abbrlink: lx1euo1b
+-->
+
 import { Button } from '../components/index.jsx'
 
 ## 书写组件

docs/其它工具.md

@@ -1,3 +1,7 @@
+<!--
+abbrlink: 292h2c5k
+-->
+
 ## 其它工具
 
 ### crd-leetcode-cli

docs/数学公式.md

@@ -1,3 +1,9 @@
+<!--
+abbrlink: slkczvi1
+title: 数学公式
+date: 2019-05-12 13:23:44
+-->
+
 ## 数学公式
 
 支持在 `$$` 与 `$$` 之间书写 latex 数学公式即能显示在网页上。

docs/更新日志.md

@@ -1,7 +1,19 @@
+<!--
+abbrlink: 179nqpxt
+-->
+
 # CHANGELOG
 
 `create-react-doc` 严格遵循 [Semantic Versioning 2.0.0](http://semver.org/lang/zh-CN/) 语义化版本规范。
 
+### 1.5.0
+
+`2021-10-13`
+
+- **Feature**
+
+  - 🚀 支持 react-doc generate 命令，给 md 文件自动补全短链。[issue](https://github.com/MuYunyun/create-react-doc/issues/87)、[mr](https://github.com/MuYunyun/create-react-doc/pull/194)
+
 ### 1.4.0
 
 `2021-10-08`

docs/站点发布.md

@@ -1,3 +1,7 @@
+<!--
+abbrlink: ude9296y
+-->
+
 ## 站点发布
 
 在 [快速上手](http://muyunyun.cn/create-react-doc/%E5%BF%AB%E9%80%9F%E4%B8%8A%E6%89%8B) 一节中介绍了如何快速搭建站点, 本节将介绍如何将搭建好的站点打包、发布到 gh-pages。

docs/高阶用法.md

@@ -1,3 +1,7 @@
+<!--
+abbrlink: 9v9ug9h8
+-->
+
 ## 高阶用法
 
 与 git 文件结构类似, 如果在展示的文件夹中有私有文件不方便展示在文档站点, 可以在 `.gitignore` 文件中设置过滤文件, 这样它们就不会展示在文档站点中了。eg: [.gitignore](https://github.com/MuYunyun/blog/blob/main/.gitignore)

packages/scripts/index.js → packages/crd-scripts/index.js

@@ -4,6 +4,7 @@ const initCache = require('./src/utils/initCache')
 const Servers = require('./src/server')
 const Build = require('./src/build')
 const Deploy = require('./src/deploy')
+const Generate = require('./src/generate')
 const paths = require('./src/conf/path')
 
 module.exports = {
@@ -13,5 +14,6 @@ module.exports = {
   Servers,
   Build,
   Deploy,
+  Generate,
   paths,
 }

packages/scripts/src/conf/node-directory-tree.js → packages/crd-scripts/src/conf/node-directory-tree.js

@@ -3,6 +3,7 @@ const fs = require('fs')
 const PATH = require('path')
 const YAML = require('yamljs')
 const { execSync } = require('child_process')
+const { replaceForFrontMatter, generateRandomId } = require('crd-utils')
 const { getDigitFromDir, timeFormat } = require('../utils')
 
 const constants = {
@@ -37,14 +38,14 @@ function safeReadDirSync(path) {
   return dirData
 }
 
-/**
- * build directory Tree, fork from https://github.com/mihneadb/node-directory-tree
+/** build directory Tree, fork from https://github.com/mihneadb/node-directory-tree
  * path: path for file
  * options: {
  *   exclude: RegExp|RegExp[] - A RegExp or an array of RegExp to test for exclusion of directories.
  *   extensions : RegExp - A RegExp to test for exclusion of files with the matching extension.
- *   mdconf: boolean
- *   prerender: boolean use for prerender
+ *   mdconf: Boolean.
+ *   prerender: Boolean. Used for prerender.
+ *   generate: Boolean. Used for generating info in front-matter.
  * }
  */
 function directoryTree({
@@ -75,37 +76,52 @@ function directoryTree({
     if (options && options.mdconf) {
       item.type = constants.FILE
       const contentStr = fs.readFileSync(path).toString()
-      if (contentStr) {
-        const contentMatch = contentStr.match(/^<!--([^>]*)-->/)
-        item.mdconf = contentMatch ? YAML.parse(contentMatch[1]) : {}
-        try {
-          // see https://stackoverflow.com/questions/2390199/finding-the-date-time-a-file-was-first-added-to-a-git-repository/2390382#2390382
-          const result = execSync(`git log --format=%aD ${path} | tail -1`)
-          item.birthtime =
-            Buffer.isBuffer(result) && timeFormat(new Date(result))
-        } catch (error) {
-          // eslint-disable-next-line no-console
-          console.log(`error: ${error.message}`)
+      if (!contentStr) return
+      const contentMatch = contentStr.match(/^<!--([^>]*)-->/)
+      if (options.generate) {
+        const randomId = generateRandomId(8)
+        if (!contentMatch) {
+          replaceForFrontMatter({
+            path,
+            target: `<!--\nabbrlink: ${randomId}\n-->\n`
+          })
         }
-        try {
-          // see https://stackoverflow.com/questions/22497597/get-the-last-modification-data-of-a-file-in-git-repo
-          const result = execSync(`git log -1 --pretty="format:%ci" ${path}`)
-          item.mtime = Buffer.isBuffer(result) && timeFormat(new Date(result))
-        } catch (error) {
-          // eslint-disable-next-line no-console
-          console.log(`error: ${error.message}`)
-        }
-        item.size = stats.size // File size in bytes
-        item.extension = ext
-        if (!options.prerender) {
-          item.relative = item.path.replace(process.cwd(), '')
-          item.isEmpty = contentMatch
-            ? !String.prototype.trim.call(contentStr.replace(contentMatch[0], ''))
-            : true
-          const uglifyContent = contentStr.replace(/\s/g, '')
-          item.content = uglifyContent
+        if (contentMatch && contentMatch[1].indexOf('abbrlink') === -1) {
+          replaceForFrontMatter({
+            path,
+            source: contentMatch[1],
+            target: `\nabbrlink: ${randomId}${contentMatch[1]}`
+          })
+          console.log('✅ replaceForFrontMatter success')
         }
       }
+
+      item.mdconf = contentMatch ? YAML.parse(contentMatch[1]) : {}
+      try {
+        // see https://stackoverflow.com/questions/2390199/finding-the-date-time-a-file-was-first-added-to-a-git-repository/2390382#2390382
+        const result = execSync(`git log --format=%aD ${path} | tail -1`)
+        item.birthtime =
+          Buffer.isBuffer(result) && timeFormat(new Date(result))
+      } catch (error) {
+        console.log(`❎ error: ${error.message}`)
+      }
+      try {
+        // see https://stackoverflow.com/questions/22497597/get-the-last-modification-data-of-a-file-in-git-repo
+        const result = execSync(`git log -1 --pretty="format:%ci" ${path}`)
+        item.mtime = Buffer.isBuffer(result) && timeFormat(new Date(result))
+      } catch (error) {
+        console.log(`❎ error: ${error.message}`)
+      }
+      item.size = stats.size // File size in bytes
+      item.extension = ext
+      if (!options.prerender) {
+        item.relative = item.path.replace(process.cwd(), '')
+        item.isEmpty = contentMatch
+          ? !String.prototype.trim.call(contentStr.replace(contentMatch[0], ''))
+          : true
+        const uglifyContent = contentStr.replace(/\s/g, '')
+        item.content = uglifyContent
+      }
     }
   } else if (stats.isDirectory()) {
     const dirData = safeReadDirSync(path)

packages/scripts/src/conf/webpack.config.prod.js → packages/crd-scripts/src/conf/webpack.config.prod.js

@@ -7,8 +7,8 @@ const CopyMarkdownImageWebpackPlugin = require('copy-markdown-image-webpack-plug
 const MiniCssExtractPlugin = require('mini-css-extract-plugin')
 const PrerenderSPAPlugin = require('crd-prerender-spa-plugin')
 const { generateSiteMap } = require('crd-generator-sitemap')
-// const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');
-// const UglifyJsPlugin = require('uglifyjs-webpack-plugin');
+// const CssMinimizerPlugin = require('css-minimizer-webpack-plugin')
+// const UglifyJsPlugin = require('uglifyjs-webpack-plugin')
 const fs = require('fs-extra')
 const { defaultHTMLPath, docsBuildDist } = require('crd-utils')
 const { getDocsConfig } = require('crd-utils')
@@ -171,13 +171,13 @@ module.exports = function (cmd) {
           await fs.remove(`${docsBuildDist}/${docsConfig.repo}`)
           // move README as root index.html
           await fs.copy(`${docsBuildDist}/README/index.html`, `${docsBuildDist}/index.html`)
-          console.log('generate prerender file success!')
+          console.log('✅ generate prerender file success!')
           if (docsConfig.seo) {
             if (docsConfig.seo.google) {
               fs.writeFileSync(`${docsBuildDist}/sitemap.xml`, generateSiteMap(routes))
             }
           }
-          console.log('generate sitemap file success!')
+          console.log('✅ generate sitemap file success!')
         }
       },
       // The actual renderer to use. (Feel free to write your own)

packages/crd-scripts/src/generate.js

@@ -0,0 +1,23 @@
+const fs = require('fs')
+const { docsConfig } = require('crd-utils')
+const DirectoryTree = require('./conf/node-directory-tree')
+
+module.exports = function generate(program) {
+  if (!fs.existsSync(docsConfig)) {
+    console.log('❎ please check config.yml in root dir!\n')
+    return
+  }
+
+  const dir = program.markdownPaths
+  const dirs = Array.isArray(dir) ? dir : [dir]
+  const otherProps = {
+    mdconf: true,
+    extensions: /\.md/,
+    generate: true
+  }
+  dirs.map(path => DirectoryTree({
+    path,
+    options: otherProps,
+  }))
+  console.log('✅ generate success!')
+}

packages/crd-seed/layout/index.js

@@ -210,6 +210,10 @@ function BasicLayout({
 
   const carryRepoInProd = ifProd && repo
   const renderContent = () => {
+    console.log('routeData', routeData)
+    const defaultPath = (routeData.find(data => data.path === '/README')
+      && routeData.find(data => data.path === '/README').mdconf
+      && routeData.find(data => data.path === '/README').mdconf.abbrlink) || 'README'
     return (
       <div
         className={cx(`${styles.content}`, {
@@ -218,7 +222,7 @@ function BasicLayout({
       >
         <Switch>
           {/* see https://reacttraining.com/react-router/web/api/Redirect/exact-bool */}
-          <Redirect exact from={ifAddPrefix ? `/${repo}` : `/`} to={ifAddPrefix ? `/${repo}/README` : `/README`} />
+          <Redirect exact from={ifAddPrefix ? `/${repo}` : `/`} to={ifAddPrefix ? `/${repo}/${defaultPath}` : `/${defaultPath}`} />
           {routeData.map((item) => {
             const { path, mdconf, component } = item
             const { abbrlink } = mdconf