VS Code + Jekyll Markdown 实用速查

这篇笔记面向当前的 Jekyll/al-folio 站点。VS Code 预览适合检查基础 Markdown，最终效果以 Jekyll 本地预览为准。

1. 文件放在哪里

学习笔记：_imported_notes/<slug>.md
博客文章：_posts/YYYY-MM-DD-<slug>.md
项目页：_projects/<slug>.md
图片：assets/img/，或按主题创建更细的子目录

文件名建议只使用小写英文、数字和连字符，避免空格。

2. Front matter

每篇文章开头都需要 YAML front matter：

---
layout: post
title: "AXI 握手协议学习笔记"
description: "记录 valid/ready 握手的时序规则与常见错误。"
tags: [notes, digital-design, axi]
categories: [notes]
---

title 会由页面布局渲染为一级标题，正文从 ## 开始即可。

3. 基础语法

## 二级标题

### 三级标题

**粗体**、_斜体_、`inline_code`

- 无序列表
- 第二项

1. 有序列表
2. 第二项

```systemverilog
assign ready = !full;
```

4. 站内链接与图片

站内链接优先使用 Jekyll link 标签，文件改名后构建会立即暴露错误：

[查看 Notes]({% link _pages/notes.md %}) [查看 Git 笔记]({% link _imported_notes/tools-git.md %})

图片推荐使用主题自带的响应式组件：

{%
  include figure.liquid
  path="assets/img/example.png"
  title="数据通路结构"
  class="img-fluid rounded z-depth-1"
%}

5. 公式

行内公式使用 $$ ... $$，独立公式也使用双美元符并单独成段：

$$ CPI = \frac{cycles}{instructions} $$

$$
T_{CPU} = IC \times CPI \times T_{clock}
$$

6. 提示块

al-folio 通过 blockquote 类名提供提示、警告和危险样式：

> ##### TIP
>
> 先在仿真中确认握手时序，再进行综合。
{: .block-tip }

可用类名为 .block-tip、.block-warning 和 .block-danger。

7. 标签页

先在 front matter 中开启：

tabs: true

然后使用 Liquid 标签：

{% tabs shell-example %}

{% tab shell-example PowerShell %}
git status
{% endtab %}

{% tab shell-example Bash %}
git status
{% endtab %}

{% endtabs %}

8. Mermaid 图表

先在 front matter 中开启 Mermaid：

mermaid:
  enabled: true
  zoomable: true

再写 mermaid 代码块：

```mermaid
flowchart LR
  Input --> Accelerator --> Output
```

9. 本地预览与构建

在 E:\Projects\blog 中启动 Docker 预览：

docker compose up -d

打开 http://localhost:8080/。修改 Markdown 后会自动重新生成；修改 _config.yml 后建议执行：

docker compose restart

不使用 Docker 时，可在已安装 Ruby 依赖的环境中运行：

bundle exec jekyll serve

提交前至少执行一次完整构建：

bundle exec jekyll build --baseurl /al-folio