【详细】使用MkDocs搭建个人博客网站

谁践踏了优雅 2023-10-05 23:42 18阅读 0赞

## 使用MkDocs搭建个人博客网站 ##

#### 0. 安装python3.7 ####

**注意：可以在个人用户下安装，不要覆盖系统原有python**

#下载Python依赖环境
    yum install gcc patch libffi-devel python-devel zlib-devel bzip2-devel openssl-devel ncurses-devel sqlite-devel readline-devel tk-devel gdbm-devel db4-devel libpcap-devel xz-devel -y
    
    #没有wget需要安装
    yum install wget -y   
    
    #下载安装包
    wget https://www.python.org/ftp/python/3.7.13/Python-3.7.13.tgz
    
    #解压
    tar -zxvf Python-3.7.13.tgz
    
    #编译安装
    cd Python-3.7.13
    ./configure --prefix=/home/mkdocs/python3
    make && make install
    
    #配置环境变量
    vi ~/.bash_profile 
    #添加此配置
    PATH=$PATH:/home/mkdocs/python3/bin
    
    source ~/.bash_profile
    
    #软连接
    sudo ln -sf /home/mkdocs/python3/bin/python3.7 /usr/bin/python3
    sudo ln -sf  /home/mkdocs/python3/bin/pip3.7 /usr/bin/pip3
    
    #验证
    python3 --version
    pip3 --version

#### 1. 安装mkdocs ####

###### 1、确保已经安装python3环境，以及Python包管理器pip ######

###### 2、 安装 MkDocs ######

pip3 install mkdocs

###### 3、创建文档项目，docs 是自定义文件目录 ######

mkdocs new docs

###### 4、切换到 mysite 目录下，并运行 ######

mkdocs serve -a ip:port

浏览器输入 ip:port就预览到我们建设的文档站点了

#### 2. 安装插件 ####

###### 安装主题插件： ######

pip3 install mkdocs-material -i https://pypi.tuna.tsinghua.edu.cn/simple

###### 安装版本管理插件： ######

pip3 install mike

###### 安装生成pdf插件： ######

pip3 install mkdocs-with-pdf

###### 安装qrcode： ######

pip3 install qrcode

###### 安装weasyprint，版本需要指定52.5： ######

pip3 install weasyprint==52.5

#### 3. 配置 ####

###### 配置mkdocs.yml ######

#站点配置说明
    site_name: Docs #站点名称
    docs_dir: docs #文档地址
    #主题配置
    theme:
      name: material #指定主题
      custom_dir: overrides #定制目录，同名覆盖
      palette: #颜色配置
        primary: indigo #主题颜色
        accent: deep orange #强调文字颜色
      language: zh #语言
      features:
        - navigation.top #tab页展示方式 顶部 
        - header.autohide #表头自动隐藏
    
    #版本控制
    extra: 
      version:            
        provider: mike
    
    #with-pdf配置说明：
    plugins:
      - search #添加搜索框
      - with-pdf: #生成pdf配置
          copyright: copyright @ 2022#设置作者文本
          cover_subtitle: v1.1.0 #子标题
          author: author #作者
          cover: true #封面
          back_cover: true #底面
          output_path: pdf/文件名称.pdf #输出路径

#### 4. 开发 ####

###### 1、把创建好的文档项目，提交到git远程仓库 ######

###### 2、在windows端，拉取git文档项目到本地，通过idea打开，选定一个分支，在docs目录下，添加md文档，进行编写文档即可 ######

###### 4、编写完成，提交到git远程，linux端拉取文档 ######

###### 5、linux端拉取到最新文档， 执行命令 ######

mkdocs build
    mike deploy [version]
    mkdocs serve -a ip:port

###### 6、浏览器访问ip:port，即可看到最新页面 ######

#### 5.项目放到Nginx中 ####

###### 1、复制site文件夹到Nginx ######

###### 2、进行Nginx相关配置 ######

###### 3、访问网站 ######

#### 附录： ####

mkdocs中文文档：

[https://mkdocs.zimoapps.com/\#\_14][https_mkdocs.zimoapps.com_14]

插件商店可参考：

[https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins\#pdf–site-conversion][https_github.com_mkdocs_mkdocs_wiki_MkDocs-Plugins_pdf_site-conversion]

mike配置可参考：

[https://github.com/jimporter/mike/tree/v1.1.2][https_github.com_jimporter_mike_tree_v1.1.2]

theme配置可参考：

[https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/][https_squidfunk.github.io_mkdocs-material_setup_changing-the-colors]

with-pdf配置：

[https://github.com/orzih/mkdocs-with-pdf][https_github.com_orzih_mkdocs-with-pdf]

[https_mkdocs.zimoapps.com_14]: https://mkdocs.zimoapps.com/#_14
[https_github.com_mkdocs_mkdocs_wiki_MkDocs-Plugins_pdf_site-conversion]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#pdf--site-conversion
[https_github.com_jimporter_mike_tree_v1.1.2]: https://github.com/jimporter/mike/tree/v1.1.2
[https_squidfunk.github.io_mkdocs-material_setup_changing-the-colors]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/
[https_github.com_orzih_mkdocs-with-pdf]: https://github.com/orzih/mkdocs-with-pdf