基于mkdocs-material搭建个人静态博客

基于mkdocs-material搭建个人静态博客

基于mkdocs-material搭建个人纯静态博客,没有php,没有mysql 如果你只是想安安静静的放一些技术文章,发布到个人站点或github-pages,mkdocs-material很适合你

小慢哥的原创文章,欢迎转载

  • 本文仅是缩略,笔者已将详细内容发布到github上

  • 可点击本文最后的”阅读更多”进行访问,或者在github上搜”cyent markdown”也可以看到

目录

  • 本文概述

  • mkdocs-material介绍

  • 安装

  • 初始化项目

  • 修改主题

  • 运行

  • 发布到GitHub pages

  • 发布到个人HTTP Server

  • mkdocs.yml注意事项

  • 添加页面

  • 添加扩展

  • markdown语法

  • 其他功能

  • 最佳实践


本文概述

mkdocs-material入门,包括安装、运行、发布至github-pages及个人站点

mkdocs-material介绍

符合google material ui规范的静态文档网站生成器,使用markdown进行文档书写

mkdocs

  • python编写的markdown解释器、编译器,带有本地cli工具

  • 自带基于Tornado的小型http服务,用于本地调试

  • 内置一键式发布至GitHub Pages

  • 内置mkdocs风格、readthedocs风格的主题,并支持自定义主题

  • 支持调用python模块实现语法及渲染的扩展

mkdocs-material

  • python模块,符合google material ui规范的mkdocs自定义主题

  • 针对特定语法、功能做了渲染优化

  • 根据客户端浏览器页面尺寸自动缩放,对PC、移动设备都友好

  • 丰富的页面配色,多达19种主体配色和16种悬停链接文字配色

  • 支持中文搜索

  • 支持统计功能,如百度统计,谷歌统计

安装

  1.  pip install mkdocs mkdocs-material

若下载慢,可更换安装源为豆瓣

  1.  pip install --trusted-host pypi.douban.com -i

  2.  http://pypi.douban.com/simple/ mkdocs mkdocs-material

初始化项目

  1.  mkdocs new my-project

会生成my-project目录,进入该目录里,可以看到默认放置了一些文件,包括mkdocs.yml,这是主配置文件

修改主题

mkdocs.yml里添加:

  1.  theme:

  2.    name: material

运行

  1.  # 在my-project目录里执行

  2.  mkdocs serve

通过浏览器访问本地ip的8000端口(比如http://127.0.0.1:8000/) 查看效果,如图所示

基于mkdocs-material搭建个人静态博客

发布到GitHub pages

通过 mkdocs gh-deploy自动编译出html并发布至GitHub pages,步骤如下

初始化repo

1.在github上创建一个repo,名字叫my-project(可以是其他名,这里先假设叫my-project),创建repo时候选择初始化带有README.md 2.使用git clone将repo同步到本地

导入项目

1.将mkdocs根目录(即my-project目录)下的所有东西移到刚刚git clone下来的git目录下 2.然后可以将最早创建的mkdocs根目录(即my-project目录)删除了

发布

在本地git目录下执行

  1.  mkdocs gh-deploy

发布到个人HTTP Server

通过 mkdocs build编译出html并手动同步至http server的根目录

生成站点文件

在git目录下执行命令

  1.  mkdocs build

命令执行完毕后可以看到site目录

发布至http server

将site目录里的所有东西拷贝到http server的根目录下

mkdocs.yml注意事项

由于是yaml格式,因此首先要符合yaml的语法要求

docs下需要一个index.md,作为站点首页

文档层次结构虽然可以很多层,但最佳实践是控制在2层内,最多不要超过3层,否则展示会不够友好

添加页面

在my-project/docs/里放置.md文件,可以自行组织目录结构

然后在mkdocs.yml里添加,比如这样:

  1.  nav:

  2.    - 介绍: index.md

  3.    - 安装:

  4.        - 本地环境搭建: install/local.md

  5.        - 发布至GitHub Pages: install/github-pages.md

  6.        - 发布至自己的HTTP Server: install/http-server.md

  7.    - 语法:

  8.        - 语法总览: syntax/main.md

  9.        - 标题: syntax/headline.md

  10.        - 段落: syntax/paragraph.md

  • 上面的index.md就是放置在my-project/docs/index.md

  • 上面的local.md就是放置在my-project/docs/install/local.md

添加扩展

只有添加了扩展,才能完美使用mkdocs-material官方支持的所有markdown语法

mkdocs.yml里添加:

  1.  markdown_extensions:

  2.    - admonition

  3.    - codehilite:

  4.        guess_lang: false

  5.        linenums: false

  6.    - toc:

  7.        permalink: true

  8.    - footnotes

  9.    - meta

  10.    - def_list

  11.    - pymdownx.arithmatex

  12.    - pymdownx.betterem:

  13.        smart_enable: all

  14.    - pymdownx.caret

  15.    - pymdownx.critic

  16.    - pymdownx.details

  17.    - pymdownx.emoji:

  18.        emoji_generator: !!python/name:pymdownx.emoji.to_png

  19.    - pymdownx.inlinehilite

  20.    - pymdownx.magiclink

  21.    - pymdownx.mark

  22.    - pymdownx.smartsymbols

  23.    - pymdownx.superfences

  24.    - pymdownx.tasklist

  25.    - pymdownx.tilde

markdown语法

mkdocs-material支持几十种markdown语法,有许多很酷炫的功能与效果,由于篇幅有限,无法在这一一展示,因此这里仅列举下所支持的主要语法

1.标题 2.段落 3.引用 4.表格 5.代码

  • 行内

  • 区块

  • 高亮

6.字体样式

  • 斜体,粗体,粗斜体

  • 上标,下标

  • 下划线

  • 横线

  • 下划线+横线

7.列表

  • 无序列表

  • 有序列表

  • 任务列表

8.分割线 9.链接

  • 普通链接

  • 自动链接

  • 锚点提示

10.图片

  • 行内式

  • 参考式

11.转义 12.高亮

  • 代码高亮

  • 背景高亮

13.注解

  • 介绍

  • 完整格式

  • 空标题

  • 无标题

  • 无类型

  • 折叠

  • 11种颜色样式

  • 嵌套

14.脚注 15.元信息 16.数学公式

  • 介绍

  • 导入js

  • 用法

17.emoji

  • 介绍

  • 工作原理

  • 最佳实践

18.特殊符号 19.嵌套

  • 介绍

  • 注解-注解

  • 列表-列表

  • 引用-引用

  • 注解-代码块

  • 列表-代码块

  • 引用-代码块

  • 黄色区块-代码

  • 绿色区块-代码

  • 红色区块-代码

  • 绿接红区块-代码

  • 注解-列表-引用

  • 列表-列表-引用

  • 引用-引用-代码

其他功能

mkdocs-material本身还支持如下功能:

  • 添加js,可用于站点统计(如百度统计,谷歌统计)

  • 页面以及跳转文字的配色

  • 中文搜索

最佳实践

如果希望自己所写的markdown可以兼容各个markdown编辑器,那么只需了解markdown的传统语法即可

如果想让自己所写的markdown发布到web服务器,例如GitHub Pages、自己搭建的HTTP Server,那么可以考虑使用本文所介绍的语法,以实现丰富多样的渲染效果。

笔者建议:尽量使用传统语法,只在必要时候才使用本文介绍的语法。因为排版简洁、条理清晰才能带来最舒服的阅读感受。


原文始发于微信公众号( 小慢哥Linux运维 ):基于mkdocs-material搭建个人静态博客

基于mkdocs-material搭建个人静态博客》有2个想法

发表评论