RE: Steem Keychain 简介和操作指南

[dapeng]

之前统一采用 markdown，我是这样考虑的：

1. steemit 原生支持 markdown。发的帖子理论上不用做任何修改，就可以用。
2. github 原生支持 markdown。源文件不用做任何修改，可以在 github 直接预览。
3. 编译成书的工具是 R bookdown，原生支持 markdown。

markdown 对 html 语法是兼容的，然而反之不然。

由于是集体协作，总得选一个标准。markdown 足够简单，并且功能足够用，于是就选了它。

bookdown 编译成 pdf 的插图问题，可以用 bookdownplus 包的 include_image()函数：当输出网页文件时，插入的图片是超级链接；当输出 pdf 时，会把图片下载到本地，再用 LaTeX 做成 pdf。

Comments

[robertyan]

谢谢大鹏 :)

我上面的问题可能有些语义上的含糊，我说的“统一采用markdown”意指不包含html的markdown原生语法；通过搜索代码仓库，也可以看到目前的书籍源码中几乎没有html的标签。

这篇文章中的html由于通过steempress投递，自动做过一些预处理，所以也是对markdown兼容的，但代码上不如原生的markdown简洁（参见：https://steemd.com/cn/@ericet/steemkeychain-7n2z3fu72e ）。对于这种情况，之前的做法是建议作者采用更标准的markdown原生语法，还是也容许带有比较多的<h4>、<ul>、<ol>、<li>标签？

好的， bookdownplus 包的include_image()函数可以具体稍后编辑时再看一下。我之前也觉得可以在编译前写一个预处理脚本，提取其中的image url，自动下载图片到本地并替换路径。这个问题回头可以另外改进，可减轻编辑的工作量、减少出错概率 :)

[robertyan]

如果是markdown中包含比较多的html，一个潜在问题是可能某些编辑由于完全不了解html语法会犯晕，不知道如何进行修改。steem上markdown的原生语法似乎更普及一些。

所以，主要是想了解下之前的编辑过程是否遇到过类似情况，是如何权衡的？

[dapeng]

编译前写一个预处理脚本，提取其中的image url，自动下载图片到本地并替换路径。

bookdownplus::include_image() 干的就是这个。除此之外，如果图片是 gif 动图，它会自动截取第一帧，另存为 png，再插入 pdf。

之前没有遇到过混杂 html 的情况。当时大家都是以 markdown 格式投稿的。

大不了把 html 预处理一下，用 pandoc 转成 markdown 再合并进书稿。

[robertyan]

好的，谢谢大鹏提供的信息 :)

代码commit以后，确实有一些工作是可以自动化的，至少保证最后输出结果无误是不困难的。

不过这里其实主要是人的问题：

由于我们现在的合作模型是作者写作+编辑提交代码，问题主要在源码阶段的作者的自由度和编辑的工作量之间的权衡。

• 如果作者都用不包含html的markdown会比较规范，但对于某些作者来说，则不自由（如不能用steempress写作），但对编辑来说格式相对统一；
• 反之，则作者自由、且对某些作者来说写作效率和收益也会提高，编辑需要更多知识（学习成本）或工作（编写成本）。

我考虑了一下，可能还是在编辑这里加一道工序，将html格式通过在线工具（如这个，或者有其他更简易的方式）转换成markdown以后再提交。如此，作者自由，编辑的成本增加的也较少。

[dapeng]

html 转 markdown 用 pandoc。说不定 travis-CI 可以自动完成。

wordpress 有 markdown 插件，可以在 wordpress 上用 markdown 写，虽然用 steempress 发布后会转成 html，但是 wordpress 的markdown 源文本可以提交到 github。

不过这依然是作者自由度的问题。作者书写方式越规范，编辑和后期维护越容易。越放飞自我，越麻烦。

[robertyan]

嗯嗯，

1. 第一点，我上面也提到了，commit以后，可以在build阶段做一些检测，这样可以保证结果是无误的。不过主要问题应该还是在编辑的阶段。。。
2. 第二点，作者需要了解的细节还挺多的，比如markdown写作以后如何提交到GitHub，然后有的作者用wordpress也是为了少用markdown。。。

所以原则上，还是让机器能做的事情让机器做吧，只不过在编辑、合并、编译每个阶段可能要用到一些不同的工具。。。解放作者和编辑之间，根据具体情况再做一些协调吧~

[robertyan]

大鹏，顺便请教一下，之前文档里的标题是不是最多支持到第三级？如果使用第四级标题是会在目录里增加新的一级吗？

标题3

标题4

[robertyan]

意思是指在这个编辑的工作流中加一步，在GitHub的编辑器编辑之前，先将html转换为markdown

想得比较多、比较细，主要还是目前假设的编辑的技术基础比较薄弱一点。。。

[robertyan]

当然，如果有 html --> rmarkdown 的converter的话会更好一些，之前书本编译的很多问题就是由于文档中的rmarkdown语法错误引起的。:P

[robertyan]

话说"github 原生支持 markdown。源文件不用做任何修改，可以在 github 直接预览。"这条其实是有问题的。。。因为目前提交到GitHub的是RMarkdown，所以直接预览是有问题的。

如果用的是gitbook之类的或许可行，但RMarkdown似乎没法支持。

[dapeng]

我们当时写书时， github 是直接渲染 RMarkdown 的，然而大约半年前，他突然不支持了。详见 https://yihui.name/en/2018/10/rmd-github/。

[robertyan]

谢谢大鹏，看了yihui的解释，理解缘由了。

虽然目前GitHub不支持直接显示R Markdown为Markdown了，但对编辑的影响不大：

1. 在文本编辑器中GitHub对R Markdown编辑时的高亮、加粗，依然遵循了Markdown的语法规则；
2. 预览时虽然不显示结果了，但采用diff的方式也不错。