如何用myST替代品进行超链接

Question

我正在使用 Sphinx、Doxygen 和 CMake 构建项目文档。

在我的项目中，有几个 Markdown 文件，我必须在其中超链接不同的链接。这些链接有共同的风格，它们来自共同的来源。

https://common/source/html/a.html
https://common/source/html/b.html
https://common/source/html/c.html

所以，现在我的超链接如下：

[This is a](https://common/source/html/a.html)
[This is b](https://common/source/html/b.html)
[This is c](https://common/source/html/c.html)

我的愿望是使用一个变量来保存这个公共地址

https://common/source/html/

然后我可以修改前面的代码片段如下：

[This is a](COMMON_ADDRESSa.html)
[This is b](COMMON_ADDRESSb.html)
[This is c](COMMON_ADDRESSc.html)

我浏览了 myST 文档和 git 问题，发现一些已接近但失败了

• 方法1
  在这里，在狮身人面像的

  conf.py

  我添加了

myst_enable_extensions = [
    # ...
    'substitution'
]

myst_substitutions = {
 "a_link": f"[TARGET NAME](https://common/source/html/)",
}

如果我在 Markdown 文件中添加

index.html

，这会将我带到

{{a_link}}

。但我的愿望是从 markdown 文件连接 html 文件，但不知道该怎么做。我已经尝试过

{{a_link}}/a.html

但不起作用。

• 方法2
  这里还写入了目标名称和完整的链接地址。没有描述连接链接地址的方法

• 我也尝试使用

  rst_prolog

  替换公共地址，但也失败了

我想我不明白超链接过程在 Markdown 文件中是如何工作的。

因此，我正在寻找一种方法，可以解析将在变量中分配的长地址，并可以将所需的 html 文件名与其连接起来以执行超链接。

Answer 1

方案

正如评论中已经指出的那样，您可以在配置文件中使用

myst_url_schemes

。这是最灵活且开销较低的方法

# define extra or use directly
COMMON_TARGET = "https://common/source/html/"


myst_url_schemes = {
    # These are the defaults; you should keep them
    "http": None,
    "https": None,
    "ftp : None,
    "mailto" : None,
    # avoid f/format strings as they reduce {{ }} -> { }
    "dynamic_creation" : "%s{{path}}#{{fragment}}" % COMMON_TARGET,
    "common_link" : "https://common/source/html/{{path}}#{{fragment}}",

用法例如

[text](common_link:path_to/a.html#some-fragment)

替代

替换的工作原理非常相似，要构建链接，您需要注意，您需要提供一个 complete 表达式来生成 Markdown url。在内部

{{ You can use python code }}

，这使它变得灵活，但也很丑陋。

# declare variables
myst_substitutions = {
  "key1": "I'm a **substitution**",
  "common_link" : COMMON_TARGET,
  "common_text" : "This is ",
}

# Afterwards use as
{{ '[{common_text} hardcoded_a ]({}path/hardcoded/a.html)'.format(common_text, common_link) }}

使用角色

开销较大，但如果您编写自定义角色，它可以让您以后更轻松地处理事情。然后你就可以在 MyST 里面写

{common_link_role}`text a <a.html>`

我认为 url_schemes 是您想要和需要的，自定义角色设置只会以不同的语法重新创建它。我把他们的设置留给未来的读者。

# conf.py

def custom_role(name, rawtext, text, lineno, inliner,
    options=None, content=None):
    # parse text to get target and text
    ...
    target, displayed_text = ...
    # create nodes
    # nodes = 
    # nodes should result in nodes representing <a href=COMMON_TARGET+target> $displayed_text </a>
    ...
    messages = []
    return nodes, messages 


def setup(app):
   app.add_role("common_link_role", custom_role)