Skip to content

Commit 3cb7cce

Browse files
Paulkm2006Paulkm2006
authored
feat: side-by-side显示markdown代码和预览 (#120)
* feat: side-by-side display of markdown source and render output * fix: structure * lint
1 parent bc2f9ee commit 3cb7cce

File tree

5 files changed

+163
-53
lines changed

5 files changed

+163
-53
lines changed

‎docs/ch3/sec0/1-basic.md

Lines changed: 15 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Markdown 是一种轻量级标记语言，具有**语法简洁、易读易写**
1010

1111
使用 `#` 表示标题，`#` 的数量决定标题级别（从 1 级到 6 级）。合理设置标题层级，有助于提升文档结构清晰度，方便他人快速查找所需。
1212

13-
```markdown
13+
```md preview
1414
# 一级标题
1515
## 二级标题
1616
### 三级标题
@@ -23,31 +23,33 @@ Markdown 是一种轻量级标记语言，具有**语法简洁、易读易写**
2323

2424
直接输入文本即为一个段落，段落之间需空一行。例如：
2525

26-
```markdown
26+
```md preview
2727
这是第一段。
2828

2929
这是第二段。
3030
```
3131

3232
如需在同一段落内换行，可在行末添加两个空格后回车：
3333

34-
```markdown
34+
```md preview
3535
这是第一行。(注意当前行最后有两个空格)
3636
这是第二行。
3737
```
3838

3939
## 3. 强调
4040

41+
```md preview
4142
- **加粗**：`**加粗**` 或 `__加粗__`
4243
- *斜体*：`*斜体*` 或 `_斜体_`
4344
- ~~删除线~~：`~~删除线~~`
45+
```
4446

4547
## 4. 列表
4648

4749
- 无序列表：使用 `-`、`*` 或 `+`
4850
- 有序列表：使用数字加点
4951

50-
```markdown
52+
```md preview
5153
- 项目 1
5254
- 项目 2
5355

@@ -61,7 +63,7 @@ Markdown 是一种轻量级标记语言，具有**语法简洁、易读易写**
6163
- 图片：`![描述](图片地址)`
6264
- 可点击的图片：`[![描述](图片地址)](点击后打开的地址)`
6365

64-
```markdown
66+
```md preview
6567
[百度](https://www.baidu.com)
6668
![Logo](https://oss.hust.openatom.club/assets/logo.png)
6769
[![Logo](https://oss.hust.openatom.club/assets/logo.png)](https://hust.openatom.club)
@@ -80,8 +82,8 @@ Markdown 是一种轻量级标记语言，具有**语法简洁、易读易写**
8082

8183
使用 `>` 表示引用。
8284

83-
```markdown
84-
> 这是一个引用
85+
```md preview
86+
> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
8587
```
8688

8789
## 7. 代码
@@ -91,22 +93,15 @@ Markdown 是一种轻量级标记语言，具有**语法简洁、易读易写**
9193
- 行内代码：用反引号包裹，如 `` `print()` ``
9294
- 代码块：用三个反引号包裹。通常来说，Markdown 编辑器能自动识别代码语言并高亮；但当遇到识别错误时，我们可以使用 ` ```<语言名称> ` 来告诉编辑器。
9395

96+
```md preview
9497
```python
9598
print("Hello, Markdown!")
9699
```
97-
98-
```c
99-
#include <stdio.h>
100-
int main()
101-
{
102-
printf("Hello, Markdown!");
103-
return 0;
104-
}
105100
```
106101
107102
## 8. 表格
108103
109-
```markdown
104+
```md preview
110105
| 姓名 | 年龄 |
111106
| ---- | ---- |
112107
| 张三 | 18 |
@@ -162,10 +157,10 @@ int main()
162157
// 这是一段 C++ 代码，我们通常使用 cpp 表示 C++
163158
#include <iostream>
164159

165-
int main(){
166-
std::cout << "Hello, world!" << std::endl;
167-
}
168-
```
160+
int main(){
161+
std::cout << "Hello, world!" << std::endl;
162+
}
163+
```
169164

170165
| 这是 | 一张 | 表格 |
171166
| :---- | :----: | ---- |

‎docs/ch3/sec0/2-advanced.md

Lines changed: 8 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -32,16 +32,13 @@ $$
3232

3333
Markdown 支持直接嵌入原生 HTML 标签，以实现更复杂的排版和样式。例如：
3434

35-
```html
36-
<!-- 插入一个带颜色的段落并居中 -->
37-
<p style="color: red;text-align: center;">这是一个红色的段落。</p>
35+
```md preview
3836

39-
<!-- 插入图片，自定义大小并居中 -->
37+
<p style="color: red;text-align: center;">这是一个红色的段落。</p>
4038
<p align="center">
41-
<img src="https://oss.hust.openatom.club/assets/logo.png" width="200" />
39+
<img src="https://oss.hust.openatom.club/assets/logo.png" alt="OpenAtom Club Logo" width="200" />
4240
</p>
4341

44-
<!-- 使用 HTML 插入表格（不推荐） -->
4542
<table>
4643
<tr>
4744
<td>Foo</td>
@@ -55,22 +52,6 @@ Markdown 支持直接嵌入原生 HTML 标签，以实现更复杂的排版和
5552

5653
```
5754

58-
<p style="color: red;text-align: center;">这是一个红色的段落。</p>
59-
<p align="center">
60-
<img src="https://oss.hust.openatom.club/assets/logo.png" alt="OpenAtom Club Logo" width="200" />
61-
</p>
62-
63-
<table>
64-
<tr>
65-
<td>Foo</td>
66-
<td>Bar</td>
67-
</tr>
68-
<tr>
69-
<td>Hello</td>
70-
<td>World</td>
71-
</tr>
72-
</table>
73-
7455
!!! tips
7556

7657
部分 Markdown 渲染器可能会限制某些 HTML 标签的使用。若非特殊情况，请尽量使用原生Markdown语法而不是HTML标签。
@@ -79,14 +60,16 @@ Markdown 支持直接嵌入原生 HTML 标签，以实现更复杂的排版和
7960

8061
部分 Markdown 编辑器或平台（如 Typora、Obsidian、Jupyter Notebook、Github）支持通过代码块插入图表，常见语法有 Mermaid。
8162

63+
```md preview
8264
```mermaid
8365
graph TD
8466
A[开始] --> B{条件判断}
85-
B -- 是 --> C[处理1]
86-
B -- 否 --> D[处理2]
67+
B -- 是 --> C[处理 1]
68+
B -- 否 --> D[处理 2]
8769
C --> E[结束]
8870
D --> E
8971
```
72+
```
9073
9174
Mermaid 提供了[在线的图标编辑器](https://www.mermaidchart.com/play)，编辑好后复制左侧 Markdown 代码即可。
9275
@@ -108,7 +91,7 @@ Mermaid 提供了[在线的图标编辑器](https://www.mermaidchart.com/play)
10891
10992
徽章（Badge）是一种小型的图标标签，常用于展示项目状态、版本信息、构建状态等。在 Markdown 中，我们可以通过图片链接的方式插入徽章。
11093
111-
```markdown
94+
```md preview
11295
展示 Github Star 状态
11396
![GitHub stars](https://img.shields.io/github/stars/hust-open-atom-club/intro2oss?style=social)
11497
@@ -125,12 +108,6 @@ Mermaid 提供了[在线的图标编辑器](https://www.mermaidchart.com/play)
125108
![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge&logo=rust&logoColor=white)
126109
```
127110

128-
效果如下：
129-
![GitHub stars](https://img.shields.io/github/stars/hust-open-atom-club/intro2oss?style=social)
130-
![License](https://img.shields.io/badge/license-MIT-blue.svg)
131-
![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)
132-
![Version](https://img.shields.io/badge/version-1.0.0-green.svg)
133-
![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge&logo=rust&logoColor=white)
134111

135112
可以访问 [shields.io](https://shields.io/) 来生成自定义的徽章。
136113

‎docs/stylesheets/extra.css

Lines changed: 134 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,137 @@
77
color: gray;
88
margin-top: -10px;
99
text-align: center;
10-
}
10+
}
11+
12+
/* Markdown Preview Plugin Styles */
13+
.markdown-preview-container {
14+
margin: 1.5em 0;
15+
border: 1px solid var(--md-default-fg-color--lighter);
16+
border-radius: 0.2rem;
17+
background-color: var(--md-code-bg-color);
18+
overflow: hidden;
19+
}
20+
21+
.markdown-preview-wrapper {
22+
display: flex;
23+
min-height: 200px;
24+
overflow-x: auto;
25+
min-width: 100%;
26+
}
27+
28+
.markdown-preview-left,
29+
.markdown-preview-right {
30+
flex: 1;
31+
min-width: 300px;
32+
max-width: 50%;
33+
display: flex;
34+
flex-direction: column;
35+
white-space: nowrap;
36+
}
37+
38+
.markdown-preview-left {
39+
border-right: 1px solid var(--md-default-fg-color--lighter);
40+
}
41+
42+
.markdown-preview-header {
43+
background-color: var(--md-default-fg-color--lightest);
44+
padding: 0.5rem 1rem;
45+
font-weight: 600;
46+
font-size: 0.9rem;
47+
border-bottom: 1px solid var(--md-default-fg-color--lighter);
48+
color: var(--md-default-fg-color--light);
49+
white-space: nowrap;
50+
overflow: hidden;
51+
text-overflow: ellipsis;
52+
}
53+
54+
.markdown-preview-content {
55+
flex: 1;
56+
padding: 1rem;
57+
overflow: auto;
58+
white-space: nowrap;
59+
}
60+
61+
.markdown-preview-left .markdown-preview-content {
62+
background-color: var(--md-code-bg-color);
63+
}
64+
65+
.markdown-preview-left .markdown-preview-content pre {
66+
margin: 0;
67+
background-color: transparent;
68+
border: none;
69+
padding: 0;
70+
white-space: pre;
71+
overflow-x: auto;
72+
overflow-y: auto;
73+
}
74+
75+
.markdown-preview-left .markdown-preview-content code {
76+
background-color: transparent;
77+
padding: 0;
78+
font-size: 0.85em;
79+
line-height: 1.4;
80+
white-space: pre;
81+
display: block;
82+
overflow-x: auto;
83+
}
84+
85+
.markdown-preview-right .markdown-preview-content {
86+
background-color: var(--md-default-bg-color);
87+
white-space: normal;
88+
}
89+
90+
.markdown-preview-rendered {
91+
min-width: 100%;
92+
overflow-x: auto;
93+
}
94+
95+
.markdown-preview-rendered>*:first-child {
96+
margin-top: 0 !important;
97+
}
98+
99+
.markdown-preview-rendered>*:last-child {
100+
margin-bottom: 0 !important;
101+
}
102+
103+
.markdown-preview-rendered table {
104+
min-width: 100%;
105+
white-space: nowrap;
106+
}
107+
108+
.markdown-preview-rendered pre {
109+
overflow-x: auto;
110+
white-space: pre;
111+
}
112+
113+
.markdown-preview-rendered code {
114+
white-space: pre;
115+
}
116+
117+
/* Responsive design */
118+
@media screen and (max-width: 768px) {
119+
.markdown-preview-wrapper {
120+
flex-direction: column;
121+
overflow-x: visible;
122+
}
123+
124+
.markdown-preview-left,
125+
.markdown-preview-right {
126+
max-width: none;
127+
min-width: 100%;
128+
}
129+
130+
.markdown-preview-left {
131+
border-right: none;
132+
border-bottom: 1px solid var(--md-default-fg-color--lighter);
133+
}
134+
135+
.markdown-preview-content {
136+
overflow-x: auto;
137+
white-space: nowrap;
138+
}
139+
140+
.markdown-preview-right .markdown-preview-content {
141+
white-space: normal;
142+
}
143+
}

‎mkdocs.yml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,11 @@ extra_css:
1010
- stylesheets/extra.css
1111

1212
plugins:
13-
- mkdocs-audio
13+
- mkdocs-audio
14+
- md-preview:
15+
enable: true
16+
left_title: "Markdown 源码"
17+
right_title: "渲染输出"
1418

1519
theme:
1620
name: 'material'

‎requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ mkdocs
22
mkdocs-material
33
mkdocs-audio
44
pymdown-extensions
5+
mkdocs-md-preview

0 commit comments

Comments
 (0)