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

Posted 2022-12-01

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> </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