贡献文档¶
本站点基于开源文档站点构建工具mkdocs-material进行构建，所有文档源文件均在Gitlab上进行维护，人人都可以成为文档贡献者，你只需要clone文档，新增或者修改相关.md文件，发起Merge Request即可，以下是站点文档编写指南。
准备工作
在编写文档之前，你需要具备Markdown相关知识，本文不对Markdown传统语法进行赘述，相关同学可以点击这里进行学习，mkdocs-material有很多增强的扩展以使文档构建之后WEB端呈现丰富多样的渲染效果，但这可能并不适用于其他Markdown编辑器，若非必要，我们使用传统语法即可，以免影响阅读体验，详见官方文档。
下载项目¶
git clone https://gitlab.zhixueyun.com/document/developer.git
目录结构¶
整体结构¶
.
├── docs #文档主目录
│ ├── contribute #贡献文档
│ ├── images #图片资源
│ ├── index.md #首页
│ ├── standard #流程与规范
│ └── tutorial #入门与教程
├── mkdocs.yml #主配置文件
├── overrides #自定义文件
│ ├── assets #资源(图片等)
│ ├── home.html #自定义首页
│ └── main.html #自定义主页面框架
详细说明¶
.
└── contribute.md #贡献文档
.
├── developer-tutorial-frontend.md #前端开发手册
├── developer-tutorial-java.md #java开发手册
├── developer-tutorial.md #开发手册
├── front-demo.md #前端开发demo
├── java-demo.md #后端开发demo
├── jooq.md
└── sleet.md
.
├── Kotlin_base.md #Kotlin基础编码规范
├── Kotlin_zxy.md #Kotlin编码规范约定
├── code.md #知学云代码管理规范
├── database.md #数据库规范
├── env-flow.md #产品环境管理规范
├── frontend.md #知学云前端编码规范
├── interface.md #接口规范
├── java_coding.md #知学云java编码规范
├── operation.md #运维对接流程规范
├── process_flow.md #产品研发管理规范
├── review_flow.md #评审流程规范
├── setup.md #升级兼容规范
└── version.md #版本管理规范
# 文档站点信息
site_xxx: xxx
# 文档源地址信息
repo_xxx: xxx
# Copyright
copyright: CopyRight © 2020 www.zhixueyun.com All Rights Reserved
# 主题信息，可以对站点色调、logo等进行自定义
theme:
name: material
custom_dir: overrides
language: zh
logo: images/logo.png
favicon: images/favicon.ico
palette:
- scheme: default
primary: blue
accent: blue
toggle:
icon: material/weather-night
name: 开启暗黑模式
- scheme: slate
primary: indigo
accent: deep purple
toggle:
icon: material/weather-sunny
name: 开启明亮模式
# 显示横向导航栏，数据为nav配置
features:
- navigation.tabs
# 导航栏
nav:
- 首页: index.md
- 流程与规范:
- xxx: 文档地址(基于 docs 目录的地址)
# markdown扩展支持，支持更多的语法渲染
markdown_extensions:
- admonition
- codehilite:
guess_lang: false
linenums: true
- toc:
permalink: true
- footnotes
- meta
- def_list
- pymdownx.xxx
# 插件
plugins:
- search
对页面主体框架或自定义页面的实现
本地构建¶
详见本地构建指南
注意事项¶
Warning
每个markdown文档只允许一个一级标题（h1），如果有多个一级标题（h1），则不会自动生产目录；若.md没有用#（h1），则mkdocs会自动将该文件在mkdocs.yml里对应的page名用h1效果展示在第一行