标签: mkdocs

有没有办法在Mkdocs或Sphinx中创建如下的选项卡代码块？

我正在使用的 mkdocs.yml nav 文件包含手册网站的层次结构树，其中包含内容文章所属的多个类别和子类别；该树绝对是虚拟的，不基于文件夹结构/网站路径。我正在寻找一种为每个树节点（类别）生成永久链接的方法。如果 Markdown 或其扩展不可能做到这一点，那么也许可以使用 html/css 元素。

我对 Markdown 和 mkdocs 很陌生；我彻底用谷歌搜索来找到解决方案，但未能找到。

site_name: My Site
site_dir: docs/guides/
site_url: http://example.net/
docs_dir: 'src'
nav:
  - 'TOP LEVEL CATEGORY':
    - 'BOTTOM LEVEL CATEGORY':
         - Manual 1: 'manuals/Manual1.md'
         - Manual 2: 'manuals/Manual2.md'
    - 'BOTTOM LEVEL 2':
{...}
  - 'TOP LEVEL CATEGORY 2':
{...}

markdown_extensions:
    - smarty
    - toc:
        permalink: True
        separator: "_"
    - sane_lists
    - tables
    - meta
    - fenced_code
    - admonition
    - footnotes

构建的具有可扩展节点的虚拟层次树是可以的，但我确实需要为每个类别和子类别生成永久链接，例如 example.net/docs/guides/toplevelcat/bottomlevelcat 或 example.net/docs/guides/toplevelcat# Bottomlevelcat 链接的组织方式以及它们是自动生成还是手动预设并不重要

该链接可能会指向包含属于该类别的所有手册的索引页面，或者仅显示根mysite.net/docs/guides/页面，并展开所需的类别

我一直在尝试通过添加气流插件来扩展气流的用户界面。我的目标是能够从气流中显示内部项目文档。我为此使用 MKDocs。

我遵循了气流文档流程（https://airflow.apache.org/plugins.html#example）并成功创建了一个插件。该链接出现，当我点击它时，它会将我带到 index.html。我的问题是它没有呈现任何 CSS、图像和其他 .md 或 .html 文件。它们都在同一个文件夹中。

我在 StackOverflow 上发现了一个类似的线程（Airlfow 提供静态 html 目录）。我试图按照那里发布的解决方案进行操作，但它没有帮助。

我也在气流帮助论坛上发布了查询，但我还没有收到任何解决方案。我将不胜感激任何线索。谢谢你。

#Creating a flask appbuilder BaseView
class TestAppBuilderBaseView(AppBuilderBaseView):
    template_folder = '/home/airflow/airflow/plugins/test-project/site'

    @expose("/")
    def list(self):
        return self.render_template("index.html", content="")

v_appbuilder_view = TestAppBuilderBaseView()

v_appbuilder_package = {"name": "Test View",
                        "category": "Test Plugin",
                        "view": v_appbuilder_view}

插件类：

# Defining the plugin class
class AirflowTestPlugin(AirflowPlugin):
    name = "test_plugin"
    appbuilder_views = [v_appbuilder_package]

我正在 MKdocs 中开发文档，需要将一些脚本文件加载到我的 markdown 文件中。如何在markdown中添加js函数和脚本标签？

所以我的设置如下：

• 部署https://sub.domain.com/folder/在 Azure Blob 存储中的静态网站 (mkdocs) ，在 Kestrel 上运行。
• 在localhost:port没有子域和文件夹的情况下进行本地测试。
• <link rel="manifest" type="application/manifest+json" href="manifest.json" crossorigin="use-credentials">并且文件/folder/处于已部署状态，在本地测试中处于 root 状态。
• <script type="text/javascript" src="sw.js"></script>并且文件/folder/处于已部署状态，在本地测试中处于 root 状态。
• 清单中的 start_url 是/folder/.
• 在清单是图标路径assets/icons/icon.png，assets是/folder/在展开状态下，在局部测试根。

图标在本地工作，但在部署的站点上我得到：

Icon https://sub.domain.com/folder/assets/icons/icon.png failed to load

当我直接访问该 URL 时，文件加载得很好。

该站点位于身份验证之后，但我crossorigin="use-credentials"在加载清单时使用。

完整的 manifest.json：

{
    "short_name": "Site Hub",
    "name": "Site Hub",
    "start_url": "/docs/?utm_source=web_app_manifest",
    "icons": [
        {
            "src": "assets/icons/manifest-icon-192.png",
            "sizes": "192x192",
            "type": "image/png"
        },
        {
            "src": "assets/icons/manifest-icon-512.png", …

这个答案通过@joki到前面的问题表明，它可以通过给浏览的文物公开网址部署在GitLab回购来动态环境中的每个活跃的分支。

用mkdocs 材料项目尝试这个，我发现了两个问题。

首先，如果 GitLab 存储库在一个组或一个子组中，则.gitlab-ci.yml文件中的 URL需要更像这样：

    environment:
        name: review/$CI_COMMIT_REF_NAME
        url: "$CI_PAGES_URL/-/jobs/$CI_JOB_ID/artifacts/public/index.html"
        auto_stop_in: 1 week
    variables:
        PUBLIC_URL: "$CI_PAGES_URL/-/jobs/$CI_JOB_ID/artifacts/public/"

其次，网站内的相关链接不好用，导致404错误很多，样式文件等东西丢失。也许上面的网址是不正确的，或者也许是site_url在mkdocs.yml需要改变的东西，如：

site_url: !!python/object/apply:os.getenv ["CI_ENVIRONMENT_URL"]

然而，这些都不适合我。

可以在此处找到具有非常小的部署和审查应用程序的最小 MR 。

有没有人有 mkdocs 评论应用程序的工作配方？

mkdocs-material 主题中是否可以有类似这样的下拉菜单：

默认情况下，Material 主题似乎仅呈现标题下方的顶级菜单，子菜单位于左侧栏中。如果保留左侧栏，我就可以了。我只是想知道是否可以让子菜单显示为下拉菜单，如第一张图片所示。

为了更清楚：

我使用TBC MkDocs Gitlab-CI 模板来构建，然后发布一个静态站点，其中包含很多其他站点的链接。

所以我应该在我的 CI 工作中添加一个检查来验证：

1. 如果我所有的内部链接（网站内）都可以
2. 如果我所有的外部链接都有效。

您能给我一个建议，让我以一种好的方式做到这一点：

• 我可以使用什么工具？例如，我查看了本地链接的linkchecker-markdown和外部链接的linkchecker
• CI作业中如何实施检查？

我有一个包含表格的 markdown 文件，还有另一个 dbt schema.yml 文件，用于提供和生成文档。传统上，我在 schema.yml 中输入表名和列名以及列名的描述，但现在我想我想将 md 文档中的列名引用到 yaml 文件中，而不是手动输入。

这就是我的doc.md文件的样子

{% docs column_description %}

| COLUMN\_NAME                   | DESCRIPTION                                                               |
| ------------------------------ | ------------------------------------------------------------------------- |
| cycle\_id                      | Customer cycle\_id(todays start sleep time to next days start sleep time) |
| user\_id                       | Customers user\_id                                                        |
| yes\_alcohol                   | User consumed alcohol or not                                              |
| blank\_alcohol                 | User did not answer or user answered "No"                                 |
                    


{% enddocs %}

目前，这就是我的 schema.yml 文件的样子

version: 2

models: …

我正在尝试使用以下方法生成自动化文档：
mkdocs = "^1.4.2"
mkdocstrings = "0.19.0"
mkdocs-material = "8.5.8"
mkdocstrings-python = "0.7.1"

我的 mkdocs.yml 看起来像这样：

site_name: Optimization Services Documentation
site_url: "https://example.com"

theme:
  name: "material"
nav:
  - 'index.md'
  - 'reference.md'
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          setup_commands:
            - import sys
            - sys.path.append('../')
          selection:
            new_path_syntax: true

index.md 仍然是 mkdocs new 生成的默认文件。

Reference.md 看起来像这样：

# Reference
::: modelling.constraints

和 modelling.constraints.py：

def init_constraints(groupes_chantiers: list[GroupeChantiers],
                     digraph_precedence: nx.DiGraph,
                     graph_coactivite: nx.Graph,
                     model: cp_model.CpModel,
                     **kwargs) -> None:
    """
    Adds constraints to cp_model
    Args:
        groupes_chantiers: 
        digraph_precedence: 
        graph_coactivite: …