TUTORIAL

Markdown 转静态网站

Markdown 转静态网站

发布时间：2026-08-13 作者：尧图建站 频道：轻量化站点开发
Markdown 转静态网站

写文章最舒服的格式是什么？绝大多数技术人会回答 Markdown——纯文本、语法简单、可读性强、版本控制友好。但浏览器看不懂 Markdown，只认 HTML。把 Markdown 转成静态网站，就是搭一座"写作体验"与"发布效果"之间的桥：你用 Markdown 写内容，工具自动转成带样式的 HTML 页面。本篇从底层解析到实战搭建，带你跑通整个流程。

一、Markdown 解析原理：从纯文本到 HTML

Markdown 转 HTML 的核心是"解析器"——它把 Markdown 文本按语法规则拆解，转换成对应的 HTML 标签。# 标题 变 <h1>标题</h1>，- 列表项 变 <ul><li>列表项</li></ul>。主流解析器有 marked（JS）、markdown-it（JS）、CommonMark（多语言）。解析过程分两步：词法分析把文本切成 token，语法分析把 token 组装成 HTML 树。

// 用 marked 把 Markdown 转成 HTML
const marked = require('marked');

const mdText = `
# 尧图建站教程

尧图提供**一站式建站**服务。

- 品牌官网定制
- 营销型官网开发
- 老旧网站改版

\`\`\`html
<a href="contact.html">联系我们</a>
\`\`\`
`;

// 基础转换
const html = marked.parse(mdText);
console.log(html);
/* 输出：
<h1 id="尧图建站教程">尧图建站教程</h1>
<p>尧图提供<strong>一站式建站</strong>服务。</p>
<ul>
<li>品牌官网定制</li>
<li>营销型官网开发</li>
<li>老旧网站改版</li>
</ul>
<pre><code class="language-html">...</code></pre>
*/

// 自定义渲染器：给 h2 加锚点、给外链加 target="_blank"
const renderer = new marked.Renderer();
renderer.heading = (text, level) => {
  const id = text.replace(/\s/g, '-').toLowerCase();
  return `<h${level} id="${id}">${text}</h${level}>`;
};
renderer.link = (href, title, text) => {
  const external = href.startsWith('http') ? ' target="_blank" rel="noopener"' : '';
  return `<a href="${href}"${external}>${text}</a>`;
};
marked.use({ renderer });

自定义渲染器是 Markdown 工具的"扩展点"——尧图在技术文档站里，用自定义渲染器给代码块加了"复制按钮"、给图片加了懒加载属性、给表格加了响应式包裹层。这些定制完全不动核心解析逻辑，只在渲染环节拦截输出，非常优雅。

二、Front Matter：给文章加元数据

光有正文不够，文章还有标题、发布日期、分类、标签、封面图等元数据。Markdown 标准没规定怎么写元数据，社区约定用"Front Matter"——在文件开头用三横线包裹一段 YAML，解析时单独提取，不进正文。几乎所有 SSG（Hexo、Hugo、Jekyll）都支持这个规范。

---
title: Markdown 转静态网站实战
date: 2026-08-13
author: 尧图建站
category: 轻量化站点开发
tags: [Markdown, Hexo, 静态网站]
cover: images/cat-api.jpg
draft: false
---

# 正文从这里开始

尧图建站教程系列……
// 解析 Front Matter（用 gray-matter 库）
const matter = require('gray-matter');

const file = matter.read('content/tutorial-032.md');
console.log(file.data);
/* {
  title: 'Markdown 转静态网站实战',
  date: 2026-08-13T00:00:00.000Z,
  author: '尧图建站',
  category: '轻量化站点开发',
  tags: ['Markdown', 'Hexo', '静态网站'],
  cover: 'images/cat-api.jpg',
  draft: false
} */
console.log(file.content);  // 纯正文（不含 Front Matter）

// 整合：解析一篇文章的完整流程
function parsePost(filePath) {
  const { data, content } = matter.read(filePath);
  const html = marked.parse(content);          // 正文转 HTML
  const excerpt = marked.parse(content.split('<!--more-->')[0]); // 摘要
  return {
    ...data,        // 元数据
    html,           // 完整正文 HTML
    excerpt,        // 摘要（列表页用）
    slug: path.basename(filePath, '.md')
  };
}

Front Matter 里有个常用技巧：<!--more--> 分隔符标记"摘要截止点"，分隔符之前的内容作为列表页的摘要展示。这比"截取前 200 字"更精准——作者能控制摘要在哪断句，避免截到一半的尴尬。

三、Hexo 实战：从零搭建一个博客

理解了原理，接下来用最流行的 Hexo 实战搭建。Hexo 用 Node.js 写的，构建速度快、插件生态丰富，是国内技术博客的主流选择。三步就能跑起来：安装、初始化、生成。整个过程不超过 5 分钟。

# 1. 安装 Hexo 命令行工具
npm install -g hexo-cli

# 2. 初始化站点
hexo init yaotu-blog
cd yaotu-blog
npm install

# 3. 新建一篇文章
hexo new "markdown-to-static-site"
# 生成 source/_posts/markdown-to-static-site.md
# 在文件里写 Front Matter 和正文

# 4. 本地预览（带热重载）
hexo server
# 访问 http://localhost:4000

# 5. 生成静态文件
hexo generate   # 或 hexo g
# 输出到 public/ 目录，可直接部署到任意静态服务器
# _config.yml 站点配置（关键部分）
title: 尧图建站博客
subtitle: 一站式建站技术分享
description: 郑州尧图企业管理咨询有限公司旗下建站技术博客
author: 尧图建站
language: zh-CN
timezone: Asia/Shanghai

url: https://ldpk.cn
permalink: :year/:month/:day/:title/   # 文章 URL 规则

theme: landscape    # 主题

# 部署配置（推送到 Git 仓库，配合 GitHub Actions 自动部署）
deploy:
  type: git
  repo: git@github.com:yaotu/ldpk-blog.git
  branch: gh-pages

# 分页
per_page: 10
pagination_dir: page

Hexo 的主题系统让站点外观与内容彻底分离——换主题只改 theme 配置项，文章一个字不用动。尧图给客户做技术博客时，会基于默认主题做深度定制：改国风配色、加侧边栏目录、加阅读进度条、加代码高亮主题。定制主题就是改 themes/主题名/layout/ 下的 EJS 模板和 source/css/ 下的样式，跟普通前端开发没区别。

从 Markdown 写作到静态网站发布，整条链路串起来：Front Matter 存元数据 → marked 解析正文 → 模板套 HTML 骨架 → Hexo 生成静态文件 → 部署到 CDN。这套方案让内容创作者专注于写作，技术细节全由工具接管。尧图用这套方案搭了十几个技术博客和文档站，维护成本几乎为零——写完 Markdown 提交 Git，自动构建部署，全程不用碰服务器。

Markdown Hexo 静态网站
返回教程列表