I found out about js-sequence-diagrams, a javascript library that makes turning text into vector UML sequence diagrams very simple. I wanted to be able to add these diagrams into my MkDocs markdown file just by typing a block, like how one could do so in Typora.
我发现了js-sequence-diagrams这个JavaScript库，它使将文本转换为矢量UML序列图非常简单。 我希望能够仅通过键入一个块将这些图添加到我的MkDocs降价文件中，就像在Typora中可以做到的那样。
## Sample sequence diagramHere is a Hello World example.```uml-sequence-diagram
Title: Hello world example
Bob->Alice: Hello
Alice-->Bob: How are you?
Note left of Bob: Bob thinks
Bob->>Alice: I'm good, thanks! How about you?
Alice-->Bob: I'm doing great, thank you!
```The standard solution I found is to use SuperFences from PyMdown Extensions. They have an example of how to plug in UML diagrams with Mermaid. However, I prefer the look-and-feel of js-seqence-diagrams so I still had to keep searching.
我发现的标准解决方案是使用SuperFences从PyMdown扩展。 他们有一个有关如何使用Mermaid插入UML图的示例。 但是，我更喜欢js-seqence-diagrams的外观，因此我仍然必须继续搜索。
Luckily I came across an example by hahadaphne on GitHub. I forgot how I came across it — should probably be while digging through some issues in the PyMdown Extensions repo. The steps I’m outlining below modeled off from that example.
幸运的是，我在GitHub上遇到了hahadaphne的示例 。 我忘记了我是怎么遇到的-可能应该是在研究PyMdown扩展存储库中的一些问题时。 我在下面概述的步骤均基于该示例。
将js序列图添加到MkDocs的步骤 (Steps to add js-sequence-diagrams to MkDocs)
1.安装MkDocs和PyMdown扩展 (1. Install MkDocs and PyMdown Extensions)
pip install mkdocs
pip install markdown
pip install pymdown-extensions Further documentations can be found at the official MkDocs and PyMdown Extensions websites.
可以在MkDocs和PyMdown扩展官方网站上找到更多文档。
2.创建一个MkDocs项目 (2. Create an MkDocs project)
mkdocs new your-project-name
cd your-project-nameIf you have an existing MkDocs project you can also skip this step.
如果您有现有的MkDocs项目，也可以跳过此步骤。
3.添加一个JavaScript文件以解析markdown中的js-sequence-diagrams语法。 (3. Add a javascript file to parse the js-sequence-diagrams syntax in the markdown.)
I modified hahadaphne’s umlconvert.js to handle the html elements that have been changed. I also removed the portion of the codes that are not related to js-sequence-diagram (the original code also parses Mermaid and flowchart). These tweaks with the html elements might get regularly updated, so if you copy-pasted my code and it’s not working, then you should view your rendered document source code to find out what element names the browser is actually using.
我修改了hahadaphne的umlconvert.js，以处理已更改的html元素。 我还删除了与js-sequence-diagram不相关的部分代码(原始代码还解析了Mermaid和流程图 )。 这些与html元素有关的调整可能会定期更新，因此，如果您复制粘贴了我的代码，但该代码不起作用，则应查看呈现的文档源代码，以了解浏览器实际使用的元素名称。
Here are the two significant changes I made from hahadaphne’s code:
这是我从hahadaphne的代码中进行的两个重要更改：
convertUML to only convert
convertUML进行了重大修改，仅将具有相应类名的
<code> tags with the corresponding class name into diagrams.
<code>标记转换为图表。
4.编辑mkdocs.yml (4. Edit mkdocs.yml)
Add the required javascript files and markdown extensions into your mkdocs.yml.
将所需的javascript文件和markdown扩展名添加到您的mkdocs.yml中。
Note that I put my umlconvert.js in the docs/js folder. You can put your javascript file anywhere but don’t forget to list its source accordingly. Same with the file name, which doesn’t have to be umlconvert.js.
请注意，我将umlconvert.js放在docs / js文件夹中。 您可以将javascript文件放在任何地方，但是不要忘记列出其源代码。 与文件名相同，不必是umlconvert.js。
5.编辑markdown文件并生成文档 (5. Edit your markdown file and build your docs)
Now you can include the sequence diagram into your .md files with the js-sequence-diagrams’ syntax:
现在，您可以使用js-sequence-diagrams '语法将序列图包含到.md文件中：
```uml-sequence-diagramInsert text here```Then you can start your MkDocs server with the usual command.
然后，您可以使用通常的命令启动MkDocs服务器。
mkdocs serveYour docs should now spin up with the desired UML sequence diagrams!
您的文档现在应该使用所需的UML序列图了！
You can view the demo website here and its GitHub repository here. Let me know if you have questions and comments or found bugs in my code. Happy writing beautiful docs!
您可以查看演示网站在这里和它的GitHub储存库在这里 。 如果您有疑问和评论，或者在我的代码中发现错误，请告诉我。 快乐编写漂亮的文档！
翻译自: https://medium.com/swlh/using-js-sequence-diagrams-in-mkdocs-4eeb0cb2c238