Markdown 文档编辑指南
Markdown 介绍
Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档。
Markdown 编写的文档后缀为 .md。
Markdown 在线教程
Markdown 指南
文档命名
- 文档名称以 .md 结尾，如：01_markdown.md
- 文档名称以数字开头，数字与文档名称之间用下划线分隔，如：01_markdown.md，这样侧边栏文件能够按照数字排序。
- 文档一级目录的名称既是侧边栏文档名称。
文档编辑指南
docusaurus 在线文档
https://docusaurus.io/zh-CN/docs
docusaurus 安装
https://docusaurus.io/zh-CN/docs/installation
文档编写注意事项
注意
- 支持 Markdown 标准语法及 GitHub Flavored Markdown 扩展 - 换行时，末尾加两个及以上空格 - html 代码段，<tag>需要成对出现，如 <tag> </tag> - 文章正文中出现的{、<、\ 需要加转义符 \, 如 \{、\<、\\ - 我写了一个代码格式校正工具，可酌情使用，并注意自己做好检查和备份 下载文件 - python 文件下载
MarkDownSyntaxAdjust.py
import re
from bs4 import BeautifulSoup
import os
import glob
class MarkDownSyntaxAdjust:
contentLines = []
adjustLines = []
def __init__(self, contentLines):
self.contentLines = contentLines
def adjustSyntax(self):
isCode = False
segmentLines = []
for i, line in enumerate(self.contentLines):
codeline = line.lstrip()
if(codeline.startswith("```")):
isCode = not isCode
if(isCode):
self.adjustLines= self.adjustLines + self.space(self.chars(self.html(segmentLines)))
segmentLines.clear()
segmentLines.append(line)
else:
segmentLines.append(line)
self.adjustLines=self.adjustLines + self.code(segmentLines)
segmentLines.clear()
else:
segmentLines.append(line)
if(len(segmentLines)>0):
self.adjustLines=self.adjustLines + self.space(self.html(self.chars(segmentLines)))
segmentLines.clear()
return
def code(self,lines):
return lines
#html内容格式化，填补未封闭tag
def html(self,lines):
merged_string = ''.join(lines)
soup = BeautifulSoup(merged_string, 'html.parser')
return [s + '\n' for s in soup.prettify().split("\n")]
#行末加上两个空格
def space(self,lines):
for i, line in enumerate(lines):
strs = line.split('\n')
if(not strs[0].endswith(" ")):
lines[i] = strs[0]+" "+"\n"
#print(lines[i])
return lines
#替换特殊字符
def chars(self,lines):
specialChars = ["{"]
newLines=[]
for i, line in enumerate(lines):
# 使用正则表达式替换
replacedLine =line
for sChar in specialChars:
pattern = r'(?<!\\)' + sChar
if(re.search(pattern,replacedLine)):
replacedLine=re.sub(pattern, r'\\'+sChar, replacedLine)
newLines.append(replacedLine)
return newLines
def adjustFile(fileName,saveOldFile):
contentLines = []
with open(fileName, 'r', encoding='utf-8') as file:
contentLines = file.readlines()
adjuster = MarkDownSyntaxAdjust(contentLines)
adjuster.adjustSyntax() # 写回文件
with open(fileName, 'w', encoding='utf-8') as file:
file.writelines(adjuster.adjustLines)
if saveOldFile:
with open(fileName+'\_back', 'w', encoding='utf-8') as file:
file.writelines(adjuster.contentLines)
def adjustDir(dirPath,saveOldFile):
mdFiles = []
for root, dirs, files in os.walk(dirPath):
for file in files:
if file.endswith('.md'):
mdFiles.append(os.path.join(root, file))
for file in mdFiles:
print(file)
adjustFile(file,saveOldFile)
# 校正一个文件
#fileName = 'C:/study/mt-document-preview/driver/alphacore/alphacore-doc-online/01_introduction.md'
#adjustFile(fileName)
# 校正一个目录下所有文件
dirPath = 'C:/study/mt-document-preview/driver/alphacore'
saveOldFile = True #原有文件将被保存为 \*\*\_back 文件
adjustDir(dirPath,saveOldFile)
- 图片和下载文件
- 图片和下载的pdf文件，可以放在static目录下，编译后 static目录既是 web页面的根目录，如 \static\images\20240509\1.png，转换成web资源就是/images/20240509/1.png。我已经给各个产品在static/download建了产品名称目录，图片、文件都放在对应目录下就可以了，引用URL就是 /download/产品路径/资源文件名称
- 如果要调整图片尺寸，只能用html代码实现，如
-
<img src="/img/img_s3000/s3000_install_raiser_in.png" width="100" height="100" alt="示例图片"></img> - 提交代码前，先在自己开发环境验证一下
标题
文档中的标题会显示在右侧侧边栏中，注意，右侧侧边栏是从二级标题开始的，一篇文档仅提供一个一级标题，以文章名称的格式出现。
标题代码示例
# Markdown 文档编辑指南
## Markdown 介绍
Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档。
Markdown 编写的文档后缀为 .md。
[Markdown 在线教程](https://www.runoob.com/markdown/md-tutorial.html/)
[Markdown 指南](https://www.markdown.xyz/)
## 基于 docusaurus 的 Markdown 文档编辑指南
### 标题
文档中的标题会显示在右侧侧边栏中，注意，右侧侧边栏是从二级标题开始的，一篇文档仅提供一个一级标题，以文章名称的格式出现。
## 二级标题
### 三级标题
### 四级标题
正文
这是一个粗体字 ，这是一个斜体字，这是一个粗斜体字。
这是一个删除线。
这是一个下划线
这是一个链接。
这是一个链接。
这是一个图片
备注
换行需要在行末增加两个或以上空格
提示
换行需要在行末增加两个或以上空格
信息
换行需要在行末增加两个或以上空格
注意
换行需要在行末增加两个或以上空格
危险
换行需要在行末增加两个或以上空格
正文代码示例
这是一个**粗体字** ，这是一个*斜体字*，这是一个**_粗斜体字_**。
这是一个~~删除线~~。
<u>这是一个下划线</u>
这是一个[链接](https://www.baidu.com)。
这是一个[链接](https://www.baidu.com "百度")。
这是一个图片
:::note
**换行需要在行末增加两个或以上空格**
:::
:::tip
**换行需要在行末增加两个或以上空格**
:::
:::info
**换行需要在行末增加两个或以上空格**
:::
:::warning
**换行需要在行末增加两个或以上空格**
:::
:::danger
**换行需要在行末增加两个或以上空格**
:::
列表
无序列表
- 第一项
- 第二项
- 第三项
有序列表
- 第一项
- 第二项
- 第三项
列表嵌套
- 第一项：
- 第一项嵌套的第一个元素
- 第一项嵌套的第二个元素
- 第二项：
- 第二项嵌套的第一个元素
- 第二项嵌套的第二个元素
列表代码示例
无序列表
- 第一项
- 第二项
- 第三项
有序列表
1. 第一项
2. 第二项
3. 第三项
列表嵌套
1. 第一项：
- 第一项嵌套的第一个元素
- 第一项嵌套的第二个元素
2. 第二项：
- 第二项嵌套的第一个元素
- 第二项嵌套的第二个元素
代码
def hello():
print("hello world")
return "hello world"
```python
def hello():
print("hello world")
return "hello world"
```
表格
| 左对齐 | 右对齐 | 居中对齐 |
|---|---|---|
| 1 | 2 | 3 |
| 4 | 5 | 6 |
| 左对齐 | 右对齐 | 居中对齐 |
| :----- | -----: | :------: |
| 1 | 2 | 3 |
| 4 | 5 | 6 |
区块
最外层
第一层嵌套
第二层嵌套
> 最外层
>
> > 第一层嵌套
> >
> > > 第二层嵌套
可折叠内容
可折叠内容示例
无序列表
- 第一项
- 第二项
- 第三项
有序列表
1. 第一项
2. 第二项
3. 第三项
列表嵌套
1. 第一项：
- 第一项嵌套的第一个元素
- 第一项嵌套的第二个元素
2. 第二项：
- 第二项嵌套的第一个元素
- 第二项嵌套的第二个元素
可折叠内容示例
<details>
<summary>可折叠内容示例</summary>
<div>
```markdown
无序列表
- 第一项
- 第二项
- 第三项
有序列表
1. 第一项
2. 第二项
3. 第三项
列表嵌套
1. 第一项：
- 第一项嵌套的第一个元素
- 第一项嵌套的第二个元素
2. 第二项：
- 第二项嵌套的第一个元素
- 第二项嵌套的第二个元素
```
</div>
</details>
