showdown 是一个功能强大的命令行工具，用于将 Markdown 文件转换为 HTML 文件，它是著名的 JavaScript 库 Showdown.js 的官方命令行接口（CLI），非常适合在构建流程、自动化脚本或快速转换文档时使用。
安装
在使用 showdown 命令之前，你需要先安装它，最简单的方式是通过 npm（Node.js 包管理器）。
前提条件： 你的系统需要安装 Node.js 和 npm。
安装命令： 打开你的终端或命令行工具，然后运行：
npm install -g showdown
-g 标志表示全局安装，这样你可以在任何地方使用 showdown 命令。
基本用法
最简单的用法是直接将一个 Markdown 文件作为输入，输出 HTML 到终端。
命令格式：
showdown <input-file.md>
示例：
假设你有一个名为 readme.md 的 Markdown 文件，内容如下：
# Hello Showdown 这是一个 **粗体** 文本和一个 *斜体* 文本。 - 列表项 1 - 列表项 2 [访问 GitHub](https://github.com)
在终端中运行：
showdown readme.md
输出： 命令会直接在终端打印出转换后的 HTML 代码：
<h1>Hello Showdown</h1> <p>这是一个 <strong>粗体</strong> 文本和一个 <em>斜体</em> 文本。</p> <ul> <li>列表项 1</li> <li>列表项 2</li> </ul> <p><a href="https://github.com">访问 GitHub</a></p>
常用命令行选项
showdown 提供了许多有用的选项来控制转换行为。
1. 输出到文件 (-o, --output)
这是最常用的选项,用于将转换结果保存到一个 HTML 文件中，而不是打印到终端。
命令格式：
showdown <input-file.md> -o <output-file.html>
示例：
showdown readme.md -o readme.html
执行后,会生成一个 readme.html 文件。
2. 指定扩展 (-e, --extension)
Showdown 支持很多非标准的 Markdown 扩展（如表格、任务列表等），你可以通过这个选项来启用它们。
命令格式：
showdown <input-file.md> -e <extension1,extension2,...>
常用扩展：
tables: 支持表格语法。tasklists: 支持任务列表语法。smartypants: 将引号、破折号等转换为更智能的印刷字符。gh-codeblock: GitHub 风格的代码块（带语言高亮）。strikethrough: 支持删除线语法~~text~~。laxhtmlblocks: 允许在 HTML 块中使用空行。
示例： 转换一个包含表格的 Markdown 文件，并启用表格扩展：
# table.md 内容 | 姓名 | 年龄 | |------|------| | 张三 | 28 | | 李四 | 32 | showdown table.md -e tables -o table.html
table.html 的内容将会是：
<table> <thead> <tr> <th>姓名</th> <th>年龄</th> </tr> </thead> <tbody> <tr> <td>张三</td> <td>28</td> </tr> <tr> <td>李四</td> <td>32</td> </tr> </tbody> </table>
3. 读取标准输入 (stdin)
你可以将 Markdown 内容通过管道（）直接传递给 showdown，这对于脚本处理非常方便。
命令格式：
echo "# Hello from stdin" | showdown
输出：
<h1>Hello from stdin</h1>
4. 查看帮助 (-h, --help)
如果你想查看所有可用的选项和它们的说明,可以使用 --help。
showdown --help
这会列出所有命令行参数,包括我们上面提到的和一些更高级的选项。
高级用法：配置文件
当你有很多自定义选项,并且不想在每次执行时都输入一遍时，可以使用配置文件。
- 创建一个名为
.showdownrc的 JSON 文件（在项目根目录）。 - 在文件中设置你想要的默认选项。
示例 .showdownrc 文件：
{
"extension": "tables,tasklists,strikethrough",
"noHeaderId": true,
"simplifiedAutoLink": true
}
当你运行 showdown 命令时，它会自动读取这个配置文件中的设置，你仍然可以通过命令行参数来覆盖这些配置。
实战示例：构建一个静态网站
假设你的项目结构如下：
my-blog/
├── posts/
│ ├── post1.md
│ └── post2.md
├── template.html
└── build.shtemplate.html (一个简单的 HTML 模板)
<!DOCTYPE html>
<html>
<head>My Blog</title>
</head>
<body>
<!-- 内容将在这里插入 -->
<div id="content">
{{content}}
</div>
</body>
</html>
build.sh (一个简单的构建脚本)
#!/bin/bash
# 创建输出目录
mkdir -p dist
echo "Building posts..."
# 遍历 posts 目录下的所有 .md 文件
for file in posts/*.md; do
# 获取文件名，不带扩展名
filename=$(basename "$file" .md)
# 1. 使用 showdown 将 Markdown 转换为 HTML
# -e tables 启用表格扩展
# --strip-html-tags 移除输入中的 HTML 标签（可选）
showdown "$file" -e tables -o "temp_content.html"
# 2. 使用 sed 或其他工具将转换后的内容插入模板
# 这里我们用一个非常简单的方法：用临时文件内容替换 {{content}}
sed -i "s/{{content}}/$(cat temp_content.html)/" template.html
# 3. 将最终结果保存到 dist 目录
mv template.html "dist/${filename}.html"
# 4. 清理临时文件
rm -f temp_content.html
echo "Built dist/${filename}.html"
done
echo "Build complete!"
如何运行：
- 将
build.sh脚本保存。 - 给它执行权限：
chmod +x build.sh - 运行脚本：
./build.sh
这个脚本会自动将 posts 目录下的所有 Markdown 文件转换为独立的 HTML 文件，并使用模板来保持网站风格的一致性。
| 功能 | 命令/选项 | 描述 |
|---|---|---|
| 基本转换 | showdown file.md |
将 Markdown 转换为 HTML 并输出到终端。 |
| 输出到文件 | showdown file.md -o output.html |
将转换结果保存到指定的 HTML 文件。 |
| 启用扩展 | showdown file.md -e tables,tasklists |
启用一个或多个 Markdown 扩展。 |
| 标准输入 | echo "text" \| showdown |
从管道接收 Markdown 内容并转换。 |
| 查看帮助 | showdown --help |
显示所有可用的命令行选项。 |
| 使用配置 | 创建 .showdownrc |
在 JSON 文件中设置默认选项。 |
showdown 命令是开发者和写作者工具箱中一个非常实用的工具，能够极大地简化 Markdown 到 HTML 的转换工作。
