近期入职的新同事比较多，而其中有些同事已经有在官网投稿的打算。为降低彼此之间的沟通成本，并缩短技术管理者的审阅时间，故而写下这篇官网投稿的相关指南。

1. 官网技术背景介绍

为了让新同事对官网有更进一步的了解，我觉得有必要简单地介绍一下官网背后的技术。

1) Refinery CMS框架

Refinery是一款基于Ruby On Rails的CMS框架，它以灵活著称。是目前Ruby社区最为流行的CMS框架

The most popular Ruby on Rails CMS

你可以到Refinery官网去了解更多的内容。如果你点击了前面的链接，将会看到一个丑陋的管理员页面的截图，没错那就是Refinery自带的管理员页面。丑陋难用其实也是它的特点之一。

灵活性是一把双刃剑，灵活性带来便利的另一面就是难以把控的风险。如果系统管理者对该系统不够熟悉，随意编辑则可能会弄出一些500的页面，为此想要在这个系统上做好运营的工作，还需运营者跟开发者之间的相互配合。

2）Refinery的Blog模块

Refinery自身是不带有Blog的管理功能的，幸好官方的成员开发出了相关的扩展插件。具体可以点击Refinery Blog查看。它会创建博客相关的管理页面视图，以及相关的数据表。

不过该模块并没包含什么像样的编辑器，为了提供Markdown的在线编辑功能还需要引入相关的JS插件。

3) Markdown支持

官网的博客编辑模块增添了Markdown在线编辑的功能。我们集成了SimpleMDE这个Markdown编辑器，使得同事们可以直接在线上编辑并预览自己的文章。

然而，个人是建议在自己的线下编辑器编写完博客之后再贴到官网上面去。如今的代码编辑器已经有比较成熟的Markdown支持了，线上的Markdown编辑器可以在对文章进行微调的时候用。

如果你还不知道Markdown是什么，emmmmmm~

2. 投稿注意事项

1）文章内容选择

往官网上投稿文章并不一定是要技术类文章，也可以是一些运动，工作，生活方面的心得体会。然而官网并不是简书之类的写作平台，因此更倾向于接收技术类有助于团队成长，突出团队风采，积极向上的文章。而一些对于时事政治的吐槽，充满着个人对社会不满的文章，请移步简书，知乎之类的社交平台。

2) 朴素，严谨，通顺

朴素

官网投稿并不是什么征文大赛，并不要求你言辞造句多么有特色。相反如果写一篇技术文章都写得像莎士比亚的戏剧一样文绉绉的话，阅读该文章的同事心中该是何等纠结。故而往官网上投稿的文章还是建议用较为简单朴素的言语来表达出最核心的想法。

严谨

编写技术文章的时候难免会需要贴代码或者截图，这个时候严谨性就很重要了。正确的代码错误的结果数据，比错误的代码更容易误导读者，简单举个有问题的例子

def sum(array)
  array.reduce(&:+)
end

puts sum([1,2,3,4,5,6]) # => 10

像这种运行结果跟注释给出的结果不一致的情况是很容易误导读者的，代码输出的正确结果应该是21而不是10。对于前端开发者来说很多时候除了贴代码以外还需要贴截图，这种时候请反复检查，避免出现代码实现的效果跟截图不一致的情况出现。

通顺

平时人与人之间的讲话都是比较随意的，即便“语法”不怎么对，但是大意都能够理解，也就没有什么人会去深究了。但是编写博客毕竟与口头说话不同，我们有时间去修正文章中的口语化问题。在编写完一篇博客之后尽量自己多读几遍，自行修正一些奇奇怪怪的语句以及错别字。这在某种程度上能够避免技术负责人在审阅文章的时候爆粗。

3) 文章格式

官网投稿的文章请统一使用Markdown格式，目前不接收其他格式的文章。简单的博客模板如下

话说天下大势，分久必合，合久必分。周末七国分争，并入于秦。及秦灭之后，楚、汉分争，又并入于汉。汉朝自高祖斩白蛇而起义，一统天下，后来光武中兴，传至献帝，遂分为三国。

<!-- More -->

0. 标题1


1. 标题2


2. 标题3

可见文章的中间有一个<!-- More -->的标记，这个标记是起到了分割符的作用。它把文章分割成上下两部分，上面一部分作为文章的预览文本。所谓预览就是在文章列表页中每篇文章的文字简述。

当然这个功能只是为了方便开发者，我们也可以在后台文章管理页面的Teaser模块中自定义相关的描述文字。为了您和您家人的安全，文字简述中只需要纯文本即可，不要往其中加入超链接或者图片。

4) 题图

同样是作用于文章列表页面，我们还需要一张分辨率还不错的图片来作为题图，题图的内容最好跟文章内容有一定的关联。举个例子

图中的博客内容主要是讲述Ruby相关的知识的，我也就顺手从网上找到Ruby相关的图片来作为题图。

可以直接在文章管理页面中的Images模块上传题图。

5) 名词的书写

这是很多同事都会忽略的一点，有些同事的文章经常被打回来就是由于专有名词大小写不够规范。可能你觉得一个名词的大写或者小写不用太过在意，然而……我们在意。在合适的地方使用大写字母不仅仅是提高了文本的视觉冲击力，同时也是专业性的一种体现。下面举些简单的例子

1. ruby on rails => Ruby On Rails视觉效果更佳。
2. html的全称是Hypertext Markup Language，是多个名词的组合应该写成HTML。

PS：在正文中出现的类名，变量名，方法名等在代码中才会出现的名词建议标记为代码模式，让读者可以一目了然。比如把一句简单的话“@user是User类的一个实例。”转换成“@user是User类的一个实例。”视觉效果就更佳了。

6）站内图片

有些同学可能会在其他的社交平台上面发布自己的文章，不同的社交平台都会有自己的图片上传机制。如果你是用简书，或者掘金来写作，当你往编辑器中粘贴图片的时候他们会先把图片上传到自己的CDN服务器中，然后再把该图片的Markdown格式链接返回给操作者。进而你就会在你的Markdown文本中看到类似这样的内容

![Hello world](https://xxxxxx.cdn.com/hello_world.png)

我们在预览文章的时候便能够看到相关的图片了。然而在官网投稿时不建议使用这种外链图，这是前技术负责人定下来的规矩了，可能他是担心一些写作平台不靠谱吧。因此，如果我们的博客文章里面有图片，请把相关的图片自行上传到官网，然后把链接贴上，大概形式如下。

![Hello world](https://blog.beansmile.com/system/images/xxxxxxxx)

可见我并没有使用全地址，而只是使用了一个相对的地址。原因有二

1. 官网的域名有改变的可能，把域名硬编码到文章当中并不是一个好的做法，日后域名的修改便会导致图片失效。
2. 目前官网还没有加入https，如果贴的是http://www.beansmile.com/xxxx的话，等到上了https之后再访问该页面时浏览器会警告我们引用了不安全的静态资源。(当然写成//www.beansmile.com/xxxx也就没事了，不过何必多添加几个字符呢？)。

PS: 上面的Hello world文本就相当于<img>标签的alt属性的值，对于一些屏幕阅读器来说意义重大，所以要养成好习惯，在里面加入有意义的文本。

7) 发布之前

如果做到了上面的几点要求就差不多可以让技术负责人审阅我们的文章了。在此之前我们还有一些需要注意的地方

存为草稿

默认情况下，一旦我们保存了博客，就可以在前台页面看到博客内容了。然而对于一篇尚未经过技术负责人审阅的文章而言，展示在网站前台还为时过早。因此任何文章在提交给技术负责人审阅之前都应该先保存为草稿。这时便只有登录并有权限的用户才能够看到这篇文章了。

存为草稿的文章会有指定的标记

自定义有意义的slug

举个例子，当我们访问《Redux源码分析–中间件篇》的时候可以发现，它的slug是/redux-apply-middleware-source-code-analysis。这个slug并不是系统自动生成的，而是需要人手定义的。给自己的文章自定义一个英文的跟内容相关的slug对大家而言应该不算什么难事。

1. 在文章编辑页面点击Advanced options展开高级配置面板。
2. 在Custom Url这个输入框中填写自定义的slug，eg: 标题为《xxx源码分析》的文章可以把slug内容设置为xxx-code-analysis。

定义Tag

每篇文章的内容及指向性都不同，我们可以很容易地给他们打上标签，让读者对文章的内容有个大概的了解。

文章编辑页面中就有一个Tags输入框，采用的是逗号分隔的模式接收多个标签字符串，比如Redux, Javascript, React

前台显示效果如下

3. 结尾

以上的注意事项是我官网投稿的一些经验总结，一方面是简单介绍官网的核心技术，另一方面是总结一下文章提交给技术负责人审阅之前所需要注意的事项，如有遗漏还望指正。

Happy Coding and Writing!!