自定义页面

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

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主体结构如下：

  1. class CustomPage extends Language {
  2.   constructor(props) {
  3.     super(props);
  4.     // others
  5.   }
  7.   render() {
  8.     const language = this.getLanguage();
  9.     // others
  10.     return (
  11.       <div>
  12.         <Header
  13.           currentKey="customKey" // key defined in site_config/site.js pageMenu
  14.           type="normal"
  15.           logo="/img/docsite.png"
  16.           language={language}
  17.           onLanguageChange={this.onLanguageChange}
  18.         />
  19.         {/* others */}
  20.       </div>
  21.     )
  22.   }
  23. }
  25. document.getElementById('root') && ReactDOM.render(<CustomPage />, document.getElementById('root'));
  27. export default CustomPage;

现对整个页面作下说明：

  • 整个页面需继承src/components/language组件，该组件提供两个方法onLanguageChange和getLanguage，分别用于语言切换（传递给Header组件即可）和获取语言版本。
  • 为支持SEO，docsite会调用ReactDOMServer.render将页面jsx渲染成一段静态HTML字符串，并最终组合到页面当中去，所以在constructor、componentWillMount、render等服务端渲染会调用的生命周期方法中，不要出现未定义的或者无法识别的变量和方法，包括其依赖的组件，否则会出现错误。
  • document.getElementById('root') && ReactDOM.render(<CustomPage />, document.getElementById('root'));用于正常的页面渲染，&&前一句防止在服务端渲染时dom节点不存在导致报错。
  • export default CustomPage;导出页面用于docsite将页面渲染成一段静态HTML字符串。

语言包配置

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

  1. export default {
  2.   'zh-cn': {
  4.   },
  5.   'en-us': {
  7.   },
  8. }

添加到站点

页面定义完成后，需要将其添加到站点中。在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。