Steem Handbook Writing Rules Revised | 《Steem 指南》写作规范增补版

This post is a contribution to the open source project Steem Handbook. Details could be found in the post Steem Handbook Calls for Support.

《Steem 指南》项目启动时，我们制订过写作规范，目的是为了各位作者步调尽可能一致，减少将来统稿的麻烦。随着编写工作逐渐展开，出现了一些事先没考虑到的地方，特此增补。

下面是向书稿的 GitHub 项目提交稿件的注意事项。文末给出了示例模板。

markdown
- 书稿统一用标准的 markdown 语法来书写（见上文的首选参考资料），保存为纯文本文件。除非特殊需求，不使用扩展语法。这是为了方便移植。
- 建议使用 typora 编辑器，这里有个简易教程。
- markdown 参考资料：使用 Markdown 来让你的文章更易于阅读、更美观 @oflyhigh。
- markdown 参考资料：中文排印指南 @momok。

@ 符号
- 由于书稿的源代码编译成书的过程里，@符号会做特殊处理，所以需要在原文里用\@来代替。例如，如果需要在成书里呈现"@steemh"，那么书稿里要写成“ \@steemh”。
分段换行
- 连续两个回车来分段。也就是说，在文本文件里，两段之间要有个空行。
署名
- 各章节的作者、编辑、校对，请自行以脚注形式在原稿章节标题处署名。标题处插入脚注的 markdown 语法是：“# 标题 ^[作者：\@deanliu；编辑：\@dapeng；校对：\@meixia。] ”
原文链接
- 如果是已经发布在 Steem 上的文章，那么建议在章节标题处以脚注形式注明出处，例如：“# 标题 ^[原文链接：https://steemit.com/steem/@steemh/steem-handbook-calls-for-support] ”。

章节
- 书稿生成程序会自动给章节编号，所以请勿手动编号。
- 章标题和节标题之间不要有正文。也就是说，所有的正文文字都从属于某个节。
- 建议（并非强制）各章最多分到三级标题（即“小节”），也就是 markdown 里的三个 # 号。尽量不要出现四级标题。如果需要的话，用粗体表示更低一级的标题即可。
- 务必不要用 # 的方式把某段文字加粗或扩大字号。# 开头仅用作章节标题。
- 建议（并非强制）每个章节标题后面添加个花括号，填入一些用来生成该节网页的文件名称，可以用标题拼音的首字母，也可以用英文，例如“# Steem 十讲{#lecture10}”。这样做有两个用处：（1）该章节的网址会以此命名；（2）方便交叉引用。例如在别处提到这一章节时，只需写“正如第 \@ref(lecture10) 章所述……”，这样，在编译生成书稿时会自动替换为该章节的编号。如果将来章节顺序有调整，则会自动更新。
插图
- 请插入本地图片，不要插入网络图片。如果需要插入网络图片，请先把图片下载到本地。同时注意不要侵犯别人图片的版权。
- 本地图片的文件名请用"章节编号开头+后面随意"，但只能包含数字、字母、下划线、短横线，切勿使用中文。例如第三章的某图，文件名可以是 03_1_fig_title.jpg。
- 图片文件上传到项目主页的 images文件夹。使用 markdown 标准语法来插入图片，如 “![](images/03_1_fig_title.jpg)”。
- 尽量使用静态图片（jpg，png），避免使用动态图片（gif）；当然，如果动态图片对展示内容效果更好的话，也无妨，但请备好能够替代的静态图片。这是为了方便做 pdf 和纸质书。
索引
- 在需要索引的地方加入\index{条目名称}即可。书后会自动添加索引条目，页码会自动生成。
- 索引可以在统稿时集中添加。初稿里不建议添加索引。
标点符号
- 请按照中文的标点符号规则书写。例如，省略号是“……”而不是“......”，也不是“。。。”。
- 最好不要用像“:)”的表情符号，除非十分有必要——想想印在纸质书里的感觉。
- 简单规范见《中文文案排版指北》。详细规范见《中文排版需求》。
发布方式
- 初稿首发在 Steem 上（标签：cn steem-guides），以便接受读者的修改意见。建议每帖 1000 到 2000 字为宜。
- 修订稿由作者本人提交 PR 到 GitHub 项目（@rileyge 的教程 1、教程 2，@evathinking 的教程）。
- 项目会将书稿编译成网页、pdf、epub 三种格式，发布在网站 steemh.org。
简单模板

# 基本常识 {#jbsc}

## 什么是 SBD ^[作者：\@steemh； 编辑：\@dapeng；校对： \@meixia。原文链接：https://steemit.com/cn/@deanliu/steem]

SBD 就是那啥啥（见 steemit [官方网站](http://steemit.com)）。

下面是个图示。

![](images/03_1_fig_title.jpg)