快速使用 MkDocs搭建个人博客

使用 MkDocs 创建静态页面

MkDocs 是一个静态网站生成器，它使用 Markdown 编写内容并生成漂亮的文档。本文将介绍如何使用 MkDocs 创建一个静态页面。

---

准备工作

首先，我们需要准备一个 Python 虚拟环境，并安装 MkDocs。以下是一个简单的脚本 install.sh，用于创建和配置虚拟环境：

#!/bin/bash

# 获取脚本所在目录
SCRIPT_DIR=$(cd "$(dirname "$0")"; pwd)
VENV_DIR="$SCRIPT_DIR/mkdocs_env"

# 创建虚拟环境
if [ ! -d "$VENV_DIR" ]; then
  echo "创建虚拟环境..."
  python3 -m venv "$VENV_DIR"
fi

# 激活虚拟环境
echo "激活虚拟环境..."
source "$VENV_DIR/bin/activate"

# 安装 MkDocs
pip install mkdocs

# 安装 MkDocs（如果尚未安装）
if ! command -v mkdocs &> /dev/null; then
    echo "安装 MkDocs..."
    pip install mkdocs
else
    echo "MkDocs 已安装。"
fi

# 关闭虚拟环境
deactivate

保存以上脚本为 install.sh，并运行它：

source install.sh

该脚本将创建一个名为 mkdocs_env 的虚拟环境并安装 MkDocs。

创建 MkDocs 项目

现在，我们可以使用 MkDocs 创建一个新项目。下面的 start.sh 脚本将帮助我们创建和启动 MkDocs 项目：

#!/bin/bash

# 获取脚本所在目录的绝对路径
SCRIPT_DIR=$(cd "$(dirname "$0")"; pwd)

# 定义虚拟环境的激活脚本路径
ACTIVATE_SCRIPT="$SCRIPT_DIR/mkdocs_env/bin/activate"

# 打印激活脚本路径
echo "路径：$ACTIVATE_SCRIPT"

# 检查激活脚本是否存在
if [ ! -f "$ACTIVATE_SCRIPT" ]; then
    echo "错误：激活脚本不存在：$ACTIVATE_SCRIPT"
    exit 1
fi

# 激活虚拟环境
source "$ACTIVATE_SCRIPT"

# 成功激活提示
echo "虚拟环境已成功激活"

# 项目目录
if [ -z "$1" ]; then
    echo "错误：未传递第二个参数。请提供一个有效的路径。"
    
else

	# 获取项目目录
	PROJECT_DIR="$SCRIPT_DIR/$1"

	# 创建新的 MkDocs 项目（如果不存在）
	if [ ! -d "$PROJECT_DIR" ]; then
		echo "创建 MkDocs 项目在：$PROJECT_DIR"
		mkdocs new "$PROJECT_DIR"
		
		# 创建激活虚拟环境的脚本
		ACTIVATE_VENV_SCRIPT="$PROJECT_DIR/activate_venv.sh"
		echo "创建激活虚拟环境的脚本：$ACTIVATE_VENV_SCRIPT"
		cat <<EOL > "$ACTIVATE_VENV_SCRIPT"
#!/bin/bash
source "$ACTIVATE_SCRIPT"
echo "虚拟环境已成功激活"
echo "使用 'mkdocs serve' 启动开发服务器"
echo "使用 'deactivate' 关闭虚拟环境"
EOL
		# 赋予执行权限
		chmod +x "$ACTIVATE_VENV_SCRIPT"
	else
		echo "项目目录已存在：$PROJECT_DIR"
	fi
fi

echo "关闭虚拟环境..."
deactivate

保存该脚本为 start.sh，并运行它：

source start.sh <your_project_name>

替换 <your_project_name> 为你想要的项目目录名。该脚本将激活虚拟环境并在指定目录创建一个新的 MkDocs 项目。

启动 MkDocs 开发服务器

进入你的项目目录并激活虚拟环境

cd <your_project_name>
source activate_venv.sh

再运行以下命令启动 MkDocs 开发服务器：

mkdocs serve

你可以在浏览器中打开 http://127.0.0.1:8000 查看生成的静态页面。或Ctrl + 左键点击链接打开.

$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.04 seconds
INFO    -  [15:56:02] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [15:56:02] Serving on http://127.0.0.1:8000/

现象

总结

通过上述步骤，我们已经成功创建了一个 MkDocs 静态页面项目，并在本地启动了开发服务器。现在，你可以编辑 docs 目录中的 Markdown 文件来更新你的静态页面内容。MkDocs 将自动重新加载并展示最新的文档内容。

希望这篇文章对你有所帮助。如果你有任何问题或建议，欢迎在评论区留言。