docfx
docfx copied to clipboard
dotnet
Addin for diagrams support
Not necessary a duplicate as #2347 explicitely asks for PlantUML support, which requires additional infrastructure and therefore might not be suitable for every situation. I can also live with any JS implementation (like e.g. the mentioned mermaid).
I'm in desperate need for that so I'm working on a mermaid renderer plugin. I have a working proof of concept (source code)
I'm pretty happy with the experience it give in combination with vs code and that mermaid plugin
Beside code quality (this is a quick and dirty poc) I'd like to provide a bit of options like give the control over rendering parameter somewhere in the docfx.json file (which would translate as additional mermaid arguments). If anyone has a bit experience with docfx and can point me on the right direction I'd love that.
[Solved] ~~In addition I couldn't make it work with pdf generation (see #2427).~~
If anyone is interested in giving feedback or anything, I've made the packages available here: https://www.myget.org/F/gl-unstable/api/v3/index.json
you need to install mermaid cli and graphviz
nuget install mermaid.renderer -OutputDirectory <Output>
nuget install graphviz.renderer -OutputDirectory <Output>
"template": [
"default",
"<Output>/mermaid.renderer.1.0.0/content",
"<Output>/graphviz.renderer.1.0.0/content"
],
Hi! I would like to test your plugin but i need some instruction how to install it on my setup. I am using Windows 10 with VS2017. Thanks!
@devLucius
As mentionned above you need to install the prerequisities (mermaid cli and graphviz).
Then the steps are the same as with an other plugins, except for the source which is from another feed which you'll need to register first ( https://docs.microsoft.com/en-us/nuget/tools/cli-ref-sources ).
In addition, I'd highly recommand using Visual Studio Code instead as you will have the live preview for both mermaid and graphviz with those vs code plugins:
- https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid
- https://marketplace.visualstudio.com/items?itemName=geeklearningio.graphviz-markdown-preview
A little legwork but you can edit the HTML after running DocFX to add Mermaid diagrams. Manual method to add Mermaid flow charts
- Created a markdown file in StackEdit.io with Mermaid Flow Chart Diagrams.
- Exported the markdown and put it in the article directory; updated toc.
- Run DocFX
- Exported the markdown file from StackEdit.io as a styled HTML file. (This displays the diagram correctly.)
- Opened the downloaded styled HTML file and docfx/_site's version in NotePadd++.
- Copied
<link rel="stylesheet" href="https://stackedit.io/style.css" />into the docFX version's<head>tag. - Found the code for the diagram in the StackEdit.io version and copied that to the corresponding location.
- The diagram boxes' label text was small and white (done by DocFX overriding its style), so I replaced all
class="label"with nothing, to delete that class. -
docfx.exe serve _site; open localhost in a browser; Now Works!
Just figured this out and haven't tried to optimise this process. Hopefully, it can provide some insight for automation or at least provide a temporary solution to add handcrafted Mermaid Flow Charts (haven't tested Gantt or sequence).
However, you will have to do this every time you rebuild or store that page separately. In my case it was an article, so I didn't have too much of a problem but the API Documentation doesn't really integrate well.
It would be really cool if DocFx automatically created these kinds of diagrams; that can show class relation/dependency, business logic, and more. Is that what you asked for, @pascalberger?
@sandorfr, I noticed your version displayed the diagram item labels with white text, which isn't easy to read. docfx.vendor.css line 1086 .label{display:inline;padding:.2em .6em .3em;font-size:75%;color:#fff;border-radius:.25em} was what was changing my labels, that was fixed by removing class="label" from the HTML file.
@sandorfr I tried to install your plugin, without success:
nuget install mermaid.renderer -OutputDirectory Documentation/Plugins/
Feeds used:
https://api.nuget.org/v3/index.json
C:\Program Files (x86)\Microsoft SDKs\NuGetPackages\
Installing package 'mermaid.renderer' to 'Documentation/Plugins/'.
GET https://api.nuget.org/v3/registration3-gz-semver2/mermaid.renderer/index.json
NotFound https://api.nuget.org/v3/registration3-gz-semver2/mermaid.renderer/index.json 506ms
Unable to find package 'mermaid.renderer'
Because you are not fetching from the right source --> https://www.myget.org/F/gl-unstable/api/v3/index.json
Thank you, you already explained this above, I haven't caught it.
You should consider writing a quick README on your repo !
Simple add mermaid for docfx as:
- add mermaid.min.js to your docfx template
- Edit article file just add
<div class="mermaid">
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
</div>
now render page using docfx and graph appear.
@sandorfr Just tried your plugins, but:
Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ConceptualDocumentProcessor.Build.BuildConceptualDocument](<MYFILE>)Markup failed: System cannot find the file specified(translated)
I guess it’s because mermaid cli has been renamed. I have not really had much time to spend on this since POC. Docfx being in limbo between .net core and .net, I’m not keen to invest time on it.
You can use mermaid API to resolve this issue.
Add this to your docfx template. I do it on scripts.tmpl.partial.
<!-- mermaid support -->
<script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({
startOnLoad: false
});
window.onload = function () {
const elements = document.getElementsByClassName("lang-mermaid");
let index = 0;
while (elements.length != 0) {
let element = elements[0];
mermaid.render('graph'+index, element.innerText, (svgGraph) => {
element.parentElement.outerHTML = "<div class='mermaid'>" + svgGraph + "</div>";
});
++index;
}
}
</script>
Then on your md file, you can use normal markdown markup to define a graph.
This should display 2 graph generated by mermaidjs
``` mermaid
graph LR
A -- text --> B -- text2 --> C
```
``` mermaid
sequenceDiagram
Alice->John: Hello John, how are you?
Note over Alice,John: A typical interaction
```
Hello @sachabruttin , Your solution works well to display mermaid design. This is fantastic. However, as soon as I add your partial script part to the default template the navigation bar in top of the screen disappear. I'm new on docfx (started yesterday) and I don't know why. Here is what I did:
- I create a mytemplate folder
- I create a partials folder in my template one.
- I create a file named scripts.tmpl.partial
- I put your code in it
- I updated the docfx.json file "template": ["default","mytemplate"],
- I launched docfx
- I launched docfx serve _site
When I reach the first page, I do not have the navigation part on top of the screen. I should have "Article", "Tutorials", etc. If I open the page where I put the mermaid design (by entering the url) it appears well
Any idea what I did wrong?
Addendum: I try to reduce the file to just and I still have the issue.
Thank you.
I found the solution. You have to add the following lines at the begining of the code
@sachabruttin Im able to work with you approach for the html side. For the pdf it doesn't seems to work. I did exactly the same for the pdf as i did for the html site.
A simplified version of @sachabruttin solution with the latest version of mermaid.min.js.
<script type="text/javascript" src="https://unpkg.com/[email protected]/dist/mermaid.min.js"
integrity="sha384-dV0RNdYNgPqjamYrB83Q21NNeuYk1jpKyUBkKQrT+c7krNFk4k39ktYZV4mOdMV1"
crossorigin="anonymous"></script>
<script>
mermaid.initialize({
startOnLoad: false
});
mermaid.init(undefined, ".lang-mermaid");
</script>
Could add Subresource Integrity to the script tag. https://unpkg.com/[email protected]/dist/mermaid.min.js?meta shows a hash.
Interesting thread:
https://twitter.com/bradygaster/status/1375147944760930305
https://fluidframework.com/docs/advanced/summarizer/
Fluid uses Mermaid in their docs, with accessibility addressed:
https://github.com/tylerbutler/FluidFramework/commit/2597379ae57b5a01aee33fff9482d64ae1212c01#diff-cf2a02b7ba760f1160fc918b8f2b175dad122a4fd64790689e7cf6e3b9ed0fed
Just in case this feature is being de-proritized due to not appearing relevant, Microsoft have themselves demonstrated a requirement for diagram support. In particular if you look at https://docs.microsoft.com/en-us/aspnet/core/blazor/components/lifecycle?view=aspnetcore-6.0 there is clearly a need to be able to show lifecycle flowcharts etc without resorting to slightly-skewed (scanned?) images etc which are then hard to update.
I had a need to add this in. Just like everyone else is saying - markdown diagram support is quickly becoming a standard and mermaid is a top contender.
Here is the content of templates/mermaid/partials/scripts.tmpl.partial to use Mermaid v9.1.3.
<!-- Required styles -->
<script type="text/javascript"
src="{{_rel}}styles/docfx.vendor.js"></script>
<script type="text/javascript"
src="{{_rel}}styles/docfx.js"></script>
<script type="text/javascript"
src="{{_rel}}styles/main.js"></script>
<!-- Load v9.1.3 of Mermaid -->
<!-- Hash obtained via https://www.srihash.org/ -->
<script type="text/javascript"
src="https://unpkg.com/[email protected]/dist/mermaid.min.js"
integrity="sha384-LnGjpNDrP4cp7MIk4CpRa/lPNclrf839ryYVFx1T1mPSV3RGAZ7nlBa7pqcyGY/K"
crossorigin="anonymous"></script>
<!-- Initialize Mermaid -->
<script>
mermaid.initialize({
startOnLoad: false
});
mermaid.init(undefined, ".lang-mermaid");
</script>
PS don't forget to add "templates/mermaid" to the templates section of your docfx.json file.
@jldubz That works, but you also need font-awesome to get icons working: https://mermaid-js.github.io/mermaid/#/flowchart?id=basic-support-for-fontawesome
Adding this is sufficient:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.2/css/all.min.css" />
@timstokman
Adding this is sufficient:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.2/css/all.min.css" />
Can you provide a full example of where this line is being added (full file path and file content is optimal) to avoid any confusion?
@jldubz This is my scripts.tmpl.partial file:
<!-- Required styles -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.2/css/all.min.css" />
<script type="text/javascript"
src="{{_rel}}styles/docfx.vendor.js"></script>
<script type="text/javascript"
src="{{_rel}}styles/docfx.js"></script>
<script type="text/javascript"
src="{{_rel}}styles/main.js"></script>
<!-- Load v9.1.3 of Mermaid -->
<!-- Hash obtained via https://www.srihash.org/ -->
<script type="text/javascript"
src="https://unpkg.com/[email protected]/dist/mermaid.min.js"
integrity="sha384-LnGjpNDrP4cp7MIk4CpRa/lPNclrf839ryYVFx1T1mPSV3RGAZ7nlBa7pqcyGY/K"
crossorigin="anonymous"></script>
<!-- Initialize Mermaid -->
<script>
mermaid.initialize({
startOnLoad: false
});
mermaid.init(undefined, ".lang-mermaid");
</script>
Without font-awesome included, the mermaid icon functionality doesn't work.
So at some point this template stopped working for me. Took me a bit to find out why.
If you have multiple templates, like here, the latest scripts.tmpl.partial overwrites the one from the main template. So including mermaid like this will break the main template (which broke about everything for me). You'll need to include the main template's scripts.tmpl.partial, like this:
<!-- Required styles -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css" />
<script type="text/javascript" src="{{_rel}}styles/docfx.vendor.js"></script>
<script type="text/javascript" src="{{_rel}}styles/docfx.js"></script>
<script type="text/javascript" src="{{_rel}}styles/main.js"></script>
<!-- Load Mermaid -->
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<!-- Initialize Mermaid -->
<script>
mermaid.initialize({
startOnLoad: false
});
mermaid.init(undefined, ".lang-mermaid");
</script>
<script type="text/javascript" src="{{_rel}}styles/docfx.vendor.min.js"></script>
<script type="text/javascript" src="{{_rel}}styles/docfx.js"></script>
<script type="text/javascript" src="{{_rel}}styles/main.js"></script>
Bit of a hack, but it works. Might be nice if there was better support for stuff like this in docfx.