如何在MkDocs中通过markdown-exec加载外部Python脚本并执行渲染？

方案1：自定义MkDocs预处理器（推荐） #

通过轻量自定义插件，在markdown-exec处理文档前完成外部Python文件内容的替换，完全适配你的需求。

实现步骤： #

1. 在项目根目录创建plugins/markdown_exec_ext.py文件，写入以下代码：

import os
from mkdocs.plugins import BasePlugin
from mkdocs.config.config_options import Type

class MarkdownExecExtPlugin(BasePlugin):
    config_scheme = (
        ('exec_tag', Type(str, default='[[exec-file:'))
    )

    def on_pre_page_markdown(self, markdown, page, config, files):
        docs_dir = config['docs_dir']
        exec_tag = self.config['exec_tag']
        
        while exec_tag in markdown:
            start_idx = markdown.find(exec_tag)
            end_idx = markdown.find(']]', start_idx)
            if end_idx == -1:
                break
            
            file_path = markdown[start_idx + len(exec_tag):end_idx].strip()
            full_path = os.path.join(docs_dir, file_path)
            
            try:
                with open(full_path, 'r', encoding='utf-8') as f:
                    code_content = f.read()
                replacement = f"""```python exec="on"
{code_content}
```"""
                markdown = markdown.replace(markdown[start_idx:end_idx+2], replacement)
            except FileNotFoundError:
                pass
        
        return markdown

2. 在mkdocs.yml中注册该插件：

plugins:
  - markdown_exec_ext:
      exec_tag: "[[exec-file:"  # 可自定义占位符格式

3. 在Markdown文档中用占位符引用外部Python文件：

[[exec-file:scripts/hello.py]]

4. 确保目标Python文件存在（例如docs/scripts/hello.py），内容示例：

print("Hello from external script!")

这个方案会在markdown-exec处理前完成内容替换，既保留了markdown-exec的执行能力，又实现了代码的外部维护。

方案2：内联调用exec加载外部文件 #

如果不想自定义插件，可在markdown-exec代码块中直接用Python原生方法加载外部文件：

import os

# 路径基于docs目录，可根据项目结构调整
file_path = os.path.join(os.path.dirname(__file__), "scripts/hello.py")
with open(file_path, 'r', encoding='utf-8') as f:
    exec(f.read())

核心业务代码仍放在外部文件中，仅保留加载逻辑在Markdown内，也能提升代码可维护性。

注意事项： #

• 方案1需确保plugins目录被Python识别，可通过设置PYTHONPATH或调整导入路径解决。
• 所有路径需根据实际项目结构调整，避免文件找不到的问题。

内容的提问来源于stack exchange，提问作者TheRealVira