Markdown 与网页开发

Markdown 不仅是一种文档格式，也是网页开发中的重要工具。通过各种静态网站生成器和框架，你可以将 Markdown 文件转换为美观的网页。在本章中，我们将介绍 Markdown 与网页开发的集成。

Jekyll 与 GitHub Pages

Jekyll 简介

Jekyll 是一个静态网站生成器，它可以将 Markdown 文件转换为静态 HTML 网站。Jekyll 是 GitHub Pages 的默认引擎，非常适合创建个人博客、项目文档等。

基本使用

1. 安装 Jekyll

gem install jekyll bundler

2. 创建 Jekyll 项目

jekyll new my-blog
cd my-blog

3. 添加 Markdown 文章

在 _posts 目录中创建 Markdown 文件，文件名格式为 YYYY-MM-DD-title.md：

---
title: "Hello, Jekyll!"
date: 2023-01-01 12:00:00
categories: blog
---

# 欢迎使用 Jekyll

这是我的第一篇 Jekyll 博客文章。

4. 本地预览

bundle exec jekyll serve

5. 部署到 GitHub Pages

将项目推送到 GitHub 仓库，然后在仓库设置中启用 GitHub Pages。

Hugo 静态网站生成

Hugo 简介

Hugo 是一个用 Go 语言编写的静态网站生成器，以速度快著称。它支持 Markdown 格式，可以生成高质量的静态网站。

基本使用

1. 安装 Hugo

根据你的操作系统下载并安装 Hugo。

2. 创建 Hugo 项目

hugo new site my-site
cd my-site

3. 添加主题

git clone https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo 'theme = "ananke"' >> config.toml

4. 添加 Markdown 内容

hugo new posts/my-first-post.md

编辑生成的 Markdown 文件：

---
title: "My First Post"
date: 2023-01-01T12:00:00Z
draft: false
---

# 欢迎使用 Hugo

这是我的第一篇 Hugo 博客文章。

5. 本地预览

hugo server -D

6. 构建网站

hugo

VuePress/Docusaurus

VuePress 简介

VuePress 是一个基于 Vue.js 的静态网站生成器，专为技术文档而设计。它支持 Markdown 格式，并提供了丰富的主题和插件系统。

基本使用

1. 创建 VuePress 项目

mkdir my-docs
cd my-docs
npm init -y
npm install -D vuepress

2. 创建目录结构

my-docs/
├── docs/
│   ├── .vuepress/
│   │   └── config.js
│   ├── README.md
│   └── guide/
│       └── README.md
└── package.json

3. 配置 VuePress

编辑 docs/.vuepress/config.js：

module.exports = {
  title: '我的文档',
  description: '这是我的技术文档',
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' }
    ],
    sidebar: {
      '/guide/': [
        { text: '介绍', link: '/guide/' },
        { text: '安装', link: '/guide/installation/' }
      ]
    }
  }
}

4. 添加 Markdown 内容

编辑 docs/README.md 和 docs/guide/README.md。

5. 本地预览

npm run docs:dev

6. 构建网站

npm run docs:build

Docusaurus 简介

Docusaurus 是 Facebook 开发的静态网站生成器，专为开源项目文档而设计。它支持 Markdown 格式，并提供了博客、版本控制等功能。

基本使用

1. 创建 Docusaurus 项目

npx create-docusaurus@latest my-docs classic
cd my-docs

2. 添加 Markdown 内容

在 docs 目录中创建 Markdown 文件。

3. 本地预览

npm run start

4. 构建网站

npm run build

自定义 CSS 样式

内联样式

在 Markdown 文件中使用 HTML 标签和内联样式：

<p style="color: red; font-size: 18px;">这是红色的文本</p>

外部样式表

在静态网站生成器中，可以创建自定义 CSS 文件：

1. 创建 CSS 文件

/* custom.css */
.markdown-section h1 {
  color: #333;
  font-size: 2.5rem;
  margin-bottom: 1rem;
}

.markdown-section p {
  line-height: 1.6;
  margin-bottom: 1rem;
}

2. 引用 CSS 文件

在 VuePress 中，编辑 docs/.vuepress/config.js：

module.exports = {
  // ...
  head: [
    ['link', { rel: 'stylesheet', href: '/css/custom.css' }]
  ]
}

主题定制

大多数静态网站生成器都支持主题定制：

• VuePress：可以创建自定义主题或修改现有主题
• Docusaurus：支持主题配置和组件覆盖
• Jekyll：可以创建自定义布局和样式
• Hugo：支持主题配置和部分覆盖

小结

Markdown 与网页开发的集成使得创建美观、专业的网站变得更加容易。通过使用静态网站生成器如 Jekyll、Hugo、VuePress 或 Docusaurus，你可以将 Markdown 文件转换为高质量的静态网站，而不需要编写复杂的 HTML 和 CSS 代码。

在接下来的章节中，我们将介绍 Markdown 与专业领域、Markdown 工具链等高级应用。