#!/usr/bin/env python3 # -*- coding: utf-8 -*- """ 自动将docs目录下的文件添加到mkdocs.yml导航配置中 """ import os import sys import re import yaml from pathlib import Path def load_mkdocs_nav(mkdocs_path='mkdocs.yml'): """加载mkdocs.yml中的导航配置""" try: with open(mkdocs_path, 'r', encoding='utf-8') as f: content = f.read() # 使用正则表达式提取nav部分 nav_match = re.search(r'nav:\s*\n(.*?)(?=\n\w+:|$)', content, re.DOTALL) if not nav_match: print("错误: 找不到nav配置") sys.exit(1) nav_content = nav_match.group(1) # 解析YAML格式的nav内容 # 为nav内容添加适当的缩进 nav_yaml = "nav:\n" + nav_content config = yaml.safe_load(nav_yaml) return config.get('nav', []) except FileNotFoundError: print(f"错误: 找不到文件 {mkdocs_path}") sys.exit(1) except Exception as e: print(f"错误: 解析文件失败: {e}") sys.exit(1) def save_mkdocs_nav(nav, mkdocs_path='mkdocs.yml'): """保存导航配置到mkdocs.yml""" try: with open(mkdocs_path, 'r', encoding='utf-8') as f: content = f.read() # 生成新的nav内容 nav_yaml = yaml.dump({'nav': nav}, allow_unicode=True, default_flow_style=False, sort_keys=False) # 移除第一行的"nav:" nav_lines = nav_yaml.split('\n') new_nav_content = '\n'.join(nav_lines[1:]) # 跳过第一行 # 替换原有的nav部分，使用re.escape避免特殊字符问题 nav_pattern = r'(nav:\s*\n)(.*?)(?=\n\w+:|$)' # 对new_nav_content进行转义处理 escaped_content = re.escape(new_nav_content) # 但我们需要保留实际的换行符等，所以使用更简单的方法 new_content = re.sub(nav_pattern, r'\1' + new_nav_content, content, flags=re.DOTALL) with open(mkdocs_path, 'w', encoding='utf-8') as f: f.write(new_content) print(f"✓ 已更新 {mkdocs_path}") except Exception as e: print(f"错误: 保存文件失败: {e}") sys.exit(1) def get_all_md_files(docs_dir='docs'): """获取docs目录下的所有.md文件""" md_files = [] for root, dirs, files in os.walk(docs_dir): for file in files: if file.endswith('.md'): rel_path = os.path.relpath(os.path.join(root, file), docs_dir) # 将Windows路径分隔符转换为Unix风格（/） rel_path = rel_path.replace('\\', '/') md_files.append(rel_path) return sorted(md_files) def get_nav_files(nav): """从导航配置中提取所有文件路径""" nav_files = [] def extract_files(item): if isinstance(item, dict): for key, value in item.items(): if isinstance(value, list): for subitem in value: extract_files(subitem) elif isinstance(value, str): nav_files.append(value) elif isinstance(item, str): nav_files.append(item) for item in nav: extract_files(item) return nav_files def categorize_file(file_path): """根据文件路径分类文件""" path_parts = file_path.split('/') # 如果文件在根目录 if len(path_parts) == 1: return "其他" # 根据目录名分类 category_map = { '技术文档': '技术文档', '开发指南': '开发指南', '学习笔记': '学习笔记', 'DevOps平台': 'DevOps平台', 'cursor': 'Cursor工具', 'Obsidian': 'Obsidian笔记' } first_dir = path_parts[0] # 如果目录名在映射中，使用映射的名称，否则使用目录名 return category_map.get(first_dir, first_dir) def remove_deleted_files_from_nav(nav, existing_files=None, docs_dir='docs'): """从导航配置中删除已不存在的文件""" deleted_files = [] def clean_item(item): """递归清理导航项，删除不存在的文件""" if isinstance(item, dict): # 处理字典类型（分类） cleaned_dict = {} for key, value in item.items(): if isinstance(value, list): # 递归处理列表 cleaned_list = [] for subitem in value: cleaned = clean_item(subitem) if cleaned is not None: cleaned_list.append(cleaned) # 如果列表不为空，保留分类 if cleaned_list: cleaned_dict[key] = cleaned_list elif isinstance(value, str): # 检查文件是否存在 file_path = os.path.join(docs_dir, value.replace('/', os.sep)) if os.path.exists(file_path) or value == 'index.md': cleaned_dict[key] = value else: deleted_files.append(value) else: # 其他类型，保留 cleaned_dict[key] = value # 如果字典为空，返回None表示删除 return cleaned_dict if cleaned_dict else None elif isinstance(item, str): # 检查文件是否存在 file_path = os.path.join(docs_dir, item.replace('/', os.sep)) if os.path.exists(file_path) or item == 'index.md': return item else: deleted_files.append(item) return None else: # 其他类型，保留 return item # 处理导航列表 new_nav = [] for item in nav: cleaned = clean_item(item) if cleaned is not None: new_nav.append(cleaned) return new_nav, deleted_files def add_files_to_nav(nav, missing_files): """将缺失的文件添加到导航配置中""" # 创建分类字典 categories = {} for file_path in missing_files: category = categorize_file(file_path) if category not in categories: categories[category] = [] categories[category].append(file_path) # 将文件添加到现有分类或创建新分类 for category, files in categories.items(): category_found = False # 查找是否已存在该分类 for i, item in enumerate(nav): if isinstance(item, dict) and category in item: # 添加到现有分类 existing_files = set(item[category]) for file_path in files: if file_path not in existing_files: item[category].append(file_path) category_found = True print(f"✓ 已将 {len(files)} 个文件添加到 '{category}' 分类") break # 如果分类不存在，创建新分类 if not category_found: nav.append({category: sorted(files)}) print(f"✓ 已创建新分类 '{category}' 并添加 {len(files)} 个文件") return nav def main(): print("开始自动同步docs目录和mkdocs.yml导航配置...") print("=" * 60) # 1. 加载当前导航配置 print("1. 加载mkdocs.yml导航配置...") nav = load_mkdocs_nav() # 2. 获取所有.md文件 print("2. 扫描docs目录下的所有.md文件...") all_md_files = get_all_md_files() print(f" 找到 {len(all_md_files)} 个.md文件") # 3. 获取导航中的文件 print("3. 分析当前导航配置...") nav_files = get_nav_files(nav) print(f" 导航中已有 {len(nav_files)} 个文件") # 4. 检查并删除已删除的文件 print("4. 检查已删除的文件...") updated_nav, deleted_files = remove_deleted_files_from_nav(nav, all_md_files) if deleted_files: print(f" 发现 {len(deleted_files)} 个文件已删除:") for i, file_path in enumerate(deleted_files, 1): print(f" {i:2d}. {file_path}") nav = updated_nav # 重新获取导航文件列表（已更新） nav_files = get_nav_files(nav) else: print(" ✓ 没有发现已删除的文件") # 5. 找出缺失的文件（需要添加到导航的） missing_files = [] for md_file in all_md_files: # 将路径统一为Unix风格进行比较 if md_file not in nav_files and md_file != 'index.md': missing_files.append(md_file) # 6. 汇总变更 has_changes = len(deleted_files) > 0 or len(missing_files) > 0 if not has_changes: print("\n✓ 导航配置已是最新，无需更新") return # 显示变更摘要 print("\n5. 变更摘要:") if deleted_files: print(f" 将删除 {len(deleted_files)} 个已不存在的文件") if missing_files: print(f" 将添加 {len(missing_files)} 个新文件:") for i, file_path in enumerate(missing_files, 1): print(f" {i:2d}. {file_path}") # 7. 确认是否继续 print("\n6. 是否继续更新mkdocs.yml？") response = input(" 输入 'y' 继续，其他键取消: ") if response.lower() != 'y': print("操作已取消") return # 8. 添加文件到导航 print("\n7. 正在更新mkdocs.yml...") if missing_files: updated_nav = add_files_to_nav(updated_nav, missing_files) # 9. 保存配置 save_mkdocs_nav(updated_nav) print("\n" + "=" * 60) print("完成！mkdocs.yml已更新") if deleted_files: print(f"删除了 {len(deleted_files)} 个已不存在的文件") if missing_files: print(f"添加了 {len(missing_files)} 个新文件到导航中") if __name__ == '__main__': main()