如何让 GitHub Pages Markdown 支持美人鱼图？

Posted 2023-03-25

技术标签:

【中文标题】如何让 GitHub Pages Markdown 支持美人鱼图？【英文标题】：How to make GitHub Pages Markdown support mermaid diagram? 【发布时间】：2019-05-21 20:45:18 【问题描述】：

我希望在 GitHub 页面中使用美人鱼，只需简单的提交和推送。

换句话说，我希望像这样写在我的降价文件中

```mermaid
graph LR
   A --> B
   A -->C
   C -->D
```

并在我的 _layouts/post.html 上添加一些 js，以某种方式将其转换为美人鱼图。

我发现这个theme 声称它支持这样的事情。但是这个主题对我来说太重了，js太多了，所以我以为我只能用这个file，简直了

<script>
 window.Lazyload.js(' _sources.mermaid ', function() 
   mermaid.initialize(
     startOnLoad: true
   );
   mermaid.init(undefined, '.language-mermaid');
 );
</script>

在我的 _include/mermaid.html 中，我将 _sources.mermaid 替换为美人鱼 cdn

<script>
 window.Lazyload.js('https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js', function() 
   mermaid.initialize(
     startOnLoad: true
   );
   mermaid.init(undefined, '.language-mermaid');
 );
</script>

还是不行。在我的帖子中，它显示为常规代码块，而不是美人鱼图。

编辑：在 chrome 开发人员看来，我没有看到与链接 https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js 建立的任何连接。

我尝试了这段代码，在开发者视图中的network标签中建立了与美人鱼的连接，但美人鱼图仍然不起作用

<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js"></script>
<script>
var config = 
    startOnReady:true,
    theme: 'forest',
    flowchart:
            useMaxWidth:false,
            htmlLabels:true
        
;
mermaid.initialize(config);
mermaid.init(undefined, '.language-mermaid');
</script>

【问题讨论】：

【参考方案1】：

我找到了解决办法。

<!DOCTYPE html>
<html lang="en">
   <head>
	 <script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js"></script>
    </head>
	 
<body>
 <pre><code class="language-mermaid">graph LR
A--&gt;B
</code></pre>

<div class="mermaid">graph LR
A--&gt;B
</div>
	
</body>
<script>
var config = 
    startOnLoad:true,
    theme: 'forest',
    flowchart:
            useMaxWidth:false,
            htmlLabels:true
        
;
mermaid.initialize(config);
window.mermaid.init(undefined, document.querySelectorAll('.language-mermaid'));
</script>

</html>

【讨论】：

如何在 github 上运行 html 代码，我不认为这是可能的？您可以使用 GitHub Pages (pages.github.com) 将 GitHub 托管的 Markdown 文件呈现为 HTML 页面，这就是最初的问题。您可以添加自定义 javascript、CSS、HTML 等。【参考方案2】：

如果您使用 Jekyll，并且不介意使用插件，我认为以下内容可以帮助您更轻松地完成。

jekyll-spaceship - ? Jekyll 插件，为 table、mathjax、plantuml、mermaid、youtube、emoji、vimeo、dailymotion 等提供强大的支持。

https://github.com/jeffreytse/jekyll-spaceship

有两种方法可以在 Jekyll 博客页面中创建图表：

```mermaid!
pie title Pets adopted by volunteers
  "Dogs" : 386
  "Cats" : 85
  "Rats" : 35
```

或

@startmermaid
pie title Pets adopted by volunteers
  "Dogs" : 386
  "Cats" : 85
  "Rats" : 35
@endmermaid

上面的代码会被解析为：

【讨论】：

【参考方案3】：

我解决了它购买在浏览器中安装 Github Mermaid 扩展。实际上，它们支持 Chrome、Opera 和 Firefox。

我正在使用 Chrome：https://chrome.google.com/webstore/detail/github-%20-mermaid/goiiopgdnkogdbjmncgedmgpoajilohe?hl=en

【讨论】：

【参考方案4】：

二月。 2022：Markdown 页面支持 Mermaid (gist too)。正如Jegors Čemisovs 在the comments 中添加的那样，这不适用于GitHub 页面，如他的example site 所示。

见：

Include diagrams in your Markdown files with Mermaid

Mermaid 是一个基于 JavaScript 的图表和图表工具，它采用 Markdown 启发的文本定义并在浏览器中动态创建图表。由 Knut Sveidqvist 维护，它支持软件项目的许多不同的常见图表类型，包括流程图、UML、Git 图、用户旅程图，甚至是可怕的甘特图。

与 Knut 以及 CommonMark 的广大社区合作，我们推出了一项更改，允许您使用 Mermaid syntax 创建内联图表：

【讨论】：

GitHub 在 README.md 文件中显示它，但不会显示在生成的 GitHub 页面上。测试仓库：github.com/rabestro/test-mermaid 生成的GitHub页面站点：rabestro.github.io/test-mermaid @JegorsČemisovs 好点。我希望他们将支持扩展到 GitHub 生成的页面。 @JegorsČemisovs 我已将您的警告包含在答案中以提高知名度。【参考方案5】：

除了提到插件的其他答案。在我的公司工作表中，要求提供大多数支持的浏览器的扩展链接。

这是在浏览器级别呈现美人鱼的美人鱼扩展，我已经对它们进行了全部测试：

用于文档的美人鱼图当您使用 mermaid 在 Gitlab 中创建图表时，如果业务迁移到新的版本控制提供商（如 Github 或 Azure DevOps 或其他），在这种情况下，您需要安装浏览器插件才能查看图表。

Chrome -> GitHub + Mermaid Firefox -> GitHub + Mermaid Opera -> Extensions for Mermaid Edge -> Extensions for Mermaid

【讨论】：

【参考方案6】：

您尝试使用的网址不存在。这是一个正确的网址：

https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0/mermaid.min.js

【讨论】：

对不起，我更新了链接，结果还是不对。 @waterliu 是函数内部的代码在执行吗？对不起，我不知道那是什么意思……我对 js 知之甚少。我只能说这就是我帖子里的所有js了。没有其他 @waterliu 插入调试器命令；作为您给出的代码功能的第一个操作。打开浏览器的开发工具并加载页面。如果函数内部的代码被执行，那么你的代码应该直接跳入其中。在 Sources 选项卡的开发工具中检查您的 Javascript。刷新了吗？让我们continue this discussion in chat.【参考方案7】：

我遇到了类似的问题，最后只使用了一个自定义的 jekyll 插件。如果您能够使用自定义插件，以下将用元素替换美人鱼的降价代码块。

Jekyll::Hooks.register :posts, :pre_render do |post, payload|
  docExt = post.extname.tr('.', '')
  # only process if we deal with a markdown file
  if payload['site']['markdown_ext'].include? docExt
    newContent = post.content.gsub(/```mermaid([^`]+?)```/, '<div class="mermaid">\1</div>')
    post.content = newContent
  end
end

【讨论】：

【参考方案8】：

我假设这个要求是 Jekyll + Github Pages，因为提到了 Github Pages。

有插件可以做到这一点，例如jekyll-spaceship。它支持更多的渲染格式。

为了使 unsafe plugins 在 Github 页面上运行，您需要一个 Github 工作流操作 jekyll-deploy-action。

顺便说一句：自定义插件（将插件放在您的 _plugins 文件夹中）不适用于 Github Pages，它们不是 safe plugins。 Github Pages 将配置锁定到safe=true，甚至在本地。

【讨论】：

【参考方案9】：

新的最佳答案是 GitHub 现在直接支持在您的 Markdown 文件中使用 Mermaid 包含图表！

https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

【讨论】：

是的，这就是我在my own answer中提到的 GitHub 在 README.md 文件中显示它，但不会显示在生成的 GitHub 页面上。测试库：github.com/rabestro/test-mermaid