Wcowin for MkDocs主题

• 基于Material for MkDocs美化
• 简洁美观，功能多元化
• 可自定义样式，中文教程详细
• 简单易上手，小白配置
• 𝕙𝕒𝕧𝕖 𝕒 𝕘𝕠𝕠𝕕 𝕥𝕚𝕞𝕖 !

目录

• Wcowin for MkDocs主题
  • 目录
  • 展示
  • 来自Claude-4-Sonnet的肯定
  • 快速开始
    • 环境要求
    • 方法一：直接下载使用（推荐新手）
    • 方法二：Git克隆使用
    • 方法三：GitHub模板创建
    • 常见问题解决
      • 🔧 依赖安装问题
      • 🔧 Python版本问题
      • 🔧 端口占用问题
      • 🔧 权限问题
    • 📝 自定义配置
    • 🚀 部署到线上
  • 视频教程
• Connect with me
  • 案例成果
  • Star History
  • 贡献者
  • 请作者喝杯咖啡
  • License

展示

主页

文章页

博客页

关于

标签页

简洁的友链页面

页面底部

Lighthouse测试结果

来自Claude-4-Sonnet的肯定

快速开始

环境要求

在开始之前，请确保你的系统已安装：

• Python 3.8+ （推荐3.9或更高版本）
• pip （Python包管理器）
• Git （用于版本控制）

方法一：直接下载使用（推荐新手）

这是最简单的方式，适合初学者快速体验：

1. 下载模板

   • 访问 Releases页面
   • 下载最新版本的 Wcowin-for-MkDocs.zip
   • 解压到你想要的目录（注意把Wcowin-for-MkDocs文件夹里的所有文件单独移动到你的项目目录下）
   • 比如你在本地新建了一个myblog文件夹，那么就把Wcowin-for-MkDocs文件夹里的所有文件单独移动到myblog文件夹下

2. 安装依赖

   # 建议在虚拟环境中安装
   pip install -r requirements.txt

3. 启动预览

   # 进入解压后的目录
   cd myblog
   
   # 启动本地服务器
   mkdocs serve

4. 查看效果

   • 打开浏览器访问 http://127.0.0.1:8000
   • 实时预览你的网站

出现报错自行谷歌即可，也可以给我发邮件，我会及时回复。

方法二：Git克隆使用

适合有Git基础的用户：

1. 克隆仓库

   # 克隆到本地
   git clone https://github.com/Wcowin/Mkdocs-Wcowin.git
   
   # 进入项目目录
   cd Mkdocs-Wcowin

2. 安装依赖

   # 安装所有必需的包
   pip install -r requirements.txt

3. 启动服务

   # 启动开发服务器
   mkdocs serve
   

方法三：GitHub模板创建

最适合想要部署到GitHub Pages的用户：

1. 使用模板创建仓库

   • 点击 使用此模板
   • 创建你自己的仓库（建议命名为 你的用户名.github.io）

2. 克隆到本地

   git clone https://github.com/你的用户名/你的仓库名.git
   cd 你的仓库名

3. 配置和部署

   # 安装依赖
   pip install -r requirements.txt
   
   # 本地预览
   mkdocs serve
   
   # 部署到GitHub Pages
   mkdocs gh-deploy

常见问题解决

🔧 依赖安装问题

如果遇到插件缺失错误：

# 单独安装缺失的插件
pip install mkdocs-git-committers-plugin-2
pip install mkdocs-glightbox
pip install mkdocs-git-revision-date-localized-plugin

# 或者一次性安装所有依赖
pip install -r requirements.txt

🔧 Python版本问题

如果提示Python版本过低：

# 检查Python版本
python --version

# 如果版本低于3.8，请升级Python
# 或使用虚拟环境
python -m venv mkdocs-env
source mkdocs-env/bin/activate  # Linux/Mac
# 或
mkdocs-env\Scripts\activate     # Windows

🔧 端口占用问题

如果8000端口被占用：

# 使用其他端口
mkdocs serve -a 127.0.0.1:8080

🔧 权限问题

如果遇到权限错误：

# 使用用户级安装
pip install --user -r requirements.txt

📝 自定义配置

1. 修改网站信息

   • 编辑 mkdocs.yml 文件
   • 修改 site_name、site_author 等基本信息

2. 添加内容

   • 在 docs/ 目录下添加你的Markdown文件
   • 更新 mkdocs.yml 中的导航配置

3. 个性化样式

   • 修改 docs/stylesheets/extra.css
   • 自定义颜色、字体等样式

🚀 部署到线上

GitHub Pages部署：

mkdocs gh-deploy

其他平台部署：

# 构建静态文件
mkdocs build

# 将site/目录上传到你的服务器

---

💡 提示： 如果你是第一次使用MkDocs，强烈建议观看我们的视频教程，手把手教你从零开始搭建。

视频教程

Mkdocs中文教程视频（手把手教学，首次使用MKdocs建议观看）

Connect with me

Wechat

Telegram

案例成果

Lenny's Web
苍镜月's docs
世界天光的笔记本
Wen-Chieh Lee的生活 BruceJin's Notebook
0X10CC的代码空间
GENG Wei's Homepage

谢谢你们~

Star History

贡献者

请作者喝杯咖啡

https://www.gitfish.dev/repo/Wcowin/Mkdocs-Wcowin

License

MIT License

Copyright (c) 2022-2025 Wang Kewen

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.