# markdown-assistant

**Repository Path**: github-9819409/markdown-assistant

## Basic Information

- **Project Name**: markdown-assistant
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Markdown Assistant Tools

![插件主界面](images/readme/index.png)

[中文](#中文说明) | [English](#english)

Markdown Assistant Tools is a VS Code extension that helps you insert common Markdown structures faster. Type `/md` in a Markdown file to open a quick menu and insert headings, lists, tables, code blocks, links, images, notes, and presentation templates powered by Reveal.js.

## 中文说明

### 这是什么

Markdown Assistant Tools 是一个面向 Markdown 写作场景的 VS Code 插件。你只需要在 Markdown 文件中输入 `/md`，就可以快速选择并插入常用 Markdown 模板，减少重复输入。

### 功能特点

- 在 Markdown 文件中输入 `/md`，自动弹出快捷选择菜单
- 支持继续输入关键词进行筛选，例如 `/md he`、`/md ta`
- 选择后直接插入 Markdown 片段，并支持 `Tab` 跳转占位符
- 支持基于 Reveal.js 的演示文档模板、横向页、纵向子页快速插入
- 支持在 VS Code 中实时预览演示内容
- 支持唤起默认浏览器打开本地演示预览，并自动同步编辑内容
- 内置中英文界面
- 插件语言默认跟随 VS Code，也可以在设置中单独切换

### 支持的模板

- Heading
- List
- Markdown Table
- Code Block
- Divider
- Divider
- Quote Block
- Link
- Image
- Note Block
- Presentation Deck
- Slide
- Child Slide

其中：

- `Heading` 可选择 `H1` 到 `H6`
- `List` 可选择无序列表、有序列表、任务列表
- `Markdown Table` 可自定义行数和列数
- `Divider` 可快速插入标准 Markdown 分隔线 `---`
- `Divider` 可快速插入标准 Markdown 分隔线 `---`
- `Presentation Deck` 可插入一份完整的演示模板
- `Slide` 用于插入横向页，分隔标记为 `[//]: # (slide)`
- `Child Slide` 用于插入纵向子页，分隔标记为 `[//]: # (vslide)`
- `Slide` 用于插入横向页，分隔标记为 `[//]: # (slide)`
- `Child Slide` 用于插入纵向子页，分隔标记为 `[//]: # (vslide)`

### 安装方式

1. 打开 VS Code
2. 进入扩展视图
3. 搜索 `Markdown Assistant Tools`
4. 点击安装

### 使用方式

1. 打开一个 Markdown 文件
2. 输入 `/md`
3. 在弹出的菜单中选择需要的内容类型
4. 按 `Enter` 或点击选项插入模板
5. 使用 `Tab` 在占位符之间快速跳转

你也可以继续输入命令进行筛选，例如：

- `/md heading`
- `/md list`
- `/md table`
- `/md code`
- `/md divider`
- `/md divider`
- `/md quote`
- `/md link`
- `/md image`
- `/md note`
- `/md deck`
- `/md slide`
- `/md child`

### 演示文档用法

你可以通过两种方式开始使用演示功能（底层基于 Reveal.js）：

1. 输入 `/md`，选择 `Presentation Deck`、`Slide` 或 `Child Slide`
2. 打开命令面板，执行以下命令：
   - `Markdown Assistant：新建演示文档`
   - `Markdown Assistant：插入横向页`
   - `Markdown Assistant：插入子页`
   - `Markdown Assistant：打开预览`
   - `Markdown Assistant：在浏览器中打开预览`
   - `Markdown Assistant：导出 HTML`
   - `Markdown Assistant：导出 PDF`
   - `Markdown Assistant：导出纯 Markdown`

演示文档的 Markdown 分隔规则：

```markdown
# 演示标题

[//]: # (slide)
[//]: # (slide)

## 横向页 1

[//]: # (vslide)
[//]: # (vslide)

### 纵向子页 1-1
```

- `[//]: # (slide)` 表示新的横向页
- `[//]: # (vslide)` 表示当前主题下的纵向子页
- `[//]: # (slide)` 表示新的横向页
- `[//]: # (vslide)` 表示当前主题下的纵向子页

预览方式：

- 在 VS Code 中执行 `打开预览`：
  - 演示文稿会打开 Reveal 侧边预览
  - 普通 Markdown 会调用 VS Code 自带的 Markdown 预览
- 在浏览器中执行 `在浏览器中打开预览`：
  - 演示文稿会打开 Reveal 浏览器预览
  - 普通 Markdown 会打开可滚动的标准网页预览
- 编辑 Markdown 后，浏览器预览会自动同步刷新

导出方式：

- `导出 HTML`：若当前文档包含 Reveal 分隔标记，则生成 Reveal.js HTML；普通 Markdown 会自动导出为可滚动的标准网页
- `导出 PDF`：若当前文档包含 Reveal 分隔标记，则按演示稿方式导出 PDF；普通 Markdown 会自动按标准文档分页打印，避免只导出一屏
- `导出纯 Markdown`：移除 `[//]: # (slide)`、`[//]: # (vslide)` 等演示分隔标记
- 导出文件命名规则为：`当前文件名-时间戳.扩展名`

### Front Matter 覆盖

演示文档支持在 Markdown 文件头使用 YAML front matter 的 `reveal` 块按文件覆盖全局 Reveal 设置，例如：

```markdown
---
reveal:
  theme: dracula
  transition: fade
  slideNumber: off
---

# 演示标题
```

未在 front matter 中显式配置的项将回退到 VS Code 设置中的默认值。

### 插件设置

本插件目前提供以下设置：

- `Markdown Assistant Tools: Language`
  - `auto`: 跟随 VS Code 显示语言
  - `en`: 强制使用英文
  - `zh-CN`: 强制使用简体中文
- `Markdown Assistant Tools: Enable Slash Menu`
  - 控制是否启用 `/md` 触发菜单

演示文档相关设置（均可被 front matter 的 `reveal` 块按文件覆盖）：

- `Markdown Assistant Tools: Reveal Theme`
  - 演示主题，默认 `black`，可选 `beige`、`black`、`black-contrast`、`blood`、`dracula`、`league`、`moon`、`night`、`serif`、`simple`、`sky`、`solarized`、`white`、`white-contrast`
- `Markdown Assistant Tools: Reveal Highlight Theme`
  - 代码高亮主题，默认 `monokai`，可选 `monokai`、`zenburn`
- `Markdown Assistant Tools: Reveal Transition`
  - 幻灯片转场动画，默认 `slide`，可选 `none`、`fade`、`slide`、`convex`、`concave`、`zoom`
- `Markdown Assistant Tools: Reveal Transition Speed`
  - 转场速度，默认 `default`，可选 `default`、`slow`、`fast`
- `Markdown Assistant Tools: Reveal Background Transition`
  - 整页背景转场动画，默认 `fade`
- `Markdown Assistant Tools: Reveal Controls Layout`
  - 控制按钮位置，默认 `bottom-right`，可选 `bottom-right`、`edges`
- `Markdown Assistant Tools: Reveal Slide Number`
  - 页码格式，默认 `c/t`，可选 `off`、`c/t`、`h/v`、`h.v`、`c`、`all`
- `Markdown Assistant Tools: Reveal Controls`：显示导航控制按钮，默认 `true`
- `Markdown Assistant Tools: Reveal Progress`：显示进度条，默认 `true`
- `Markdown Assistant Tools: Reveal Center`：垂直居中幻灯片，默认 `true`
- `Markdown Assistant Tools: Reveal Overview`：启用概览模式，默认 `true`
- `Markdown Assistant Tools: Reveal Fragments`：启用片段动画，默认 `true`
- `Markdown Assistant Tools: Reveal Hash`：将导航状态写入 URL hash，默认 `true`
- `Markdown Assistant Tools: Reveal Keyboard`：启用键盘导航，默认 `true`
- `Markdown Assistant Tools: Reveal Auto Animate`：启用自动动画，默认 `true`
- `Markdown Assistant Tools: Reveal Auto Animate Easing`：自动动画缓动函数，默认 `ease-in-out`
- `Markdown Assistant Tools: Reveal Auto Animate Duration`：自动动画时长（秒），默认 `1.2`

### 适用场景

- 快速写技术文档
- 整理会议纪要
- 编写项目 README
- 记录学习笔记
- 生成规范的任务列表和 Markdown 表格

---

## English

### What It Does

Markdown Assistant Tools is a VS Code extension for faster Markdown writing. Type `/md` inside a Markdown file to open a quick menu and insert common Markdown templates, including Reveal.js presentation decks, without writing them by hand.

### Features

- Type `/md` in a Markdown file to open a quick insert menu
- Keep typing to filter items, such as `/md he` or `/md ta`
- Insert ready-to-use Markdown snippets with `Tab` navigation between placeholders
- Quick insert for Reveal.js presentation decks, horizontal slides, and vertical child slides
- Live preview of presentations inside VS Code
- Open a local browser preview that auto-refreshes as you edit
- Built-in English and Simplified Chinese UI
- Extension language follows VS Code by default, with manual override available in Settings

### Supported Templates

- Heading
- List
- Markdown Table
- Code Block
- Divider
- Divider
- Quote Block
- Link
- Image
- Note Block
- Presentation Deck
- Slide
- Child Slide

Details:

- `Heading` supports `H1` to `H6`
- `List` supports unordered, ordered, and checklist formats
- `Markdown Table` lets you choose custom rows and columns
- `Divider` inserts the standard Markdown horizontal rule `---`
- `Presentation Deck` inserts a full presentation template
- `Slide` inserts a horizontal slide, separator is `[//]: # (slide)`
- `Child Slide` inserts a vertical child slide, separator is `[//]: # (vslide)`

### Installation

1. Open VS Code
2. Go to the Extensions view
3. Search for `Markdown Assistant Tools`
4. Click Install

### How To Use

1. Open a Markdown file
2. Type `/md`
3. Pick the content type you want from the quick menu
4. Press `Enter` or click an item to insert it
5. Use `Tab` to move through snippet placeholders

You can also type a longer command to filter suggestions, for example:

- `/md heading`
- `/md list`
- `/md table`
- `/md code`
- `/md divider`
- `/md divider`
- `/md quote`
- `/md link`
- `/md image`
- `/md note`
- `/md deck`
- `/md slide`
- `/md child`

### Settings

The extension currently provides these settings:

- `Markdown Assistant Tools: Language`
  - `auto`: Follow the VS Code display language
  - `en`: Force English
  - `zh-CN`: Force Simplified Chinese
- `Markdown Assistant Tools: Enable Slash Menu`
  - Enable or disable the `/md` trigger menu

Presentation-related settings (all can be overridden per file via a `reveal` block in the Markdown front matter):

- `Markdown Assistant Tools: Reveal Theme`
  - Presentation theme, default `black`, options: `beige`, `black`, `black-contrast`, `blood`, `dracula`, `league`, `moon`, `night`, `serif`, `simple`, `sky`, `solarized`, `white`, `white-contrast`
- `Markdown Assistant Tools: Reveal Highlight Theme`
  - Code highlight theme, default `monokai`, options: `monokai`, `zenburn`
- `Markdown Assistant Tools: Reveal Transition`
  - Slide transition, default `slide`, options: `none`, `fade`, `slide`, `convex`, `concave`, `zoom`
- `Markdown Assistant Tools: Reveal Transition Speed`
  - Transition speed, default `default`, options: `default`, `slow`, `fast`
- `Markdown Assistant Tools: Reveal Background Transition`
  - Full-page background transition, default `fade`
- `Markdown Assistant Tools: Reveal Controls Layout`
  - Control button position, default `bottom-right`, options: `bottom-right`, `edges`
- `Markdown Assistant Tools: Reveal Slide Number`
  - Slide number format, default `c/t`, options: `off`, `c/t`, `h/v`, `h.v`, `c`, `all`
- `Markdown Assistant Tools: Reveal Controls`: Show navigation controls, default `true`
- `Markdown Assistant Tools: Reveal Progress`: Show progress bar, default `true`
- `Markdown Assistant Tools: Reveal Center`: Vertically center slides, default `true`
- `Markdown Assistant Tools: Reveal Overview`: Enable overview mode, default `true`
- `Markdown Assistant Tools: Reveal Fragments`: Enable fragment animations, default `true`
- `Markdown Assistant Tools: Reveal Hash`: Persist slide navigation in URL hash, default `true`
- `Markdown Assistant Tools: Reveal Keyboard`: Enable keyboard navigation, default `true`
- `Markdown Assistant Tools: Reveal Auto Animate`: Enable auto animations, default `true`
- `Markdown Assistant Tools: Reveal Auto Animate Easing`: Auto-animate easing function, default `ease-in-out`
- `Markdown Assistant Tools: Reveal Auto Animate Duration`: Auto-animate duration in seconds, default `1.2`

### Best For

- Writing technical documentation
- Taking structured notes
- Creating project READMEs
- Keeping learning notes organized
- Building task lists and Markdown tables quickly
- Drafting slide decks with Markdown and Reveal.js

### Presentation Workflow

You can start a presentation in two ways. Reveal.js is used under the hood:

1. Type `/md` and choose `Presentation Deck`, `Slide`, or `Child Slide`
2. Open the Command Palette and run:
   - `Markdown Assistant: Create Presentation Deck`
   - `Markdown Assistant: Insert Slide`
   - `Markdown Assistant: Insert Child Slide`
   - `Markdown Assistant: Open Preview`
   - `Markdown Assistant: Open Preview in Browser`
   - `Markdown Assistant: Export HTML`
   - `Markdown Assistant: Export PDF`
   - `Markdown Assistant: Export Plain Markdown`
3. Right-click inside a Markdown editor, or right-click a `.md` file in Explorer, then choose `Markdown Assistant: Open Presentation Preview`

Presentation Markdown separators:

```markdown
# Presentation Title

[//]: # (slide)
[//]: # (slide)

## Horizontal Slide

[//]: # (vslide)
[//]: # (vslide)

### Vertical Child Slide
```

- `[//]: # (slide)` creates a new horizontal slide
- `[//]: # (vslide)` creates a vertical child slide under the current group
- `[//]: # (slide)` creates a new horizontal slide
- `[//]: # (vslide)` creates a vertical child slide under the current group

Preview options:

- `Open Preview` uses Reveal preview for slide decks and VS Code's built-in Markdown preview for regular Markdown
- `Open Preview in Browser` uses Reveal browser preview for slide decks and a scrollable standard web preview for regular Markdown
- Browser preview auto-refreshes while you edit the Markdown document

Export options:

- `Export HTML` generates Reveal.js HTML for slide decks, and automatically exports regular Markdown as a scrollable standard web page
- `Export PDF` exports slide decks as Reveal PDFs, and automatically prints regular Markdown as a paginated document PDF
- `Export Plain Markdown` removes Reveal slide separator markers from the current document
- Exported files are named as `current-file-name-timestamp.ext`

### Front Matter Override

Presentation decks support overriding global Reveal settings per file via a `reveal` block in the YAML front matter, for example:

```markdown
---
reveal:
  theme: dracula
  transition: fade
  slideNumber: off
---

# Presentation Title
```

Keys not explicitly set in the front matter fall back to the VS Code settings defaults.