photoprism/mkdocs-material

Material for MkDocs Docker镜像

镜像概述

Material for MkDocs是一个基于Material Design设计的MkDocs主题镜像，用于将Markdown文件转换为品牌化的静态文档网站。该镜像特别适合托管开源项目或商业项目的文档，具有高度可定制性、内置搜索功能、移动友好设计以及40多种语言支持，可在5分钟内完成搭建。

核心功能与特性

简洁的Markdown编写

• 只需使用Markdown编写技术文档，无需掌握HTML、JavaScript或CSS
• Material for MkDocs会自动处理格式转换，生成美观且功能完善的网站

丰富的扩展功能

• 原生集成Python Markdown扩展，支持：
  • 标注框(callouts)
  • 选项卡式内容容器
  • 数学公式
  • 批注标记(critic markup)
  • 任务列表
  • 10,000+图标和表情符号

全设备响应式设计

• 从移动设备到宽屏显示器，完全适配各种屏幕尺寸
• 流体布局自动适应可用屏幕空间

内置搜索功能

• 无需服务器支持，静态网站即可实现全文搜索
• 快速索引和检索文档内容

多样化配置选项

• 自定义颜色方案、字体家族、语言、图标、网站图标和Logo
• 轻松添加源代码仓库链接、社交媒体资料、Google Analytics和Disqus评论系统

国际化支持

• 包含40多种语言的翻译
• 完整支持RTL(从右到左)布局

无障碍访问

• 可扩展的键盘导航
• 语义化标记，包括角色属性和地标
• 尊重用户默认字体大小设置

现代技术架构

• 基于TypeScript、RxJS和SCSS构建
• 提供出色的主题扩展和自定义可能性

使用场景与适用范围

适用场景

• 开源项目技术文档
• 商业产品用户手册
• 内部知识库
• API文档
• 技术博客
• 培训材料

被信任的组织与项目

领先组织：Atlassian、AWS、Binance、Bloomberg、CERN、Datadog、Google、ING、Intel、LinkedIn、Microsoft、Mozilla、Netflix、Salesforce、SoundCloud、Square、Zalando等。

开源项目：Arduino、AutoKeras、BFE、Crystal、Electron、FastAPI、Knative、Kubernetes、kSQL、Nokogiri、OpenFaaS、Pi-Hole、Pydantic、Renovate、Traefik、Vapor、ZeroNet、WTF等。

使用方法与配置说明

基本使用流程

1. 准备文档结构：创建包含Markdown文件的文档目录，典型结构如下：

   docs/
   ├── index.md
   ├── getting-started.md
   └── ...
   mkdocs.yml
   

2. 配置mkdocs.yml：在配置文件中指定Material主题

   yaml
   theme:
     name: material
   

3. 通过Docker运行：使用Docker镜像启动服务

Docker部署示例

基本运行命令

bash
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs docker.xuanyuan.run/squidfunk/mkdocs-material

构建静态网站

bash
docker run --rm -v ${PWD}:/docs docker.xuanyuan.run/squidfunk/mkdocs-material build

Docker Compose配置

yaml
version: '3'
services:
  mkdocs:
    image: docker.xuanyuan.run/squidfunk/mkdocs-material
    ports:
      - "8000:8000"
    volumes:
      - ./:/docs
    command: serve --dev-addr 0.0.0.0:8000

高级配置选项

在mkdocs.yml中可以添加更多配置来自定义网站：

yaml
theme:
  name: material
  palette:
    primary: "indigo"
    accent: "teal"
  font:
    text: "Roboto"
    code: "Roboto Mono"
  icon:
    logo: "material/library"
  features:
    - navigation.tabs
    - search.suggest
    - search.highlight

site_name: 我的项目文档
site_url: https://example.com/docs
repo_url: https://github.com/your/repo
repo_name: your/repo

许可证

MIT许可证

版权所有 (c) 2016-2021 Martin Donath

特此授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人免费许可，不受限制地处理本软件，包括但不限于使用、复制、修改、合并、出版、分发、再许可和/或出售软件副本的权利，并允许向其提供软件的人这样做，但须符合以下条件：

上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。

本软件按“原样”提供，不提供任何明示或暗示的担保，包括但不限于对适销性、特定用途适用性和非侵权性的担保。在任何情况下，作者或版权持有人均不对因软件或软件的使用或其他交易而引起的任何索赔、损害或其他责任承担责任，无论是合同诉讼、侵权行为还是其他形式的诉讼。