doc 贡献指南

概述

portal 是 go-zero 官方文档网站，大家在使用中发现 bug，有新的特性等，均可以参与到 portal 的贡献中来，我们非常欢迎大家的积极参与，也会最快响应大家提出的各种问题，pr 等。

贡献步骤

关于如何 pr 可以参考 Github Pull Request 文档。

贡献规范

  1. 快速开始 菜单下的文档初衷：点到为止，告诉开发者该怎么用（用法），不告知其为何这么用（背景&场景），需要有所保留，开发者能够根据文档跑出预期结果即可，无需详细介绍。

  2. 指南 菜单下的文档初衷：指南中文档相比【任务】则要更甚之，要告诉开发者该怎么用（用法），更要告知其为何这么用（背景&场景），从用法层面暴露更多开发者挖掘不到的用法。

  3. 组件菜单：从基本用法到深入原理

  4. 所有文档标题以 2 级标题（即 “##”）作为起始标题，子标题建议不高于 5 级（包含 5 级，即 “#####”），一级标题归文档大标题保留所有。

  5. 文档建议以二级标题【概述】开头，然后正文。

  6. 超链接建议用 <a href="url" target="_blank">content</a>，防止用户新开页面而关掉当前页面带来不便。

  7. 图片组件建议用 Image，支持放大缩放，用法参考 example

  8. 温馨提示、警告、说明等建议用文档自身携带的组件，用法参考 example

  9. 文档中如果有外链，建议在文末补充 【参考文献】标题

参考文献