sidebar
auto

我的博客

转载我的任何博客都需要注明出处, 禁止断章取义、人身攻击, 禁止用于商业用途

介绍

基于 vitepress 的静态文档网站, 使用 markdown 标记语言写作

环境准备

• node: 10.x 版本以上

写文章可以用各种 markdown 编辑器, 或者任何文本编辑器, 甚至直接在 github 网页上写, 但是有些语法可能会不支持预览(比如图表)

安装使用

使用命令行, 建议配置 github CI/CD

初次安装

npm (安装node附带):

npm i

yarn【建议】:

yarn

生成网站

npm:

npm build

yarn【建议】:

yarn build

目录结构

│
├── docs # 文档目录
│   │── .vitepress # 博客配置代码, 含主题等
│   │── public # 静态资源, 如使用到的图片等
│   │── components # vue组件目录 (任意位置)
│   │
│   │── ... # 自定义博客文档结构 (每个目录都需要一个 index.md 文件, 【不要使用前面的文件夹名】)
│   │
│   └── index.md # 目录对应的默认页
│
├── ... # 项目相关配置文件
│
└── dist # 生成的静态网站

支持markdown语法

插件列表如下 (=>表示生成结果)

• markdown-it-sub

  功能: 下标
  标记: ~内容~
  示例: H~2~0 => H<sub>2</sub>O

• markdown-it-sup

  功能: 上标
  标记: ^内容^
  示例: 29^th^ => 29<sup>th</sup>

• markdown-it-ins

  功能: 插入 (删除: ~~内容~~)
  标记: ++内容++
  示例: ++inserted++ => <ins>inserted</ins>

• markdown-it-abbr

  功能: 缩写
  标记: *[缩写]: 全称
  示例:
    *[HTML]: Hyper Text Markup Language
    *[W3C]:  World Wide Web Consortium
    The HTML specification is maintained by the W3C.
  
    =>
  
  The <abbr title="Hyper Text Markup Language">HTML</abbr> specification is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.

• markdown-it-mark

  功能: 标记 (默认加黄色背景)
  标记: ==内容==
  示例: ==marked== => <mark>inserted</mark>

• markdown-it-katex 支持公式

  功能: 数学公式 katex 语法
  标记: 行内 $katex$ 块级 $$katex$$
  示例: $f(x)$ => <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>f</mi><mo stretchy="false">(</mo><mi>x</mi><mo stretchy="false">)</mo></mrow><annotation encoding="application/x-tex">f(x)</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height: 1em; vertical-align: -0.25em;"></span><span class="mord mathnormal" style="margin-right: 0.10764em;">f</span><span class="mopen">(</span><span class="mord mathnormal">x</span><span class="mclose">)</span></span></span></span>

• markdown-it-latex 数学公式latex/asciimath语法

• markdown-it-deflist

  功能: 定义列表 (<dl>)
  标记:
  项目 (<dt>)
  : 描述 (<dd>)
  示例: 见 https://pandoc.org/MANUAL.html#definition-lists

• markdown-it-footnote

  功能: 脚注
  标记: [^1] 内容 [^1]: 脚注
  示例:
  Here is a footnote reference,[^1] and another.[^longnote]
  
  [^1]: Here is the footnote.
  
  [^longnote]: Here's one with multiple blocks.
  
  Subsequent paragraphs are indented to show that they belong to the previous footnote.
  
  =>
  
  Here is a footnote reference,<sup class="footnote-ref"><a href="#fn1" id="fnref1">[1]</a></sup> and another.<sup class="footnote-ref"><a href="#fn2" id="fnref2">[2]</a></sup>
  <hr class="footnotes-sep">
  <section class="footnotes">
    <ol class="footnotes-list">
      <li id="fn1" class="footnote-item"><p>Here is the footnote. <a href="#fnref1" class="footnote-backref">↩</a></p>
      </li>
      <li id="fn2" class="footnote-item"><p>Here’s one with multiple blocks.</p>
      <p>Subsequent paragraphs are indented to show that they
      belong to the previous footnote. <a href="#fnref2" class="footnote-backref">↩</a></p>
      </li>
    </ol>
  </section>

• markdown-it-img-lazy 懒加载图片, 相同位置文件名前加_o_用于点击浏览大图(都可以浏览大图)

• markdown-it-task-lists

  功能: 任务列表
  标记: 列表项(-/1.): [ ] todo [x] done
  示例:
  - [ ] todo
  - [x] done
  
  =>
  
  <ul class="contains-task-list"><li class="task-list-item"><input class="task-list-item-checkbox" disabled="" type="checkbox"> todo</li><li class="task-list-item"><input class="task-list-item-checkbox" checked="" disabled="" type="checkbox"> done</li></ul>

• markdown-it-html5-media 使用图片标记![描述](链接), 以链接后缀区分媒体类型

• markdown-it-link-attributes 链接属性

• markdown-it-plugin-echarts: 使用eval获取图表配置对象(即: 可以写js)

  width/height: 指定容器宽高, 数字单位为px, 其他单位使用字符串

  {
    width: '100%',
    height: 250,
    xAxis: {
        type: 'category',
        data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
    },
    yAxis: {
        type: 'value'
    },
    series: [
      {
        data: [820, 932, 901, 934, 1290, 1330, 1320],
        type: 'line'
      }
    ]
  }
  

• markdown-it-plugin-mermaid:

  graph TD
  A[Hard] -->|Text| B(Round)
  B --> C{Decision}
  C -->|One| D[Result 1]
  C -->|Two| E[Result 2]
  

  Loading

• markdown-it-plugin-flowchart:

  st=>start: Start:>http://www.google.com[blank]
  e=>end:>http://www.google.com
  op1=>operation: My Operation
  sub1=>subroutine: My Subroutine
  cond=>condition: Yes
  or No?:>http://www.google.com
  io=>inputoutput: catch something...
  para=>parallel: parallel tasks
  
  st->op1->cond
  cond(yes)->io->e
  cond(no)->para
  para(path1, bottom)->sub1(right)->op1
  para(path2, top)->op1
  

• 使用Vue组件

  # Docs
  
  This is a .md using a custom component
  
  <CustomComponent />
  
  ## More docs
  
  ...
  
  <script setup>
  import CustomComponent from '../components/CustomComponent.vue'
  </script>

使用说明

在每个 .md 文件中可以使用如下宏:

// 顶部注释区域, 不显示在正文中
---
// 指定文章标题
title: 文章标题

// 可以通过链接访问, 但不出现在导航链接中 true/false
hide: true

// 指定左侧栏是否显示 可选值为:
// 不指定: 对应目录结构
// auto: 对应文章的目录结构
// false: 不显示
sidebar: auto

// 同目录下的排序, 数字小的在后面
index: 0
---

// 正文区域
// 若注释区未设置标题则使用第一个一级标题
# 文章标题

// 列出当前目录树(仅index.md), 文章目录请使用 markdown 目录语法
<Menu />

公式参考链接: katex asciimath, 可视化

emoji

更多请参考: vitepress

TODO

• markdown 插件:
  • 字体图标(含SVG Symbol)
  • 图片查看/媒体播放
  • 待定
• 标签/归档
• 换肤/背景
• bug: 代码高亮行错位