悟空编辑器从技术博客的内容结构指导技术文档的编写

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了悟空编辑器从技术博客的内容结构指导技术文档的编写相关的知识,希望对你有一定的参考价值。

在上一篇中,我们为了分析技术博客的内容结构,开发了内容结构提取工具,写作的过程中自然激发了论文写作的检查流程,然后就想到能不能基于技术博客的内容结构,给技术博客的编写提供指导建议呢?

1 研究思路

s=>start: 开始
e=>end: 结束

op1=>operation: 查找html文档结构规律
op2=>operation: 列出常用文档片段结构
op3=>operation: 给出文档片段检查建议

s->op1->op2->op3->e

2 查找文档结构规律

2.1 内容的标签结构

HTML 是结构化语言

结构化是指 HTML 页面的框架部分是结构化的,有明确的包含关系,例如:

<html>
	<head>
		<meta ... />
		<title>Sample</title>
	</head>
	<body>
		
	</body>
</html>

HTML 是扁平化语言

扁平化是指 HTML 页面的内容部分是扁平化的,标题、内容处在同一等级,例如:

<h2>研究背景</h2>
<h3>国内现状</h3>
<p>xxx话题近几年被广泛提及,最早对它大规模推广的是...</p>
<p>...</p>
<h3>国外现状</h3>
<p>xxx在欧美的应用比较早,但由于xxx原因,局限于xxx范围。</p>
<p>...</p>
<h2>研究内容</h2>
<p><img /></p>
<h2>实施方案</h2>
<h3>硬件设备</h3>
<p>...</p>
<h3>实施团队</h3>
<p>...</p>
<h3>实施周期</h3>
<p>...</p>

使用标签来描述内容性质,使用 xpath 表示所属关系,可以表示为 h2, h3, p, p/img

假如我们使用空格表示前后关系,使用 < 表示下级关系,使用 > 表示上级关系,那么可以使用 h2 h3 p p h3 p p h2 p < img > h2 h3 p h3 p h3 p 表示结构。

了解了这个特点后,我们可以做出基本的判定:

  • 主要内容是扁平化结构
  • 结构化的标签描述的主要是组件

2.2 常用语义化标签

HTML 标签比较丰富,有些有特定含义,有些可以通用。此处本文选取语义化标签。

顶级标签

  • 使用 h2-h5 表示 2-5 级标题
  • 使用 p 表示内容(内部用正文行、正文块)
  • 使用 blockquote 表示引用(内部用正文行、正文块)
  • 使用 pre/code 表示代码块
  • 使用 ul/li 表示无序列表(内部用正文行)
  • 使用 ol/li 表示有序列表(内部用正文行)
  • 使用 table/thead/tbody/tr/th/td 表示表格(内部用正文行、正文块)

2.3 正文行标签

  • 文字
  • 使用 a 表示超级链接
  • 使用 code 表示行内代码
  • 使用 strong 表示强调
  • 使用 em 表示倾斜
  • 使用 ins 表示下划线
  • 使用 s 表示删除线

正文块标签

  • 使用 img/figure 表示图片
  • 使用 video 表示视频
  • 使用 audio 表示音频

不建议

  • 不建议使用 h1,标题即 h1
  • 不建议使用 h6 或者以后标题,导致层级太深
  • 不建议修改默认字号,破坏阅读观感
  • 不建议使用多种自定义颜色,扰乱色彩体系

3 常用文档片段

3.1 团队技术文章

样本:腾讯云技术文章

选取文章深入解读Raft算法与etcd工程实现,内容节点为 .J-articleContent,路径和使用数量如下:

blockquote < p >                        1
div < pre < code < span > > > button >  8
figure < div < span > >                 30
h3 < strong >                           11
h4 < strong >                           23
ol < li >                               20
p                                       52
p < a < strong > >                      1
p < a >                                 1
p < strong >                            4

样本:阿里云技术文章

选取文章阿里云高性能计算负责人何万青:阿里云大计算加速HPC与AI融合,内容节点为 .lake-engine-view,路径和使用数量如下:

p < strong strong < span > strong < span > >  1
p < span < span < span < span < span < span < span < span < i < svg < path path > > > img span < span > > > > > > > > >24
p < span >                              1
p < br >                                40
p                                       28
p < strong strong >                     1
p < strong < span > >                   7
p < strong >                            6
p < strong < span > strong < span > >   1
p < span strong < span > >              1
p < a >                                 1

样本:百度云技术文章

选取文章亿元免费算力 | 百度大脑AI Studio重磅推出算力支持计划,内容节点为 .markdown-body,路径和使用数量如下:

p < span < img > >                      11
                                        74
p                                       35
p < span >                              21
p < span < strong > >                   4
p < a < img > >                         1
p < span < strong strong > >            1
p < img >                               1
p < span < a > >                        1

这里空白标签是因为使用了<p>&nbsp;</p>作为空行,显然是文章粘贴转写的原因。

样本:美团技术博客

选取文章深入理解函数式编程(上),内容节点为 .content,路径和使用数量如下:

p                                        56
p < strong >                             47
p < img >                                42
h4                                       12
h3                                       6
h2                                       5
ul < li < strong > >                     4
blockquote < p < strong > >              3
ol < li < strong > >                     2
ul < li >                                2
p < strong < a > >                       1

选取文章大规模异构图召回在美团到店推荐广告的应用,内容节点为 .content,路径和使用数量如下:

p                                        23
p < strong >                             14
p < img >                                12
h2                                       9
p < sup >                                6
h3                                       2
ul < li >                                2
p < strong sup >                         1

样本:字条跳动的掘金博客

选取文章构建可扩展模型的几种方案,内容节点为 .markdown-content cache,路径和使用数量如下:

p                                        14
h3                                       7
ul < li >                                6
h2                                       4
h1                                       3
p < img >                                2
ol < li >                                2
table < thead < tr < th > > tbody < tr < td > > > 2
style                                    1
blockquote < p >                         1
blockquote < p < a < strong > > >        1
ul < li < em > li < em > >               1
h1 < strong >                            1

样本:火山引擎技术文章

选取文章CDP市场将迎新增长 火山引擎VeDI旗下的这款产品推出多项新动作,内容节点为 .markdown-body,路径和使用数量如下:

p                                        13
p < em >                                 2
p < img >                                1
p < a >                                  1

3.2 个人博客

样本:阮一峰博客

选取最新一期的电子周刊,内容节点为 #main-content,路径和使用数量如下:

p                                        77
p < a >                                  65
p < img >                                49
h2                                       13
p < code >                               2
blockquote < p >                         1
p < strong >                             1
p < a < code > >                         1
iframe                                   1

样本:廖雪峰教程博客

选取文章构建可扩展模型的几种方案,内容节点为 .x-wiki-content x-main-content,路径和使用数量如下:

p < code >                               15
pre < code >                             9
p                                        7
h3                                       2

样本:Joyee Cheungs Blog

选取文章Fixing snapshot support of class fields in V8,内容节点为 .post-content,路径和使用数量如下:

figure                                   12
p < code >                               12
p                                        7
h3 < a >                                 2
p < a >                                  1
p < code a code >                        1
p < img >                                1

4 文档片段检查

4.1 对样本的基本分析

好的

  • 主体基本都是规范的
  • 引用是一致的
  • 代码块是一致的
  • 段落是一致的

不好的

  • 标题使用不太规范,有的没有 h2,有的使用 p strong 代替 h3/h4,有的标题中存在 strong
  • 使用空行当作段落间距
  • 图像标签的使用存在多层嵌套的情况,较为复杂

4.2 推荐的文档片段检查建议

关于标题

  • 文章标题为 h1
  • 文中标题从 h2 开始
  • 文中标题有合理的层级,中间不跳级
  • 标题不含其他标签

关于引用

  • 使用 blockquote 标签
  • 引用中的内容放在段落内

关于列表

  • 列表使用 ol/ul 标签
  • 列表中允许文字
  • 列表中允许链接 a
  • 列表中允许代码行 code
  • 列表中允许强调strong、斜体em、下划线ins、删除线s

关于图像

  • 普通图片放在 img
  • 学术/技术图片可以放在 figure

关于段落

  • 不使用空行
  • 正文应在段落内
  • 图像 img/figure 应在段落内
  • 代码块 code 应在段落内
  • 段落中允许强调strong、斜体em、下划线ins、删除线s

关于代码块

  • 建议使用 pre/code
  • 不建议层层嵌套

关于表格

  • 建议按标签规范使用
  • 建议存储短文本、数字
  • 不建议存储大量文本内容
  • 不建议存储图片
  • 不建议存储代码块

4.3 典型场景附加建议

短讯、短评

此类文章比较简单,一般不需要建议。

  • 文字,多个段落
  • 图文,至少一张图 + 多个段落

长技术文章

此类文章写作时耗时多,可以启用建议。

  • 代码块:建议代码不超过30行,源文件较长时附加源码链接
  • 图片:建议图片采用实际格式(较小)或者自适应宽度模式(较大)
  • 表格:单个单元格长度内容长度少于50,内容超多的单元格小于10%

以上是关于悟空编辑器从技术博客的内容结构指导技术文档的编写的主要内容,如果未能解决你的问题,请参考以下文章

#聊一聊悟空编辑器# 51CTO博客悟空编辑器体验

# 聊一聊悟空编辑器 #Gin + Swagger快速生成API文档

,直接导入Word文档(支持图片同步)!

安卓手机怎么斜着裁剪图片,一张正方形图片我想把它斜着切掉一半

# 聊一聊悟空编辑器 # 51CTO之悟空编辑器初体验(一个有自己名字的编辑器)

#聊一聊WuKong编辑器#51CTO更文一个月,体验悟空编辑器的那些事儿