跳转至

使用uv管理wiki_blog

环境配置

使用uv 进行项目环境的部署和管理

Visual Studio Code 编写并实时预览 Markdown_vscode 中 md 文件编辑的同时实时预览-CSDN 博客

1.初始化项目环境

cd D:/Projects/work

# 克隆项目
git clone http://git.iomics.pro/yhfu/bio_wiki.git
# 注意：首次clone时，需要配置一下git信息
git config  user.name "wangshangjian"
git config  user.email "wangshangjian@webmail.hzau.edu.cn"

# 进入项目
cd bio_wiki

# 创建虚拟环境
uv venv
# 进入虚拟环境
.\.venv\Scripts\activate # win

# 安装第三方包(是安装在虚拟环境中的，放心使用)
uv pip install mkdocs-material mkdocs-glightbox mkdocs-git-revision-date-localized-plugin mkdocs-exclude mkdocs-print-site-plugin mkdocs-minify-plugin mkdocs-static-i18n mkdocs-git-authors-plugin

# 测试看效果
mkdocs serve -a 127.0.0.1:8000

2.之后的部署测试

  • 以后再测试部署时，直接进入bio_wiki
cd D:/Projects/blog/bio_wiki

# 启动虚拟环境
.venv\Scripts\activate

# 然后部署看效果
mkdocs serve -a 127.0.0.1:8000

文件放置

1.md 文件

  • md 文件，放到 doc 目录下、对应的文件夹中就行

2.静态文件

静态文件就是图片之类的文件

（1）静态文件放到docs/static中去

  • 最好一个 md，对应一个存放静态文件的文件夹，方便管理
  • 静态文件目录的结构，和 doc 中 md 文件的结构保持一致就更好

（2）要配置好静态文件的查找路径

  • 比如，我的 md 文件是：docs/CS/Git/在VScode中使用Git.md
  • 而我的图片文件在：docs/static/images/CS/git文件夹下
  • 所以，在 md 文件中使用该图片时，可以如下配置：
![image-20241014192050852](../../static/images/CS/git/image-20241014192050852.png)

3.配置 yml 文件

（1）在把 md 文件放到对应位置以后，一个重要的工作，就是要配置mkdocs.yml文件

  • 否则 md 文件就无法加载到 wiki 里去

（2）主要配置yml文件的nav块：

nav:
  ...
  - 计算机科学:
      - Git:
          - 修改: "CS/Git/修改.md"
  • 这样，就可以在点击对应的导航后，看到相应的 md 文件啦：

image-20241023194800835

补充： 如果你的 md 文件很大，建议拆为多个，这样前端用户查看时更友好

1）如果我们不拆为多个会怎样？

  • 假设我们如下配置 yml：
nav:
  ...
  - 计算机科学:
      - Git: "CS/Git/修改.md"

效果如下：

  • 可以看到，只有一个层级时，Git处只会显示一个 md 文件

image-20241023194849085

2）而如果我们配置Git为多个层级后

  • 即Git为父级，它下面还有其他子级 md 文件
nav:
  ...
  - 计算机科学:
      - Git:
          - 基本概念: "CS/Git/基本概念.md"
          - 安装Git: "CS/Git/安装Git.md"
          ...
          - 在VScode中使用Git: "CS/Git/在VScode中使用Git.md"

效果如下：

  • 可以看到，配置为多个层级时，出现了可以折叠Git的按钮1
  • 同时需要说明的是：如果文件的内容很多，2处的目录是不会出现的
  • 这样就很不方便进行内容的目录检索和快速跳转了

image-20241023194452505

  • 综上，建议 md 文件很大、内容很多时，拆为多块
  • 这样 ，不仅左侧有详细的目录导航
  • 右侧目录处还可以进行内容的快速跳转
  • 非常方面用户的查看

其他小细节

md 的强调语法的使用细节

  • md 的强调语法****后面，最好空一格，否则 MkDocs 就无法正常渲染

空格前

image-20241023201055934

image-20241023201105992

空格后

image-20241023201247786

image-20241023201257169

侧边栏目录导航显示不全

  • 有时候，md 文件内容很多，但是侧边栏的目录导航只显示了很少的几块
  • 此时有两个解决方案：
  • 1.把大的 md 文件拆分为多个
  • 2.尽量使用 H2 和 H3 级别的标题。我发现只要有 H1 级别的标题，目录导航就不正常

项目推送

1.首先，终端配置用户名和邮箱

git config user.name "wangshangjian"
git config user.email "wangshangjian@webmail.hzau.edu.cn"

2.然后，直接使用 vscode 的 git 插件进行管理就行

image-20241023195511218

本文阅读量  次
本站总访问量  次
Authors: wangshangjian