【悟空编辑器】从技术博客的内容结构指导技术文档的编写-CFANZ编程社区

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

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> </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 Cheung's 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