diff --git a/README.md b/README.md index ca1898f90..0492c2937 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,6 @@ + _.-"\ _.-" \ ,-" \ @@ -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) \ No newline at end of file diff --git a/config.yml b/config.yml index c2a02e801..33153c05f 100644 --- a/config.yml +++ b/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 \ No newline at end of file +inject: injectLogic/index.js + +# Use abbrlink +abbrlink: true diff --git a/docs/Front-matter.md b/docs/Front-matter.md index 72a4559cd..a1bb2a7d7 100644 --- a/docs/Front-matter.md +++ b/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 // 一键给所有文章加上短链 +``` diff --git "a/docs/\344\270\273\351\242\230/\351\273\230\350\256\244\344\270\273\351\242\230.md" "b/docs/\344\270\273\351\242\230/\351\273\230\350\256\244\344\270\273\351\242\230.md" index 843946479..3dab66b6b 100644 --- "a/docs/\344\270\273\351\242\230/\351\273\230\350\256\244\344\270\273\351\242\230.md" +++ "b/docs/\344\270\273\351\242\230/\351\273\230\350\256\244\344\270\273\351\242\230.md" @@ -1,3 +1,7 @@ + + ## 默认主题 create-react-doc 的默认主题为 [crd-seed](https://github.com/MuYunyun/create-react-doc/tree/main/packages/crd-seed)。该主题有以下特性: diff --git "a/docs/\344\271\246\345\206\231\347\273\204\344\273\266.md" "b/docs/\344\271\246\345\206\231\347\273\204\344\273\266.md" index 0e82c45a4..cfa6c6ffa 100644 --- "a/docs/\344\271\246\345\206\231\347\273\204\344\273\266.md" +++ "b/docs/\344\271\246\345\206\231\347\273\204\344\273\266.md" @@ -1,3 +1,7 @@ + + import { Button } from '../components/index.jsx' ## 书写组件 diff --git "a/docs/\345\205\266\345\256\203\345\267\245\345\205\267.md" "b/docs/\345\205\266\345\256\203\345\267\245\345\205\267.md" index a41091b1c..4ffac9385 100644 --- "a/docs/\345\205\266\345\256\203\345\267\245\345\205\267.md" +++ "b/docs/\345\205\266\345\256\203\345\267\245\345\205\267.md" @@ -1,3 +1,7 @@ + + ## 其它工具 ### crd-leetcode-cli diff --git "a/docs/\346\225\260\345\255\246\345\205\254\345\274\217.md" "b/docs/\346\225\260\345\255\246\345\205\254\345\274\217.md" index 5cebe3e23..ce37e75fa 100644 --- "a/docs/\346\225\260\345\255\246\345\205\254\345\274\217.md" +++ "b/docs/\346\225\260\345\255\246\345\205\254\345\274\217.md" @@ -1,3 +1,9 @@ + + ## 数学公式 支持在 `$$` 与 `$$` 之间书写 latex 数学公式即能显示在网页上。 diff --git "a/docs/\346\233\264\346\226\260\346\227\245\345\277\227.md" "b/docs/\346\233\264\346\226\260\346\227\245\345\277\227.md" index 2a54a254c..7a4e552c3 100644 --- "a/docs/\346\233\264\346\226\260\346\227\245\345\277\227.md" +++ "b/docs/\346\233\264\346\226\260\346\227\245\345\277\227.md" @@ -1,7 +1,19 @@ + + # 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` diff --git "a/docs/\347\253\231\347\202\271\345\217\221\345\270\203.md" "b/docs/\347\253\231\347\202\271\345\217\221\345\270\203.md" index bcdbe9182..c841e5b60 100644 --- "a/docs/\347\253\231\347\202\271\345\217\221\345\270\203.md" +++ "b/docs/\347\253\231\347\202\271\345\217\221\345\270\203.md" @@ -1,3 +1,7 @@ + + ## 站点发布 在 [快速上手](http://muyunyun.cn/create-react-doc/%E5%BF%AB%E9%80%9F%E4%B8%8A%E6%89%8B) 一节中介绍了如何快速搭建站点, 本节将介绍如何将搭建好的站点打包、发布到 gh-pages。 diff --git "a/docs/\351\253\230\351\230\266\347\224\250\346\263\225.md" "b/docs/\351\253\230\351\230\266\347\224\250\346\263\225.md" index 975f03252..e8e390c75 100644 --- "a/docs/\351\253\230\351\230\266\347\224\250\346\263\225.md" +++ "b/docs/\351\253\230\351\230\266\347\224\250\346\263\225.md" @@ -1,3 +1,7 @@ + + ## 高阶用法 与 git 文件结构类似, 如果在展示的文件夹中有私有文件不方便展示在文档站点, 可以在 `.gitignore` 文件中设置过滤文件, 这样它们就不会展示在文档站点中了。eg: [.gitignore](https://github.com/MuYunyun/blog/blob/main/.gitignore) diff --git a/packages/scripts/.babelrc.js b/packages/crd-scripts/.babelrc.js similarity index 100% rename from packages/scripts/.babelrc.js rename to packages/crd-scripts/.babelrc.js diff --git a/packages/scripts/.npmrc b/packages/crd-scripts/.npmrc similarity index 100% rename from packages/scripts/.npmrc rename to packages/crd-scripts/.npmrc diff --git a/packages/scripts/README.md b/packages/crd-scripts/README.md similarity index 100% rename from packages/scripts/README.md rename to packages/crd-scripts/README.md diff --git a/packages/scripts/index.js b/packages/crd-scripts/index.js similarity index 88% rename from packages/scripts/index.js rename to packages/crd-scripts/index.js index c819cc573..8a84dd852 100644 --- a/packages/scripts/index.js +++ b/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, } diff --git a/packages/scripts/package.json b/packages/crd-scripts/package.json similarity index 100% rename from packages/scripts/package.json rename to packages/crd-scripts/package.json diff --git a/packages/scripts/src/build.js b/packages/crd-scripts/src/build.js similarity index 100% rename from packages/scripts/src/build.js rename to packages/crd-scripts/src/build.js diff --git a/packages/scripts/src/commands/initProject.js b/packages/crd-scripts/src/commands/initProject.js similarity index 100% rename from packages/scripts/src/commands/initProject.js rename to packages/crd-scripts/src/commands/initProject.js diff --git a/packages/scripts/src/commands/initTheme.js b/packages/crd-scripts/src/commands/initTheme.js similarity index 100% rename from packages/scripts/src/commands/initTheme.js rename to packages/crd-scripts/src/commands/initTheme.js diff --git a/packages/scripts/src/conf/getPrerenderRoutes.js b/packages/crd-scripts/src/conf/getPrerenderRoutes.js similarity index 100% rename from packages/scripts/src/conf/getPrerenderRoutes.js rename to packages/crd-scripts/src/conf/getPrerenderRoutes.js diff --git a/packages/scripts/src/conf/node-directory-tree.js b/packages/crd-scripts/src/conf/node-directory-tree.js similarity index 54% rename from packages/scripts/src/conf/node-directory-tree.js rename to packages/crd-scripts/src/conf/node-directory-tree.js index 55048be44..cf2ea2a63 100644 --- a/packages/scripts/src/conf/node-directory-tree.js +++ b/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: `\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) diff --git a/packages/scripts/src/conf/path.js b/packages/crd-scripts/src/conf/path.js similarity index 100% rename from packages/scripts/src/conf/path.js rename to packages/crd-scripts/src/conf/path.js diff --git a/packages/scripts/src/conf/rawTreeReplaceLoader.js b/packages/crd-scripts/src/conf/rawTreeReplaceLoader.js similarity index 100% rename from packages/scripts/src/conf/rawTreeReplaceLoader.js rename to packages/crd-scripts/src/conf/rawTreeReplaceLoader.js diff --git a/packages/scripts/src/conf/webpack.config.dev.js b/packages/crd-scripts/src/conf/webpack.config.dev.js similarity index 100% rename from packages/scripts/src/conf/webpack.config.dev.js rename to packages/crd-scripts/src/conf/webpack.config.dev.js diff --git a/packages/scripts/src/conf/webpack.config.js b/packages/crd-scripts/src/conf/webpack.config.js similarity index 100% rename from packages/scripts/src/conf/webpack.config.js rename to packages/crd-scripts/src/conf/webpack.config.js diff --git a/packages/scripts/src/conf/webpack.config.prod.js b/packages/crd-scripts/src/conf/webpack.config.prod.js similarity index 97% rename from packages/scripts/src/conf/webpack.config.prod.js rename to packages/crd-scripts/src/conf/webpack.config.prod.js index d6a644895..d64493618 100755 --- a/packages/scripts/src/conf/webpack.config.prod.js +++ b/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) diff --git a/packages/scripts/src/conf/webpack.config.server.js b/packages/crd-scripts/src/conf/webpack.config.server.js similarity index 100% rename from packages/scripts/src/conf/webpack.config.server.js rename to packages/crd-scripts/src/conf/webpack.config.server.js diff --git a/packages/scripts/src/deploy.js b/packages/crd-scripts/src/deploy.js similarity index 100% rename from packages/scripts/src/deploy.js rename to packages/crd-scripts/src/deploy.js diff --git a/packages/crd-scripts/src/generate.js b/packages/crd-scripts/src/generate.js new file mode 100644 index 000000000..70fe2c0a0 --- /dev/null +++ b/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!') +} diff --git a/packages/scripts/src/server.js b/packages/crd-scripts/src/server.js similarity index 100% rename from packages/scripts/src/server.js rename to packages/crd-scripts/src/server.js diff --git a/packages/scripts/src/utils/index.js b/packages/crd-scripts/src/utils/index.js similarity index 100% rename from packages/scripts/src/utils/index.js rename to packages/crd-scripts/src/utils/index.js diff --git a/packages/scripts/src/utils/initCache.js b/packages/crd-scripts/src/utils/initCache.js similarity index 100% rename from packages/scripts/src/utils/initCache.js rename to packages/crd-scripts/src/utils/initCache.js diff --git a/packages/scripts/src/web/Router.js b/packages/crd-scripts/src/web/Router.js similarity index 100% rename from packages/scripts/src/web/Router.js rename to packages/crd-scripts/src/web/Router.js diff --git a/packages/scripts/src/web/crd.json b/packages/crd-scripts/src/web/crd.json similarity index 100% rename from packages/scripts/src/web/crd.json rename to packages/crd-scripts/src/web/crd.json diff --git a/packages/scripts/src/web/index.js b/packages/crd-scripts/src/web/index.js similarity index 100% rename from packages/scripts/src/web/index.js rename to packages/crd-scripts/src/web/index.js diff --git a/packages/scripts/src/web/lazyload.js b/packages/crd-scripts/src/web/lazyload.js similarity index 100% rename from packages/scripts/src/web/lazyload.js rename to packages/crd-scripts/src/web/lazyload.js diff --git a/packages/crd-seed/layout/index.js b/packages/crd-seed/layout/index.js index 79d3df713..4a504ea7f 100644 --- a/packages/crd-seed/layout/index.js +++ b/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 (
{/* see https://reacttraining.com/react-router/web/api/Redirect/exact-bool */} - + {routeData.map((item) => { const { path, mdconf, component } = item const { abbrlink } = mdconf diff --git a/packages/templates/.npmrc b/packages/crd-templates/.npmrc similarity index 100% rename from packages/templates/.npmrc rename to packages/crd-templates/.npmrc diff --git a/packages/templates/README.md b/packages/crd-templates/README.md similarity index 100% rename from packages/templates/README.md rename to packages/crd-templates/README.md diff --git a/packages/templates/default/.github/workflows/gh-pages.yml b/packages/crd-templates/default/.github/workflows/gh-pages.yml similarity index 100% rename from packages/templates/default/.github/workflows/gh-pages.yml rename to packages/crd-templates/default/.github/workflows/gh-pages.yml diff --git a/packages/templates/default/.npmrc b/packages/crd-templates/default/.npmrc similarity index 100% rename from packages/templates/default/.npmrc rename to packages/crd-templates/default/.npmrc diff --git a/packages/templates/default/Introduction/hello_world.md b/packages/crd-templates/default/Introduction/hello_world.md similarity index 100% rename from packages/templates/default/Introduction/hello_world.md rename to packages/crd-templates/default/Introduction/hello_world.md diff --git a/packages/templates/default/README.md b/packages/crd-templates/default/README.md similarity index 100% rename from packages/templates/default/README.md rename to packages/crd-templates/default/README.md diff --git a/packages/templates/default/_.gitignore b/packages/crd-templates/default/_.gitignore similarity index 100% rename from packages/templates/default/_.gitignore rename to packages/crd-templates/default/_.gitignore diff --git a/packages/templates/default/_config.yml b/packages/crd-templates/default/_config.yml similarity index 100% rename from packages/templates/default/_config.yml rename to packages/crd-templates/default/_config.yml diff --git a/packages/templates/default/_package.json b/packages/crd-templates/default/_package.json similarity index 100% rename from packages/templates/default/_package.json rename to packages/crd-templates/default/_package.json diff --git a/packages/templates/package.json b/packages/crd-templates/package.json similarity index 100% rename from packages/templates/package.json rename to packages/crd-templates/package.json diff --git a/packages/templates/theme/default/Introduction/hello_world.md b/packages/crd-templates/theme/default/Introduction/hello_world.md similarity index 100% rename from packages/templates/theme/default/Introduction/hello_world.md rename to packages/crd-templates/theme/default/Introduction/hello_world.md diff --git a/packages/templates/theme/default/README.md b/packages/crd-templates/theme/default/README.md similarity index 100% rename from packages/templates/theme/default/README.md rename to packages/crd-templates/theme/default/README.md diff --git a/packages/templates/theme/default/_.gitignore b/packages/crd-templates/theme/default/_.gitignore similarity index 100% rename from packages/templates/theme/default/_.gitignore rename to packages/crd-templates/theme/default/_.gitignore diff --git a/packages/templates/theme/default/_.npmrc b/packages/crd-templates/theme/default/_.npmrc similarity index 100% rename from packages/templates/theme/default/_.npmrc rename to packages/crd-templates/theme/default/_.npmrc diff --git a/packages/templates/theme/default/_config.yml b/packages/crd-templates/theme/default/_config.yml similarity index 100% rename from packages/templates/theme/default/_config.yml rename to packages/crd-templates/theme/default/_config.yml diff --git a/packages/templates/theme/default/_index.js b/packages/crd-templates/theme/default/_index.js similarity index 100% rename from packages/templates/theme/default/_index.js rename to packages/crd-templates/theme/default/_index.js diff --git a/packages/templates/theme/default/_index.less b/packages/crd-templates/theme/default/_index.less similarity index 100% rename from packages/templates/theme/default/_index.less rename to packages/crd-templates/theme/default/_index.less diff --git a/packages/templates/theme/default/_package.json b/packages/crd-templates/theme/default/_package.json similarity index 100% rename from packages/templates/theme/default/_package.json rename to packages/crd-templates/theme/default/_package.json diff --git a/packages/theme/.npmrc b/packages/crd-theme/.npmrc similarity index 100% rename from packages/theme/.npmrc rename to packages/crd-theme/.npmrc diff --git a/packages/theme/README.md b/packages/crd-theme/README.md similarity index 100% rename from packages/theme/README.md rename to packages/crd-theme/README.md diff --git a/packages/theme/component/Loading/index.js b/packages/crd-theme/component/Loading/index.js similarity index 100% rename from packages/theme/component/Loading/index.js rename to packages/crd-theme/component/Loading/index.js diff --git a/packages/theme/component/Loading/index.less b/packages/crd-theme/component/Loading/index.less similarity index 100% rename from packages/theme/component/Loading/index.less rename to packages/crd-theme/component/Loading/index.less diff --git a/packages/theme/crd.logo.svg b/packages/crd-theme/crd.logo.svg similarity index 100% rename from packages/theme/crd.logo.svg rename to packages/crd-theme/crd.logo.svg diff --git a/packages/theme/favicon.ico b/packages/crd-theme/favicon.ico similarity index 100% rename from packages/theme/favicon.ico rename to packages/crd-theme/favicon.ico diff --git a/packages/theme/index.html b/packages/crd-theme/index.html similarity index 100% rename from packages/theme/index.html rename to packages/crd-theme/index.html diff --git a/packages/theme/index.js b/packages/crd-theme/index.js similarity index 100% rename from packages/theme/index.js rename to packages/crd-theme/index.js diff --git a/packages/theme/index.less b/packages/crd-theme/index.less similarity index 100% rename from packages/theme/index.less rename to packages/crd-theme/index.less diff --git a/packages/theme/markdown/Link.js b/packages/crd-theme/markdown/Link.js similarity index 100% rename from packages/theme/markdown/Link.js rename to packages/crd-theme/markdown/Link.js diff --git a/packages/theme/markdown/Link.less b/packages/crd-theme/markdown/Link.less similarity index 100% rename from packages/theme/markdown/Link.less rename to packages/crd-theme/markdown/Link.less diff --git a/packages/theme/markdown/codeBlock.js b/packages/crd-theme/markdown/codeBlock.js similarity index 100% rename from packages/theme/markdown/codeBlock.js rename to packages/crd-theme/markdown/codeBlock.js diff --git a/packages/theme/markdown/index.js b/packages/crd-theme/markdown/index.js similarity index 100% rename from packages/theme/markdown/index.js rename to packages/crd-theme/markdown/index.js diff --git a/packages/theme/markdown/style/css.less b/packages/crd-theme/markdown/style/css.less similarity index 100% rename from packages/theme/markdown/style/css.less rename to packages/crd-theme/markdown/style/css.less diff --git a/packages/theme/markdown/style/default.less b/packages/crd-theme/markdown/style/default.less similarity index 100% rename from packages/theme/markdown/style/default.less rename to packages/crd-theme/markdown/style/default.less diff --git a/packages/theme/markdown/style/diff.less b/packages/crd-theme/markdown/style/diff.less similarity index 100% rename from packages/theme/markdown/style/diff.less rename to packages/crd-theme/markdown/style/diff.less diff --git a/packages/theme/markdown/style/index.less b/packages/crd-theme/markdown/style/index.less similarity index 100% rename from packages/theme/markdown/style/index.less rename to packages/crd-theme/markdown/style/index.less diff --git a/packages/theme/markdown/style/javascript.less b/packages/crd-theme/markdown/style/javascript.less similarity index 100% rename from packages/theme/markdown/style/javascript.less rename to packages/crd-theme/markdown/style/javascript.less diff --git a/packages/theme/markdown/style/swift.less b/packages/crd-theme/markdown/style/swift.less similarity index 100% rename from packages/theme/markdown/style/swift.less rename to packages/crd-theme/markdown/style/swift.less diff --git a/packages/theme/markdown/style/xml.less b/packages/crd-theme/markdown/style/xml.less similarity index 100% rename from packages/theme/markdown/style/xml.less rename to packages/crd-theme/markdown/style/xml.less diff --git a/packages/theme/package.json b/packages/crd-theme/package.json similarity index 100% rename from packages/theme/package.json rename to packages/crd-theme/package.json diff --git a/packages/theme/routes/Pages/index.js b/packages/crd-theme/routes/Pages/index.js similarity index 100% rename from packages/theme/routes/Pages/index.js rename to packages/crd-theme/routes/Pages/index.js diff --git a/packages/theme/utils/index.js b/packages/crd-theme/utils/index.js similarity index 100% rename from packages/theme/utils/index.js rename to packages/crd-theme/utils/index.js diff --git a/packages/utils/.npmrc b/packages/crd-utils/.npmrc similarity index 100% rename from packages/utils/.npmrc rename to packages/crd-utils/.npmrc diff --git a/packages/utils/README.md b/packages/crd-utils/README.md similarity index 100% rename from packages/utils/README.md rename to packages/crd-utils/README.md diff --git a/packages/crd-utils/index.js b/packages/crd-utils/index.js new file mode 100644 index 000000000..6b12c186f --- /dev/null +++ b/packages/crd-utils/index.js @@ -0,0 +1,76 @@ +const fs = require('fs') +const yaml = require('js-yaml') +const { resolveApp, resolveTool } = require('./path') + +const docsConfig = resolveApp('config.yml') + +/** + * get docs config, see https://github.com/nodeca/js-yaml/blob/2d1fbed8f3a76ff93cccb9a8a418b4c4a482d3d9/lib/js-yaml/loader.js#L1590-L1592 + */ +const getDocsConfig = () => { + /* avoid reference loop, so use resolveApp('config.yml') instead of refrence from paths. */ + // const docsConfig = resolveApp('config.yml') + if (!fs.existsSync(docsConfig)) { + return null + } + return yaml.safeLoad(fs.readFileSync(docsConfig)) +} + +/** + * replace file content for Front-matter + * path: file path + * source?: source content + * target: target content + */ +const replaceForFrontMatter = ({ + path, + source, + target +}) => { + fs.readFile(path, (err, data) => { + if (err) { + console.log(`❎ readFileContent error in ${path}`) + return + } + console.log(`✅ readFileContent success in ${path}`) + const replaceResult = source + ? data.toString().replace(source, target) + : `${target}\n${data.toString()}` + fs.writeFile(path, replaceResult, (err) => { + if (err) { + console.log(`❎ writeFileContent error in ${path}`) + return + } + }) + console.log(`✅ writeFileContent success in ${path}`) + }) +} + +// generate a random string, length of it is n. +const generateRandomId = (n) => { + const str = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'] + let res = "" + for (let i = 0; i < n; i++) { + const id = Math.ceil(Math.random() * 35) + res += str[id] + } + return res +} + +module.exports = { + resolveApp, + resolveTool, + getDocsConfig, + replaceForFrontMatter, + generateRandomId, + // common paths + docsGitIgnore: resolveApp('.gitignore'), + docsBase: resolveApp(''), + docsConfig, + docsReadme: resolveApp('README.md'), + docsBuildDist: resolveApp('.crd-dist'), + cacheDirPath: resolveApp('.cache'), + searchFilePath: resolveApp('.cache/search.js'), + templatePath: resolveApp('node_modules/crd-templates'), + defaultHTMLPath: resolveApp('node_modules/crd-theme/index.html'), +} diff --git a/packages/utils/package.json b/packages/crd-utils/package.json similarity index 100% rename from packages/utils/package.json rename to packages/crd-utils/package.json diff --git a/packages/utils/path.js b/packages/crd-utils/path.js similarity index 100% rename from packages/utils/path.js rename to packages/crd-utils/path.js diff --git a/packages/create-react-doc/README.md b/packages/create-react-doc/README.md index 3ab9406f4..b04c5f74d 100644 --- a/packages/create-react-doc/README.md +++ b/packages/create-react-doc/README.md @@ -12,15 +12,17 @@ # react-doc -react-doc 是配合 [Create React Doc](https://github.com/MuYunyun/create-react-doc) 使用的脚手架。 +react-doc 是配合 [Create React Doc](https://github.com/MuYunyun/create-react-doc) 使用的脚手架，其内置如下命令。 ```bash -$ react-doc doc // 在当前文件夹下创建名为 doc 的文档站点 -$ react-doc start // 启动项目 -$ react-doc build // 项目打包 -$ react-doc deploy // 手动发布项目 +$ react-doc doc // 在当前文件夹下创建名为 doc 的文档站点 +$ react-doc start // 启动项目 +$ react-doc build // 项目打包 +$ react-doc deploy // 手动发布项目 +$ react-doc theme // 创建新主题包 +$ react-doc generate // 用于自动生成 Front-matter 中相关字段信息 ``` # 调试 -进入该目录, 执行 yarn link, 即可在全局使用 react-doc xxx 命令。 \ No newline at end of file +进入此包目录, 执行 yarn link, 即可在全局使用 react-doc xxx 命令。 diff --git a/packages/create-react-doc/index.js b/packages/create-react-doc/index.js index fff787d45..4df3c5057 100755 --- a/packages/create-react-doc/index.js +++ b/packages/create-react-doc/index.js @@ -7,6 +7,7 @@ const { initTheme, initCache, Deploy, + Generate, Servers, Build, } = require('crd-scripts') @@ -17,10 +18,11 @@ const pkg = require('./package.json') program .version(pkg.version, '-v, --version') .description('Markdown doc site generator for React.') - .option('start', 'Documents generated.') + .option('start', 'Start the documents site in local env.') .option('build', 'Build the documents generated.') .option('deploy', 'Deploy site to gh-pages.') .option('theme', 'Create a new theme') + .option('generate', 'Generate info in front-matter') .option('-o, --output ', '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') @@ -32,14 +34,15 @@ program console.log(' $ react-doc start') console.log(' $ react-doc build') console.log(' $ react-doc deploy') + console.log(' $ react-doc theme') + console.log(' $ react-doc generate') console.log() }) // the third value in process.argv is the value we want. .parse(process.argv) -const { start, build, deploy, theme } = program - -if (!start && !build && !deploy && !theme) return initProject(program) +const { start, build, deploy, theme, generate } = program +if (!start && !build && !deploy && !theme && !generate) return initProject(program) if (theme) { return input({ @@ -62,7 +65,7 @@ program.output = path.join(process.cwd(), program.output) const docsConfig = getDocsConfig() // assign all the markdown dir -if (start || build) { +if (start || build || generate) { fs.existsSync(docsReadme) && program.markdownPaths.push(docsReadme) @@ -84,23 +87,31 @@ if (deploy) { } // no point markdown paths -if (program.markdownPaths.length === 0) return console.log('Please specify the directory in config.yml.'.red) +if (program.markdownPaths.length === 0) { + return console.log('❎ Please specify the markdownPaths props in config.yml.'.red) +} let isExists = true // judge if files exist. program.markdownPaths.forEach((item) => { if (!fs.existsSync(item)) { - console.log(`Error: Directory ${item.yellow} does not exist`.red) isExists = false } }) -if (isExists) { - initCache(program, () => { - if (build) { - Build(program) - } else { - Servers(program) - } - }) +if (!isExists) { + console.log(`❎ Error: Directory ${item.yellow} does not exist`.red) + return +} + +if (generate) { + return Generate(program) } + +initCache(program, () => { + if (build) { + Build(program) + } else { + Servers(program) + } +}) diff --git a/packages/utils/index.js b/packages/utils/index.js deleted file mode 100644 index dca8d4751..000000000 --- a/packages/utils/index.js +++ /dev/null @@ -1,33 +0,0 @@ -const fs = require('fs') -const yaml = require('js-yaml') -const { resolveApp, resolveTool } = require('./path') - -const docsConfig = resolveApp('config.yml') - -/** - * get docs config, see https://github.com/nodeca/js-yaml/blob/2d1fbed8f3a76ff93cccb9a8a418b4c4a482d3d9/lib/js-yaml/loader.js#L1590-L1592 - */ -const getDocsConfig = () => { - /* avoid reference loop, so use resolveApp('config.yml') instead of refrence from paths. */ - // const docsConfig = resolveApp('config.yml') - if (!fs.existsSync(docsConfig)) { - return null - } - return yaml.safeLoad(fs.readFileSync(docsConfig)) -} - -module.exports = { - resolveApp, - resolveTool, - getDocsConfig, - // common paths - docsGitIgnore: resolveApp('.gitignore'), - docsBase: resolveApp(''), - docsConfig, - docsReadme: resolveApp('README.md'), - docsBuildDist: resolveApp('.crd-dist'), - cacheDirPath: resolveApp('.cache'), - searchFilePath: resolveApp('.cache/search.js'), - templatePath: resolveApp('node_modules/crd-templates'), - defaultHTMLPath: resolveApp('node_modules/crd-theme/index.html'), -}