Skip to content

MkDocs 安装与部署

1、环境配置

#创建环境
micromamba env create -n wiki python=3.12.1  -c conda-forge
#激活环境
micromamba activate wiki
#安装mkdocs和mkdocs-material
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
#创建一个新项目
cd /data/bio_wiki
mkdocs new bio_wiki
cd bio_wiki


#启动服务(主要用于测试)
mkdocs serve -a 0.0.0.0:8000

2、项目配置

#最新配置见mkdocs.yml
site_name: BioBrain # 项目名称
site_url: http://39.100.236.203:8000/
site_author: BioBrain # 作者
site_description: >- # 项目描述
  欢迎来到BioBrain Wiki，这里是探索生命科学、生物信息技术以及人工智能前沿知识的宝库！

# 代码仓库信息
repo_name: yhfu/bio_wiki # 仓库名称
repo_url: http://git.iomics.pro/yhfu/bio_wiki # 仓库地址

# 版权信息
copyright: Copyright © 2024 ~ now |   BioBrain

#配置主题
theme:
  custom_dir: material/overrides # 可以用自定义文件覆盖默认文件
  name: material # material主题
  logo: static/images/logo.png # logo 图片
  language: zh # 默认语言
  features: # 功能
    - content.code.annotate # 代码注释
    - navigation.top # 开启顶部导航栏
    - announce.dismiss # 可以叉掉公告的功能
    - content.action.edit # 编辑按钮，似乎没啥用
    - content.action.view # 查看按钮，似乎没啥用
    - content.code.copy # 复制代码按钮
    # - content.code.select # 选择代码按钮
    # - content.tabs.link # 链接标签
    - content.tooltips # 不太清楚呢这个
    # - header.autohide # 自动隐藏header
    - navigation.expand # 默认展开导航栏
    - navigation.footer # 底部导航栏
    - navigation.indexes # 索引按钮可以直接触发文件，而不是只能点击其下属选项浏览，这个功能可以给对应的section提供很好的预览和导航功能
    # - navigation.instant # 瞬间加载 最好注释掉，多语言切换这个会导致跳回首页
    - navigation.instant.prefetch # 预加载
    - navigation.instant.progress # 进度条
    - navigation.path # 导航路径， 目前好像没啥用
    # - navigation.prune # 只构建可见的页面
    - navigation.sections # 导航栏的section
    - navigation.tabs # 顶级索引被作为tab
    - navigation.tabs.sticky # tab始终可见
    - navigation.tracking # 导航栏跟踪
    - search.highlight # 搜索高亮
    - search.share # 搜索分享
    - search.suggest # 搜索建议
    - toc.follow # 目录跟踪-页面右侧的小目录
    # - toc.integrate # 目录跟踪集成到左侧大目录中
  palette: #主题颜色
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material//weather-sunny
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      primary: teal
      scheme: slate
      toggle:
        icon: material/weather-night
        name: Switch to light mode
  # font: # 字体，大概率不需要换
  #   text: Roboto
  #   code: Roboto Mono
  # favicon: assets/favicon.png # 网站图标 似乎不需要管
  # icon: # 一些用到的icon
  #   logo: logo
  #   previous: fontawesome/solid/angle-left
  #   next: fontawesome/solid/angle-right
  #   tag:
  #     default-tag: fontawesome/solid/tag
  #     hardware-tag: fontawesome/solid/microchip
  #     software-tag: fontawesome/solid/laptop-code

markdown_extensions:
  - pymdownx.snippets: # 往文档中嵌入其它文档的内容
      check_paths: true
      base_path: "./codes/"
  - pymdownx.arithmatex
  - pymdownx.details # 提示块可折叠
  - pymdownx.magiclink
  - pymdownx.tilde # 删除线下标
  - pymdownx.caret # 下划线上标
  - pymdownx.emoji
  - pymdownx.mark # 文本高亮
  - pymdownx.smartsymbols # 符号转换
  - pymdownx.critic # 增加删除修改高亮注释，可修饰行内或段落
  - pymdownx.tabbed: # tab块
      alternate_style: true
  - pymdownx.inlinehilite # 行内代码高亮
  - pymdownx.magiclink # 自动识别超链接
  - pymdownx.superfences # 代码嵌套在列表里
  - pymdownx.highlight: # 代码高亮，显示行号
      linenums: true
      linenums_style: pymdownx-inline
  - pymdownx.emoji: # 表情
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      emoji_index: !!python/name:material.extensions.emoji.twemoji
  - toc: # 锚点
      permalink: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify {
          kwds: { case: lower },
        } # 自定义页面锚点，如 ## Custom Heading {#custom-anchor}
  - admonition # 提示块
  - footnotes # 脚注
  - meta # 定义元数据，通过文章上下文控制，如disqus
  - pymdownx.betterem: # 对加粗和斜体更好的检测
      smart_enable: all
  - pymdownx.tasklist: # 复选框checklist
      custom_checkbox: true
  - attr_list # 增加css-html样式，例如按钮，比如图片定义大小，caption，设置新窗口中打开链接
  - md_in_html
  - pymdownx.arithmatex: # 数学公式
      generic: true
  - abbr
  - admonition
  - def_list
  - footnotes
  - pymdownx.inlinehilite
  - pymdownx.keys

plugins:
  - glightbox: # 图片点击放大 https://github.com/blueswen/mkdocs-glightbox
  - search: # 搜索插件
      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])' # 分隔符
  - tags:
      tags_file: tags.md
  - exclude: # 编译静态页面时排除的文件和目录
      glob:
        - "tmp/*"
        - "*.tmp"
        - "*.pdf"
        - "*.gz"
      regex:
        - '.*\.(tmp|bin|tar)$'
  - print-site: # 将所有页面都在一个页面内生成
      # 防止生产静态页面时报错，需添加以下两个选项
      enumerate_headings: false
      add_table_of_contents: false

  - blog # 博客功能插件
  # - rss: # rss订阅插件 - 不太懂是干嘛的目前
  #     match_path: blog/posts/.*
  #     date_from_meta:
  #       as_creation: date
  #     categories:
  #       - categories
  #       - tags
  # - social # 目前我开启会报错，还没研究透

  - minify: # 压缩插件
      minify_html: true
  # - privacy # 隐私插件
  - i18n: # 多语言插件
      docs_structure: suffix # 抄来的，不太懂
      fallback_to_default: true # 抄来的，不太懂
      reconfigure_material: true # 抄来的，不太懂
      reconfigure_search: true # 抄来的，不太懂
      languages: # 多语言配置 - 需要小心一点
        - locale: zh
          default: true # 默认语言
          name: 简体中文
          build: true # 是否构建
          # site_name: Infinity
        - locale: en
          name: English
          build: true
          nav_translations: # 导航栏翻译，不可以有缩进
            首页: HOME
            人工智能: AI
            常用工具: TOOLS
            关于: ABOUT
  - git-revision-date-localized: # 配合git，以显示每个页面的创建和修改时间
      type: date
      enable_creation_date: true
      fallback_to_build_date: true

extra_javascript:
  - http://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js # 访问统计
  # - 'js/baidu-tongji.js' # 百度统计
  # - 'js/tablesort.js' # 表格排序

nav:
  - 首页: index.md
  - 人工智能: "./AI/index.md"
  - 常用工具:
      - Slurm: "TOOLS/Slurm/slurm.md"
      - MkDocs:
          - 安装与部署: "TOOLS/MkDocs/install.md"
          - 使用技巧: "TOOLS/MkDocs/tips.md"

3、编译与部署

#拉取最新代码
cd /data/bio_wiki
git clone http://git.iomics.pro/yhfu/bio_wiki.git

#编译(可以参考deploy.example实现快速更新与部署)
mkdocs build

#配置web服务(这里使用nginx)
#因为线上节点的nginx配置在docker，所以需要进入docker进行配置
docker exec -it pig_nginx_new_240310 /bin/bash

#使用iswine的nginx(/data/pignew_240310/conf/nginx_flask.conf)
# wiki.iomics.pro (2024.08.30 add by Yuhua Fu)

server {
    listen 90;
    server_name wiki.iomics.pro; # 随便
    root /wiki/bio_wiki/site; # 找到site文件夹,改路径在docker内，提前做映射
    index index.html index.htm;
    location / {
        try_files $uri $uri/ =404;
    }
}



/usr/sbin/nginx -s reload
本文阅读量  次
本站总访问量  次
Authors: Wind (97.18%), wangshangjian (2.42%), Your Name (0.4%)