cnpm不能使用_快速构建项目网站：DocSite使用指南

什么是DocSite？

Docsite 是一个开源网站的快速搭建工具。

是阿里巴巴开源的基于react的企业站点生成器，

包含中英文切换，落地页，博客页，文档页，社区页面的生成等功能，支持响应式，页面定制，seo优化。

官网在这里^[1]?

演示

Nacos的官方网站，nacos.io^[2]便是由它快速搭建的。

文章目录：

文章分为四部分：

•快速开始•详细配置•高级定制•补充内容

快速开始?

这部分让你快速上手DocSite

环境搭建

安装Node.js

mac用户可以直接使用Homebrew安装

brew install node

或者在官网^[3]下载安装包

安装cnpm

为了提高下载速度，可以安装cnpm

 sudo npm install -g cnpm --registry=https://registry.npm.taobao.org --verbose

验证成功

# node版本号node -v# npm版本号npm -v# cnpm版本号cnpm -v

---

安装Docsite

使用npm或cnpm皆可，推荐后者：

# npm安装npm install docsite -g# cnpm安装sudo cnpm install docsite -g

验证成功：

# 显示版本号docsite -V

---

开始项目

三个关键命令，按顺序执行

docsite init

在项目根目录下执行该命令，会在目录下初始化一个站点开发模板并安装好相关依赖。

执行docsite init，生成的目录如下结构：

.├── .babelrc├── .docsite├── .eslintrc├── .gitignore├── .nojekyll├── blog│   ├── en-us│   └── zh-cn├── docs│   ├── en-us│   │   ├── dir│   │   └── img│   └── zh-cn│       ├── dir│       └── img├── docsite.config.yml├── gulpfile.js├── img│   ├── dubbo.ico│   └── system├── package-lock.json├── package.json├── redirect.ejs├── site_config│   ├── blog.js│   ├── community.jsx│   ├── docs.js│   ├── home.jsx│   └── site.js├── src│   ├── components│   │   ├── bar│   │   ├── button│   │   ├── footer│   │   ├── header│   │   ├── language│   │   ├── pageSlider│   │   ├── sidemenu│   │   └── slider│   ├── markdown.scss│   ├── pages│   │   ├── blog│   │   ├── blogDetail│   │   ├── community│   │   ├── documentation│   │   └── home│   ├── reset.scss│   └── variables.scss├── template.ejs├── utils│   └── index.js└── webpack.config.js

现从上至下对主要的文件、文件夹作说明。

.docsite

空文件，用作判断当前项目是否已初始化过。

template.ejs

所有生成的HTML页面的模板，修改对所有页面(除重定向页面)生效。

redirect.ejs

重定向页面模板，可在其中配置重定向逻辑。默认会根据这个模板在项目根目录下生成index.html和404.html(用于某些静态托管站点的自定义404页面的功能)。

blog

存放博客的markdown文档及相关图片资源的目录，分为中、英文两个目录。

docs

存放说明文档的markdown文档及相关图片资源的目录，分为中、英文两个目录。

img

存放非markdown使用的一些站点的图片，其中system中存放一些业务无关的图片。

site_config

存放整个站点的中英文配置数据，其中site.js配置全局的一些数据，包括本地开发启动的服务器端口(默认为8080)、部署到服务器的根目录(需以/开头但不能有尾/，如果只有/，请填写空字符串)、站点默认显示的语言版本、顶部的菜单栏和底部的页脚部分。home.jsx、docs.js、blog.js、community.jsx分别对应首页、文档页、博客列表页、社区页的配置。

docsite.config.yml

放置非markdown文件对应页面的SEO配置信息(1.3.3版本添加)

.nojekyll

用于跳过jekyll的检查

src

存放源码的位置，其中，markdown.scss为markdown文档的样式文件，variable.scss为一些公共scss变量，components为公共组件，pages为对应站点的不同页面，utils中存放一些公共方法。

现在网站的骨架搭建完成，可以进行网站的自定义和内容填充了。

docsite start

执行该命令，会在本地启动一个开发服务器，默认端口号为8080(可在site_config/site.js中的port字段进行更改)。

同时会在浏览器中自动打开该页面。在开发过程中，修改源代码包括markdown文档时，会自动进行编译，刷新浏览器即可看到更新后的结果。

在项目根目录下执行docsite start命令，会在浏览器中自动打开页面。

初始化生成的模板工程默认集成了首页、文档页、博客列表页、博客详情页、社区页及中英文国际化功能。可以按照需求自行添加和删除页面。

添加文档

•将对应的.md或者.markdown文件放进docs文件夹下的对应语言目录中，支持多级目录•在site_config文件夹下的docs.js中配置文档的菜单项

添加博客

•将对应的.md或者.markdown文件放进blog文件夹下的对应语言目录中，支持多级目录存放•在site_config文件夹下的blog.js中配置博客的列表项 注：

markdown文件均支持在文档顶部自定义元数据，顶部的—-(至少三个-)之间的数据会被认为是元数据，一个key占用一行。目前支持title、keywords、description三个字段，在生成静态HTML时，分别作为页面标签的标题、页面关键字、页面描述，便于搜索引擎更好地收录站点，从而利于SEO。

---title: titlekeywords: keywords1,keywords2,keywords3description: some description---your markdown content

docsite build

待本地开发完成后，运行该命令，将对源码和markdown文档进行编译和构建，生成构建后的文件。

发布站点

至此，整个站点的开发已经完成，在项目根目录下执行docsite build进行项目构建。

站点托管

你可以将站点托管在github pages上或者自己的服务器上

github pages托管

在github上新建仓库，将项目代码上传至仓库中。打开项目的github页面，选择Setting面板，如下所示：

转到GitHub Pages版面，选择Source后点击Save，会给出站点的访问地址，访问该地址即可看到你的站点。

服务器托管

将项目中的build目录、img目录、zh-cn目录、en-us目录、index.html及其他图片资源放置在服务器中即可。

DocSite快速入门结束，接下来介绍DocSite的详细配置(下面有分页符，选择下一页继续阅读)

详细配置

如果你详细了解DocSite的使用，可以看看以下内容

文档编写

元数据

markdown文件均支持在文档顶部自定义元数据，顶部的—-(至少三个-)之间的数据会被认为是元数据，一个key占用一行。目前支持title、keywords、description三个字段，在生成静态HTML时，分别作为页面标签的标题、页面关键字、页面描述，便于搜索引擎更好地收录站点，从而利于SEO。

---title: titlekeywords: keywords1,keywords2,keywords3description: some description---

路径

在编写markdown文档时，难免需要文档之间的相互引用。而相对地址的写法相比于绝对地址，对于站点内文档之间的引用显得更为便捷。

当需要引用其他文档时，引用路径按照在项目目录的相对文件地址即可。

同样的，当需要引用项目内的图片资源，引用路径同样是相对的文件地址，最终会被处理成正确的绝对地址。

---

添加文档

文档编写完成后，需要将其添加到页面当中。

放置位置

根据文档对应的语言版本，放入docs目录下的zh-cn或者en-us，可以是一层或者多层目录。

菜单配置

文档放入对应语言的目录中后，需要在site_config/docs.js中配置。其中的link字段用于配置访问地址，需要注意的是这个路径需要以语言开头(/zh-cn或/en-us)。

例如，某个文档的存放位置为/docs/zh-cn/demo/xxx.md，那么link字段的配置值为/zh-cn/docs/demo/xxx.html

---

添加博客

博客编写完成后，需要将其添加到页面当中。

放置位置

根据文档对应的语言版本，放入blog目录下的zh-cn或者en-us，可以是一层或者多层目录。

菜单配置

文档放入对应语言的目录中后，需要在site_config/blog.js中配置。其中的link字段用于配置访问地址，需要注意的是这个路径需要以语言开头(/zh-cn或/en-us)。

例如，某个博客的存放位置为/blog/zh-cn/demo/xxx.md，那么link字段的配置值为/zh-cn/blog/demo/xxx.html

---

国际化

国际化分为两部分，分别为markdown文档的国际化和站点其余部分的国际化。

markdown文档的国际化

markdown文档主要分为说明文档和博客文档。这两种类型文档的国际化处理方式是类似的，说明文档按照中英文版本分别放入docs目录下的zh-cn和en-us目录中。博客文档按照中英文版本分别放入blog目录下的zh-cn和en-us目录中。

站点其余部分的国际化

在site_config目录中，根据中英文版本分别对应着zh-cn和en-us字段，所有页面相关的文案均需配置在这两个字段下。

---

重定向

docsite默认会在项目根目录下根据模板redirect.ejs生成index.html和404.html(用于某些静态站点托管平台自定义404页面的功能)。redirect.ejs中配置了访问到根目录时的跳转逻辑。如下所示：

高级定制

以下是DocSite的定制部分

自定义样式

自定义样式分为整个站点的自定义和文档展示风格的自定义。

站点自定义

src目录下的variables.scss文件中，定义了一些用于控制站点整体显示风格的一些scss变量。通过修改这些变量，能够获得不同风格的站点。

当然，如果这样还觉得不满足需求，可以进入到每个具体的页面的样式文件中去修改。

文档展示风格自定义

src目录下的markdown.scss文件中，定义了文档展示风格的样式。分为两部分，文档的展示和代码高亮的展示。

•文档的展示 默认采用github风格https://github.com/sindresorhus/github-markdown-css，如果想要其他风格，请修改`markdown.scss`文件。•代码高亮 在https://highlightjs.org/static/demo/中去选择喜爱的高亮配色，然后根据选择后的主题名称，在https://github.com/isagalaev/highlight.js/tree/master/src/styles中复制对应的样式文件到`markdown.scss`中即可。

---

自定义页面

docsite整体架构基于react，所以自定义页面需要有一定的react基础，可查看react官网^[4]进行学习。

docsite内置模板默认包含首页、文档页、博客列表页、博客详情页、社区页，分别对应src/pages目录下的home、documentation、blog、blogDetail、community。对于js和css资源，docsite在构建时，会将src/pages目录下的文件夹名称作为js和css资源的名称，在build目录中生成对应的js和css文件。

页面编写

自定义页面时，请在src/pages目录下新建一个文件夹，docsite会将文件夹下的index.jsx和index.scss文件作为页面进行处理。

一个自定义页面的index.jsx主体结构如下：

class CustomPage extends Language {  constructor(props) {    super(props);    // others  }  render() {    const language = this.getLanguage();    // others    return (      

currentKey="customKey" // key defined in site_config/site.js pageMenu type="normal" logo="/img/docsite.png" language={language} onLanguageChange={this.onLanguageChange} /> {/* others */}

) }}document.getElementById('root') && ReactDOM.render(, document.getElementById('root'));export default CustomPage;

现对整个页面作下说明：

•

整个页面需继承src/components/language组件，该组件提供两个方法onLanguageChange和getLanguage，分别用于语言切换(传递给Header组件即可)和获取语言版本。

•

为支持SEO，docsite会调用ReactDOMServer.render将页面jsx渲染成一段静态HTML字符串，并最终组合到页面当中去，所以在constructor、componentWillMount、render等服务端渲染会调用的生命周期方法中，不要出现未定义的或者无法识别的变量和方法，包括其依赖的组件，否则会出现错误。···

document.getElementById('root') && ReactDOM.render(, document.getElementById('root'));

•

用于正常的页面渲染，&&`前一句防止在服务端渲染时dom节点不存在导致报错。

•

export default CustomPage;导出页面用于docsite将页面渲染成一段静态HTML字符串。

语言包配置

为支持国际化，需要配置页面的国际化文案。在site_config目录下新建一个文件，将所需要的文案配置其中，并在页面中引入。其基本结构如下：

export default {  'zh-cn': {  },  'en-us': {  },}

添加到站点

页面定义完成后，需要将其添加到站点中。在site_config/site.js文件中的pageMenu中定义页面的key、title、link等。

其中key用于Header的currentKey，设置顶部菜单的选中状态。title用于顶部菜单的显示标题。link用于设置访问链接，链接设置规则如下：

•需以/zh-cn或/en-us开头。•假如页面所在的文件夹名称为custom，则英文访问链接为/en-us/custom/index.html，中文访问链接为/zh-cn/custom/index.html。

---

SEO

作为一个开源静态文档站点，我们希望用户能够通过搜索引擎更快的访问到需要的内容，因此SEO就显得尤为重要。

docsite对于markdown文档，提供了title、keywords、description三个元数据配置项。同时将对应的jsx页面渲染成静态HTML，组合到最终生成的页面中去。

对于非markdown文档页面，title、keywords、description三个配置项在项目根目录下的docsite.config.yml(v1.3.3版本添加，旧工程需手动添加该文件)中，内容如下：

pages: # key is the dirname of pages in src/pages, not including documentation and blogList that is related to markdown file home:  # 首页配置  zh-cn:   title: '网页标签title'   keywords: '关键词1，关键词2'   description: '页面内容简介'  # home config  en-us:   title: 'page title'   keywords: 'keyword1,keyword2'   description: 'page description' community:  # 社区页配置  zh-cn:   title: '网页标签title'   keywords: '关键词1，关键词2'   description: '页面内容简介'  # community page config  en-us:   title: 'page title'   keywords: 'keyword1,keyword2'   description: 'page description' blog:  # 博客列表页配置  zh-cn:   title: '网页标签title'   keywords: '关键词1，关键词2'   description: '页面内容简介'  en-us:   # blog list page config   title: 'page title'   keywords: 'keyword1,keyword2'   description: 'page description'

在整个页面站点完成并发布后，为使搜索引擎更快的收录站点，需要向搜索引擎提供站点地图。

站点地图生成

打开站点中的某个页面(最好是文档页面和博客页面)，将页面地址拷贝填入https://www.xml-sitemaps.com/的输入框，点击开始，会生成一份站点地图。

因站点的中英文版本之间无明显的链接相连，所以需中英文分别生成，然后手动合并成一份，并命名为sitemap.xml。当然，你也可以选择其他站点地图生成工具。

站点地图提交

除了将生成的站点地图文件放置在项目根目录外，你还可以主动向搜索引擎提供站点地图。目前主流的搜索引擎为Google和百度，可以分别向这两个搜索引擎的站长平台提交站点地图，链接为：

•Google站长^[5]•百度站长^[6]

---

全局搜索

该功能自1.2.0版本内置模板添加。该功能依赖于goolge搜索和百度搜索，因此确保站点被二者收录^[7]

在site_config/site.js配置文件中，有两个字段需要配置：domain和defaultSearch。

domain

用于设置站点的域名。比如站点地址为https://docsite.js.org/zh-cn/docs/installation.html?p=1，那么设置该字段为docsite.js.org。不包含网络协议、path、查询参数等。

defaultSearch

用于设置初始展示的搜索引擎，可选值为google、baidu。当然，在使用过程中，可以通过点击图标随意进行切换。

在填写完关键字后，按下回车键就可以进行搜索了。

---

补充内容

构建细节

本篇简单介绍下docsite的构建细节，便于更好的理解和使用docsite。

md文档构建

除了基本的md文本内容，docsite还支持title，keywords，description三个元数据。

在本地开发时，当新增、修改、删除md文档时，会在对应目录中生成对应的json文件，比如/blog/zh-cn/demo.md文档中内容如下：

---title: demo titlekeywords: keywords1,keywords2,keywords3description: some description---## the title

则会在/zh-cn/blog/下生成一个demo.json文件，内容如下：

{  "title": "title",  "keywords": "keywords1,keywords2,keywords3",  "description": "some description",  "__html": "

the title

", "filename": "demo.md",}

js、css构建

docsite会对pages目录下的一级文件夹中的index.jsx和index.scss文件作构建，在build目录生成对应的js和css文件，文件名为文件夹的名称。比如某个页面为pages/custom/index.jsx，pages/custom/index.scss，那么会在build目录中生成custom.js和custom.css文件。

html构建

html构建主要生成两类页面，一个是功能性页面，一个是站点页面。

•功能页面 docsite会根据redirect.ejs在根目录下生成一个index.html文件，用作访问根目录时的跳转。还会生成一个404.html，用于某些静态站点托管平台的自定义404页面的功能。当用户访问一个不存在的页面时，平台会将用户导向404.html，进而跳转到正常的页面。•站点页面 对于站点页面，docsite依据template.ejs生成HTML页面，页面中引入合适的静态资源。主要分为首页、md页和其他页面三种类型，现分别作说明：•首页 docsite将src/pages/home文件夹下的index.jsx转换为index.html文件，放置在zh-cn和en-us目录下。•md页 文档页中，结合docs/zh-cn(或docs/en-us)中的md文档和src/pages/documentation，转换成对应的HTML文件。比如某个文档为docs/zh-cn/demo.md，则会生成zh-cn/docs/demo.html。

博客详情页中，结合blog/zh-cn(或blog/en-us)中的md文档和src/pages/blogDetail，转换成对应的HTML文件。比如某个博客为blog/en-us/demo.md，则会生成en-us/blog/demo.html。

•其他页面 比如某个页面的jsx代码位置为src/pages/demo/index.jsx，则会生成zh-cn/demo/index.html和en-us/demo/index.html。

---

路径前缀

当站点部署在一些静态托管站点时，其根路径并不是/。比如github pages，其根路径一般为/repertory_name/，如果需要部署到多个平台，那么修改资源的访问地址将是个噩梦。为此，docsite将根路径抽取出来，放置在site_config/site.js中的rootPath字段进行配置，配置规则如下：

•当部署根路径为/，则设置为''空字符串即可。•当部署根路径不为/，则设置为具体的根路径，注意需以/开头，但不能有尾/。在执行docsite build前，请确保rootPath配置正确。

路径配置

对于站点内的页面链接，在site_config目录下配置时，请以/zh-cn或/en-us开头，内置页面会对这些链接进行处理，拼接上rootPath，进而得到完整的访问地址。

---

性能

在业务使用过程中，我们发现托管在项目内的图片资源占据了大量的访问带宽，导致页面的加载过慢，github pages尤其如此。为提高加载性能，建议将图片进行压缩，或者直接放在cdn上进行引用。

References

[1] 这里: https://docsite.js.org/zh-cn/index.html[2] nacos.io: https://nacos.io[3] 官网: https://nodejs.org/zh-cn/download/[4] react官网: https://reactjs.org/[5] Google站长: https://www.google.com/webmasters/tools/home[6] 百度站长: https://ziyuan.baidu.com/site/index[7] 收录: https://docsite.js.org/zh-cn/docs/SEO.md