DOCSITE
En
文档

自定义页面

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

class CustomPage extends Language {
  constructor(props) {
    super(props);
    // others
  }

  render() {
    const language = this.getLanguage();
    // others
    return (
      <div>
        <Header
          currentKey="customKey" // key defined in site_config/site.js pageMenu
          type="normal"
          logo="/img/docsite.png"
          language={language}
          onLanguageChange={this.onLanguageChange}
        />
        {/* others */}
      </div>
    )
  }
}

document.getElementById('root') && ReactDOM.render(<CustomPage />, document.getElementById('root'));

export default CustomPage;

现对整个页面作下说明：

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

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