""" Markdown 轉 HTML 網站產生器 v3 ============================== 新增功能： - 字體大小調整 - 回到頂部按鈕 - 程式碼複製按鈕 - 閱讀進度條 - 全站搜尋 """ import sys sys.stdout.reconfigure(encoding='utf-8') import subprocess import re import json from pathlib import Path from html import escape from datetime import datetime from collections import defaultdict import shutil import argparse # ===== 功能模組定義 ===== # 每個功能模組包含：id, 名稱, 說明, 依賴關係 FEATURE_MODULES = { 'notes': { 'name': '三層筆記系統', 'desc': '網站筆記、文件筆記、段落筆記', 'depends': [], 'default': True, }, 'note_center': { 'name': '筆記中心', 'desc': '在首頁查看所有筆記、跨頁跳轉', 'depends': ['notes'], 'default': True, }, 'search': { 'name': '全站搜尋', 'desc': 'Ctrl+K 快捷鍵即時搜尋', 'depends': [], 'default': True, }, 'dark_mode': { 'name': '深色模式', 'desc': '自動儲存主題偏好', 'depends': [], 'default': True, }, 'pip_video': { 'name': 'PIP 影片播放', 'desc': '滾動時自動啟用子母畫面', 'depends': [], 'default': True, }, 'reading_time': { 'name': '閱讀時間估算', 'desc': '顯示預估閱讀時間', 'depends': [], 'default': True, }, 'help_modal': { 'name': '使用說明', 'desc': '❓ 按鈕開啟功能說明', 'depends': [], 'default': True, }, 'export': { 'name': '匯出筆記', 'desc': '選擇匯出範圍和格式', 'depends': ['notes'], 'default': True, }, 'floating_toc': { 'name': '浮動目錄', 'desc': 'Notion 風格懸浮目錄（預設隱藏，hover 滑出）', 'depends': [], 'default': False, # 預設使用固定目錄 }, 'watermark': { 'name': '浮水印', 'desc': '可自訂文字、日期的浮水印保護', 'depends': [], 'default': False, }, } # 預設啟用的功能 DEFAULT_FEATURES = [f for f, cfg in FEATURE_MODULES.items() if cfg['default']] def resolve_dependencies(features): """解析功能依賴，自動加入必要的依賴功能""" resolved = set(features) changed = True while changed: changed = False for f in list(resolved): if f in FEATURE_MODULES: for dep in FEATURE_MODULES[f]['depends']: if dep not in resolved: resolved.add(dep) changed = True return list(resolved) def parse_features(args): """從命令列參數解析啟用的功能""" # 如果指定了 --features，則只啟用指定的功能（從空集合開始） # 如果沒有指定 --features，則使用預設功能 if hasattr(args, 'features') and args.features: features = set() for f in args.features.split(','): f = f.strip() if f == 'all': features = set(FEATURE_MODULES.keys()) elif f == 'none': features = set() elif f in FEATURE_MODULES: features.add(f) else: features = set(DEFAULT_FEATURES) # 處理 --no-features 參數 if hasattr(args, 'no_features') and args.no_features: for f in args.no_features.split(','): f = f.strip() features.discard(f) # 解析依賴關係 return resolve_dependencies(list(features)) def process_template(template: str, features: list) -> str: """ 根據啟用的功能處理模板，移除未啟用功能的區塊。 模板中使用以下標記： ... 該功能的 HTML/CSS/JS ... 如果 feature_name 不在 features 列表中，整個區塊會被移除。 """ import re # 匹配功能區塊的正則表達式 # 支援多行匹配，非貪婪模式 pattern = r'(.*?)' def replace_feature_block(match): feature_name = match.group(1) feature_content = match.group(2) if feature_name in features: # 保留內容（移除標記本身） return feature_content else: # 移除整個區塊 return '' # 使用 DOTALL 讓 . 可以匹配換行 processed = re.sub(pattern, replace_feature_block, template, flags=re.DOTALL) return processed # ===== 首頁模板 ===== INDEX_TEMPLATE = ''' {site_title}

{site_title}

{site_description}

{total_docs}
文件數量
{total_categories}
分類數量
{generated_date}
生成日期
{categories_html} {demos_html}

📚 筆記中心

載入中...
''' # ===== 文件頁面模板 ===== DOC_TEMPLATE = ''' {title}
{content}
{prev_link} {next_link}
0:00 / 0:00

📝 筆記

❓ 使用說明

🔍 搜尋功能

  • 點擊搜尋框或按 Ctrl+K 快速搜尋
  • 搜尋結果會高亮顯示關鍵字

📝 筆記功能

  • 🌐 網站筆記：記錄整體心得（全站共用）
  • 📄 文件筆記：記錄單篇文件重點
  • 📝 段落筆記：在段落旁點擊 📝 記錄

💾 筆記儲存

  • 自動儲存於瀏覽器（換電腦會遺失）
  • 建議定期點擊「匯出筆記」備份

🎨 其他功能

  • 🌙 深色模式：右上角切換
  • 🔤 字體大小：A- / A+ 調整
  • 📺 影片子母畫面：滾動時自動懸浮

📤 匯出筆記

選擇要匯出的筆記範圍：

(0 則)
(0 則)
(0 則)

匯出格式：

📚 筆記中心

載入中...
''' def extract_title_from_md(md_path: Path) -> str: content = md_path.read_text(encoding='utf-8') # 1. 先嘗試從 YAML frontmatter 提取 title yaml_match = re.search(r'^---\s*\n(.*?)\n---', content, re.DOTALL) if yaml_match: yaml_content = yaml_match.group(1) title_match = re.search(r'^title:\s*["\']?(.+?)["\']?\s*$', yaml_content, re.MULTILINE) if title_match: return title_match.group(1).strip() # 2. 移除 YAML frontmatter 後，找第一個 # 標題 content_without_yaml = re.sub(r'^---\s*\n.*?\n---\s*\n', '', content, flags=re.DOTALL) match = re.search(r'^#\s+(.+)$', content_without_yaml, re.MULTILINE) if match: return match.group(1).strip() # 3. 都找不到就用檔名 return md_path.stem def extract_description_from_md(md_path: Path) -> str: content = md_path.read_text(encoding='utf-8') # 移除 YAML frontmatter content = re.sub(r'^---\s*\n.*?\n---\s*\n', '', content, flags=re.DOTALL) lines = content.split('\n') for line in lines: line = line.strip() # 跳過空行、標題、註解 if line and not line.startswith('#') and not line.startswith('---') and not line.startswith('>'): desc = re.sub(r'\*\*|__|\*|_|`', '', line) if desc: # 確保有內容 return desc[:60] + '...' if len(desc) > 60 else desc return '' def extract_text_content(md_path: Path) -> str: """提取純文字內容供搜尋用""" content = md_path.read_text(encoding='utf-8') # 移除 Markdown 語法 content = re.sub(r'```[\s\S]*?```', '', content) # 移除代碼區塊 content = re.sub(r'`[^`]+`', '', content) # 移除行內代碼 content = re.sub(r'\[([^\]]+)\]\([^)]+\)', r'\1', content) # 連結轉文字 content = re.sub(r'[#*_~>`|]', '', content) # 移除 Markdown 符號 content = re.sub(r'\n+', ' ', content) # 換行轉空格 content = re.sub(r'\s+', ' ', content) # 多空格轉單空格 return content.strip()[:500] # 限制長度 def generate_toc(html_content: str) -> tuple: toc_items = [] counter = [0] def add_id(match): level = match.group(1) attrs = match.group(2) or '' text = match.group(3) if 'id="' not in attrs: clean_text = re.sub(r'<[^>]+>', '', text) slug = re.sub(r'[^\w\u4e00-\u9fff]+', '-', clean_text.lower()).strip('-') if not slug: counter[0] += 1 slug = f'section-{counter[0]}' return f'{text}' return match.group(0) html_content = re.sub(r']*)>(.*?)', add_id, html_content, flags=re.DOTALL) for match in re.finditer(r']*id="([^"]*)"[^>]*>(.*?)', html_content, re.DOTALL): level, id_, text = match.groups() clean_text = re.sub(r'<[^>]+>', '', text) toc_items.append((level, id_, clean_text)) toc_html = '' return toc_html, html_content def convert_folder_to_site( source_folder: Path, output_folder: Path = None, site_title: str = "文件目錄", site_description: str = "", max_depth: int = 1, features: list = None, watermark_text: str = "" ): # 預設啟用所有功能 if features is None: features = DEFAULT_FEATURES source_folder = Path(source_folder) if output_folder is None: output_folder = source_folder / 'html_output' else: output_folder = Path(output_folder) output_folder.mkdir(parents=True, exist_ok=True) # 收集 Markdown 檔案 md_files = [] for md_file in source_folder.rglob('*.md'): rel_path = md_file.relative_to(source_folder) depth = len(rel_path.parents) - 1 if depth <= max_depth: md_files.append(md_file) print(f"找到 {len(md_files)} 個 Markdown 檔案") print("=" * 50) # 分類與搜尋索引 categories = defaultdict(list) all_docs = [] search_index = [] for md_file in md_files: rel_path = md_file.relative_to(source_folder) parent = rel_path.parent.as_posix() parts = parent.split('/') category = parts[0] if parts[0] != '.' else '總覽' title = extract_title_from_md(md_file) desc = extract_description_from_md(md_file) text_content = extract_text_content(md_file) html_rel_path = rel_path.with_suffix('.html') doc_info = { 'md_path': md_file, 'html_rel_path': html_rel_path, 'title': title, 'description': desc, 'category': category } categories[category].append(doc_info) all_docs.append(doc_info) # 搜尋索引 search_index.append({ 'title': title, 'url': html_rel_path.as_posix(), 'content': text_content }) # 轉換每個 Markdown 檔案 for i, doc in enumerate(all_docs): md_path = doc['md_path'] html_path = output_folder / doc['html_rel_path'] html_path.parent.mkdir(parents=True, exist_ok=True) print(f"[{i+1}/{len(all_docs)}] {doc['title']}") # 尋找同資料夾的影片檔案（供影片版使用） video_file = None video_files = list(md_path.parent.glob('*.mp4')) if video_files: video_file = video_files[0] result = subprocess.run([ 'pandoc', str(md_path), '--from', 'markdown', '--to', 'html5', '--no-highlight' ], capture_output=True, text=True, encoding='utf-8') if result.returncode != 0: print(f" ✗ 錯誤") continue content = result.stdout toc, content = generate_toc(content) depth = len(doc['html_rel_path'].parents) - 1 index_path = '../' * depth + 'index.html' if depth > 0 else 'index.html' prev_link = '' next_link = '' if i > 0: prev_doc = all_docs[i-1] prev_href = '../' * depth + prev_doc['html_rel_path'].as_posix() prev_link = f'← {prev_doc["title"][:25]}' if i < len(all_docs) - 1: next_doc = all_docs[i+1] next_href = '../' * depth + next_doc['html_rel_path'].as_posix() next_link = f'{next_doc["title"][:25]} →' # 輕量版（無影片）- 根據功能處理模板 processed_doc_template = process_template(DOC_TEMPLATE, features) html = processed_doc_template.format( title=escape(doc['title']), category=escape(doc['category']), index_path=index_path, toc=toc, content=content, prev_link=prev_link, next_link=next_link, watermark_text=escape(watermark_text) ) html_path.write_text(html, encoding='utf-8') # 記錄影片資訊供後續影片版使用 doc['video_file'] = video_file doc['toc'] = toc doc['content'] = content doc['index_path'] = index_path doc['prev_link'] = prev_link doc['next_link'] = next_link print(f" ✓ 完成") # 收集範例作品（程式碼資料夾中的 HTML 檔案） print() print("收集範例作品...") demos = [] maps_folder = output_folder / 'maps' for html_file in source_folder.rglob('*.html'): # 排除已生成的 html_output if 'html_output' in str(html_file): continue # 只收集「程式碼」資料夾中的 HTML if '程式碼' in str(html_file.parent): maps_folder.mkdir(parents=True, exist_ok=True) dest_path = maps_folder / html_file.name shutil.copy2(html_file, dest_path) # 從檔名提取標題 title = html_file.stem.replace('_', ' ') demos.append({ 'title': title, 'url': f'maps/{html_file.name}', 'type': '互動地圖' }) print(f" ✓ {title}") if not demos: print(" (無範例作品)") # 生成搜尋索引 print() print("生成搜尋索引...") search_index_path = output_folder / 'search-index.json' search_index_path.write_text(json.dumps(search_index, ensure_ascii=False, indent=2), encoding='utf-8') # 生成首頁 print("生成首頁...") categories_html = '' for category, docs in sorted(categories.items()): cards_html = '' for doc in docs: href = doc['html_rel_path'].as_posix() cards_html += f'''

{escape(doc['title'])}

{escape(doc['description'])}

 ''' categories_html += f'''

{escape(category)}

{cards_html}
''' # 生成範例作品區塊 if demos: demo_cards = '' for demo in demos: demo_cards += f'''

🗺️ {escape(demo['title'])}

{escape(demo['type'])} ''' demos_html = f'''

🎯 範例作品

{demo_cards}
''' else: demos_html = '' # 搜尋索引 JSON 嵌入 HTML（避免 file:// CORS 問題） search_index_json = json.dumps(search_index, ensure_ascii=False) if 'search' in features else '[]' # 根據功能處理模板 processed_index_template = process_template(INDEX_TEMPLATE, features) index_html = processed_index_template.format( site_title=escape(site_title), site_description=escape(site_description), total_docs=len(all_docs), total_categories=len(categories), generated_date=datetime.now().strftime('%Y-%m-%d'), categories_html=categories_html, demos_html=demos_html, search_index_json=search_index_json ) index_path = output_folder / 'index.html' index_path.write_text(index_html, encoding='utf-8') # ===== 生成影片版 ===== video_output_folder = output_folder.parent / (output_folder.name + '_video') video_output_folder.mkdir(parents=True, exist_ok=True) print() print("生成影片版...") video_count = 0 for doc in all_docs: video_html_path = video_output_folder / doc['html_rel_path'] video_html_path.parent.mkdir(parents=True, exist_ok=True) # 生成影片嵌入區塊（插入到 h1 標題後面） content_with_video = doc['content'] if doc.get('video_file'): video_file = doc['video_file'] video_dest = video_html_path.parent / video_file.name shutil.copy2(video_file, video_dest) video_block = f'''

📺 教學影片

''' # 插入到第一個 後面 content_with_video = doc['content'].replace('', '\n' + video_block, 1) video_count += 1 print(f" 📺 {doc['title']}") # 影片版也使用模組化模板 processed_doc_template = process_template(DOC_TEMPLATE, features) html = processed_doc_template.format( title=escape(doc['title']), category=escape(doc['category']), index_path=doc['index_path'], toc=doc['toc'], content=content_with_video, prev_link=doc['prev_link'], next_link=doc['next_link'], watermark_text=escape(watermark_text) ) video_html_path.write_text(html, encoding='utf-8') # 複製 maps 資料夾到影片版 if (output_folder / 'maps').exists(): shutil.copytree(output_folder / 'maps', video_output_folder / 'maps', dirs_exist_ok=True) # 生成影片版首頁（標題加上「影片版」）- 使用處理過的模板 video_index_html = processed_index_template.format( site_title=escape(site_title + '（影片版）'), site_description=escape(site_description), total_docs=len(all_docs), total_categories=len(categories), generated_date=datetime.now().strftime('%Y-%m-%d'), categories_html=categories_html, demos_html=demos_html, search_index_json=search_index_json ) (video_output_folder / 'index.html').write_text(video_index_html, encoding='utf-8') print(f" ✓ 影片版完成（{video_count} 部影片）") print() print("=" * 50) print(f"✅ 完成！共 {len(all_docs)} 份文件") print(f" 📁 輕量版: {output_folder}") print(f" 📺 影片版: {video_output_folder}") return index_path if __name__ == '__main__': # 建立功能清單說明 feature_list = '\n'.join([f" {f}: {cfg['name']} - {cfg['desc']}" for f, cfg in FEATURE_MODULES.items()]) parser = argparse.ArgumentParser( description='Markdown 轉 HTML 網站 v3（支援模組化功能）', formatter_class=argparse.RawDescriptionHelpFormatter, epilog=f''' 可用功能模組： {feature_list} 範例： # 啟用所有功能（預設） python md_to_html_site.py ./docs # 只啟用搜尋和深色模式 python md_to_html_site.py ./docs --features search,dark_mode # 停用筆記相關功能 python md_to_html_site.py ./docs --no-features notes,note_center,export # 最小化版本（無任何額外功能） python md_to_html_site.py ./docs --features none ''' ) parser.add_argument('input', nargs='?', help='來源資料夾') parser.add_argument('-o', '--output', help='輸出資料夾') parser.add_argument('--title', default='文件目錄', help='標題') parser.add_argument('--description', default='', help='描述') parser.add_argument('--depth', type=int, default=1, help='掃描深度') parser.add_argument('--features', metavar='LIST', help='啟用的功能（逗號分隔），可用 "all" 或 "none"') parser.add_argument('--no-features', metavar='LIST', dest='no_features', help='停用的功能（逗號分隔）') parser.add_argument('--list-features', action='store_true', help='列出所有可用功能模組') parser.add_argument('--watermark', metavar='TEXT', help='浮水印文字（會自動啟用 watermark 功能）') args = parser.parse_args() # 如果沒有提供 input 且沒有 --list-features，顯示錯誤 if not args.input and not args.list_features: parser.error("請提供來源資料夾，或使用 --list-features 查看可用功能") # 列出功能模組 if args.list_features: print("\n📦 可用功能模組：") print("=" * 50) for f, cfg in FEATURE_MODULES.items(): deps = f" (依賴: {', '.join(cfg['depends'])})" if cfg['depends'] else "" default = " ✓" if cfg['default'] else "" print(f" {f:15} {cfg['name']}{default}") print(f" {cfg['desc']}{deps}") print("\n✓ = 預設啟用") sys.exit(0) # 解析啟用的功能 enabled_features = parse_features(args) # 如果指定了浮水印，自動啟用 watermark 功能 watermark_text = '' if args.watermark: enabled_features = list(set(enabled_features) | {'watermark'}) # 浮水印文字加上日期 from datetime import datetime watermark_text = f"{args.watermark} | {datetime.now().strftime('%Y-%m-%d')}" print(f"\n🔧 啟用功能: {', '.join(sorted(enabled_features))}") if watermark_text: print(f"🔖 浮水印: {watermark_text}") index_path = convert_folder_to_site( Path(args.input), Path(args.output) if args.output else None, args.title, args.description, args.depth, enabled_features, watermark_text ) import webbrowser webbrowser.open(str(index_path))