mkdocs.yml

site_name: 现代 C++ 教程  # 网站标题,显示在浏览器标签和页面顶部
site_description: 系统化的现代 C++ 教程 — 从基础入门到领域实战  # 网站描述,用于SEO优化
site_author: Charliechen  # 作者名称,可以改成你的真实姓名或网名
site_url: https://awesome-embedded-learning-studio.github.io/Tutorial_AwesomeModernCPP/

# 版权信息,显示在页面底部
copyright: Copyright © 2025 Charliechen - 保留所有权利

# 文档源文件夹
docs_dir: "documents"


# ==================== 主题配置 ====================
# Material 是一个现代化的 MkDocs 主题,提供了丰富的功能和美观的界面

theme:
  name: material  # 使用 Material 主题
  custom_dir: overrides  # 自定义模板覆盖目录（i18n 语言切换器等）
  language: zh  # 界面语言设置为简体中文
  
  # 自定义网站图标和Logo
  logo: images/logo.svg  # 网站Logo（SVG 优先）
  favicon: images/favicon.ico  # 浏览器标签图标

  # 调色板配置 - 支持亮色/暗色模式切换
  palette:
    # 亮色模式
    - media: "(prefers-color-scheme: light)"
      scheme: default  # 使用默认亮色主题
      primary: indigo  # 主色调:靛蓝色(导航栏等)
      accent: indigo  # 强调色(链接、按钮等)
      toggle:
        icon: material/brightness-7  # 切换图标
        name: 切换至暗色模式
    
    # 暗色模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate  # 使用暗色主题
      primary: black  # 主色调:黑色
      accent: indigo  # 强调色保持一致
      toggle:
        icon: material/brightness-4  # 切换图标
        name: 切换至亮色模式
  
  # 字体配置
  font:
    text: Noto Sans SC  # 中文优先正文字体
    code: JetBrains Mono  # 等宽字体,C++符号更清晰
  
  # 功能特性开关
  features:
    # ---------- 导航功能 ----------
    - navigation.tracking  # 地址栏自动更新为当前标题的锚点
    - navigation.tabs  # 顶部显示主要章节标签
    - navigation.tabs.sticky  # 滚动时标签栏保持固定
    - navigation.sections  # 侧边栏显示章节分组
    - navigation.prune  # 裁剪不可见的导航项,提升大站点性能
    - navigation.path  # 显示当前页面的完整路径
    - navigation.indexes  # 支持章节索引页
    - navigation.top  # 显示"返回顶部"按钮
    - navigation.footer  # 页面底部显示上一页/下一页导航

    # ---------- 目录功能 ----------
    - toc.follow  # 目录自动跟随滚动
    
    # ---------- 搜索功能 ----------
    - search.suggest  # 搜索时显示建议
    - search.highlight  # 高亮显示搜索结果
    - search.share  # 允许分享搜索结果链接
    
    # ---------- 内容功能 ----------
    - content.code.copy  # 代码块添加复制按钮
    - content.code.select  # 代码块可以选择
    - content.code.annotate  # 代码块支持注释
    - content.tabs.link  # 内容标签页可以链接
    - content.tooltips  # 鼠标悬停显示提示信息
    - content.action.edit  # 显示"编辑此页"按钮
    - content.action.view  # 显示"查看源代码"按钮


# ==================== Markdown 扩展 ====================
# 这些扩展增强了 Markdown 的功能,让你能写出更丰富的内容

markdown_extensions:
  # ---------- 基础扩展 ----------
  - abbr  # 支持缩写定义
  - attr_list  # 允许为元素添加HTML属性
  - def_list  # 支持定义列表
  - footnotes  # 支持脚注
  - md_in_html  # 允许在HTML中使用Markdown
  - tables  # 表格支持(标准Markdown已支持,这里确保启用)
  
  # 目录扩展
  - toc:
      permalink: true  # 标题旁显示永久链接符号(#)
      permalink_title: 链接到此章节  # 永久链接的提示文字
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower  # URL中的标题转为小写
  
  # 警告框扩展 - 可以创建提示、警告、危险等样式的信息框
  - admonition  # 基础警告框支持
  
  # ---------- PyMdown 扩展(强大的Markdown增强) ----------
  
  # 细节折叠块 - 可折叠的内容区域
  - pymdownx.details
  
  # 代码高亮
  - pymdownx.highlight:
      anchor_linenums: true  # 代码行号可以被链接
      line_spans: __span  # 每行代码单独包装
      pygments_lang_class: true  # 添加语言类名
      linenums: true  # 显示行号
      linenums_style: pymdownx-inline  # 行号样式
  
  # 行内代码高亮
  - pymdownx.inlinehilite
  
  # 代码块和其他内容的围栏支持
  - pymdownx.superfences:
      custom_fences:
        # 支持 Mermaid 图表
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  
  # 内容标签页 - 可以创建多个标签切换的内容区域
  - pymdownx.tabbed:
      alternate_style: true  # 使用替代样式
      combine_header_slug: true  # 合并标签头的slug
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  
  # Emoji 支持 - 可以使用 :smile: 这样的表情符号
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  
  # 其他实用扩展
  - pymdownx.caret  # 支持上标 ^text^
  - pymdownx.mark  # 支持高亮标记 ==text==
  - pymdownx.tilde  # 支持删除线 ~~text~~ 和下标 ~text~
  - pymdownx.keys  # 支持键盘按键显示 ++ctrl+alt+del++
  - pymdownx.smartsymbols  # 智能符号替换
  - pymdownx.snippets  # 路径相对于 mkdocs.yml 所在目录（项目根目录）
  - pymdownx.critic  # 支持批注和修订标记
  - pymdownx.betterem  # 改进的强调语法

  # 任务列表语法（- [ ] / - [x]）
  - pymdownx.tasklist:
      custom_checkbox: true
      clickable_checkbox: true

  # 数学公式渲染（LaTeX via MathJax）
  - pymdownx.arithmatex:
      generic: true


# ==================== 插件配置 ====================
# 插件为网站添加额外功能

plugins:
  # 搜索插件 - 提供全站搜索功能
  - search:
      separator: '[\s\u200b\-_,:!=\[\]()"/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'  # 中文分词支持
      lang:
        - zh  # 中文搜索
        - en  # 英文搜索
      pipeline:
        - stemmer
        - stopWordFilter
        - trimmer

  # 标签插件 - 为文章添加标签分类
  - tags:
      tags_file: tags.md

  # Awesome Pages 插件 - 自动展开 nav 中的目录引用，支持 .pages 文件控制排序和标题
  - awesome-pages

  # 多语言支持 - 使用后缀方案 (file.md + file.en.md)
  # 注意：i18n 必须在 git-revision-date-localized 之前定义
  - i18n:
      docs_structure: suffix
      languages:
        - locale: zh
          name: 中文
          default: true
          build: true
          site_name: "现代 C++ 教程"
          site_description: "系统化的现代 C++ 教程 — 从基础入门到领域实战"
        - locale: en
          name: English
          build: true
          site_name: "Awesome Modern C++ for Embedded"
          site_description: "Modern C++ Tutorial for Embedded Systems"
          nav_translations:
            基础与特性: Basics & Features
            标准库与高级: Std Library & Advanced
            工程实践: Engineering
            领域实战: Domains & Practice
            卷一 · 基础入门: Vol.1 - C++ Basics
            卷二 · 现代特性: Vol.2 - Modern Features
            卷三 · 标准库深入: Vol.3 - Standard Library
            卷四 · 高级主题: Vol.4 - Advanced Topics
            卷五 · 并发编程: Vol.5 - Concurrency
            卷六 · 性能优化: Vol.6 - Performance
            卷七 · 工程实践: Vol.7 - Engineering
            卷八 · 领域应用: Vol.8 - Domains
            编译与链接: Compilation & Linking
            实战项目: Projects
            标签: Tags

  # Git 修订日期插件 - 自动显示文章的创建和更新时间
  - git-revision-date-localized:
      enabled: !ENV [MKDOCS_ENABLE_GIT, true]
      enable_creation_date: true  # 显示创建日期
      fallback_to_build_date: true  # 如果Git历史不可用,使用构建日期
      type: datetime  # 日期格式: datetime(日期+时间) / date(仅日期) / iso_date / iso_datetime
      timezone: Asia/Shanghai  # 时区设置
      locale: zh  # 本地化语言

  # Git 作者信息
  - git-authors:
      enabled: !ENV [MKDOCS_ENABLE_GIT, true]
      show_line_count: false
      show_contribution: false
      sort_authors_by: "name"
      authorship_threshold_percent: 5

  # HTML/CSS/JS 压缩
  - minify:
      enabled: !ENV [MKDOCS_ENABLE_MINIFY, true]
      minify_html: true
      minify_css: true
      minify_js: true
      htmlmin_opts:
        remove_comments: true
        remove_empty_space: true

  # 以下插件暂未启用，待条件满足后取消注释：
  #
  # mkdocs-redirects: 旧中文路径在 tutorial/ 下（旧 docs_dir），当前 docs_dir 已改为
  # documents/，redirect_maps 无法匹配不存在的路径。重定向需在 hosting 层处理。
  # - redirects:
  #     redirect_maps: { ... }


# ==================== Hooks ====================
# MkDocs 钩子脚本,用于在构建过程中自动处理内容

hooks:
  - documents/hooks/meta.py
  - documents/hooks/i18n_banner.py


# ==================== 额外配置 ====================

# 社交媒体链接 - 显示在页面右上角
extra:
  # 社交媒体图标
  social:
    - icon: fontawesome/brands/github  # GitHub图标
      link: https://github.com/Awesome-Embedded-Learning-Studio  # 你的GitHub主页
      name: GitHub
    - icon: fontawesome/solid/paper-plane  # 邮件图标
      link: mailto:725610365@qq.com
      name: 发送邮件


# ==================== 额外的CSS和JavaScript ====================
# 可以添加自定义样式和脚本

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js


# ==================== 注意事项 ====================
# 本地预览命令:
#    mkdocs serve  # 启动本地服务器,访问 http://127.0.0.1:8000
#
# ==================== 配置结束 ====================