search

dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
3.96k stars 846 forks source link

Addin for diagrams support #2292

Closed pascalberger closed 1 year ago

pascalberger commented 6 years ago

An addin which adds support for writing diagrams would be nice (e.g. by using mermaid)

ChristophLindemann commented 6 years ago

Duplicate of #2347

pascalberger commented 6 years ago

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).

sandorfr commented 6 years ago

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 image

image

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).

sandorfr commented 6 years ago

I've added support for https://www.graphviz.org/ to my branch.

sandorfr commented 6 years ago

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"
    ],
devLucius commented 6 years ago

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!

sandorfr commented 6 years ago

@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:

Zenith-Convoy commented 5 years ago

A little legwork but you can edit the HTML after running DocFX to add Mermaid diagrams. Manual method to add Mermaid flow charts

  1. Created a markdown file in StackEdit.io with Mermaid Flow Chart Diagrams.
  2. Exported the markdown and put it in the article directory; updated toc.
  3. Run DocFX
  4. Exported the markdown file from StackEdit.io as a styled HTML file. (This displays the diagram correctly.)
  5. Opened the downloaded styled HTML file and docfx/_site's version in NotePadd++.
  6. Copied <link rel="stylesheet" href="https://stackedit.io/style.css" /> into the docFX version's <head> tag.
  7. Found the code for the diagram in the StackEdit.io version and copied that to the corresponding location.
  8. 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.
  9. 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.

NormandErwan commented 5 years ago

@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'
sandorfr commented 5 years ago

Because you are not fetching from the right source --> https://www.myget.org/F/gl-unstable/api/v3/index.json

NormandErwan commented 5 years ago

Thank you, you already explained this above, I haven't caught it.

You should consider writing a quick README on your repo !

EurekaChen commented 4 years ago

Simple add mermaid for docfx as:

  1. add mermaid.min.js to your docfx template
  2. 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.

Logerfo commented 4 years ago

@sandorfr Just tried your plugins, but:

Error:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ConceptualDocumentProcessor.Build.BuildConceptualDocument](<MYFILE>)Markup failed: System cannot find the file specified (translated)

sandorfr commented 4 years ago

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.

sachabruttin commented 4 years ago

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/mermaid@8.4/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
```
huguesr commented 4 years ago

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:

  1. I create a mytemplate folder
  2. I create a partials folder in my template one.
  3. I create a file named scripts.tmpl.partial
  4. I put your code in it
  5. I updated the docfx.json file "template": ["default","mytemplate"],
  6. I launched docfx
  7. 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.

huguesr commented 4 years ago

I found the solution. You have to add the following lines at the begining of the code

Corji commented 4 years ago

@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.

christianlegault commented 4 years ago

A simplified version of @sachabruttin solution with the latest version of mermaid.min.js.

<script type="text/javascript" src="https://unpkg.com/mermaid@8.5.2/dist/mermaid.min.js"
        integrity="sha384-dV0RNdYNgPqjamYrB83Q21NNeuYk1jpKyUBkKQrT+c7krNFk4k39ktYZV4mOdMV1"
        crossorigin="anonymous"></script>
<script>
    mermaid.initialize({
        startOnLoad: false
    });
    mermaid.init(undefined, ".lang-mermaid");
</script>
KalleOlaviNiemitalo commented 4 years ago

Could add Subresource Integrity to the script tag. https://unpkg.com/mermaid@8.5.2/dist/mermaid.min.js?meta shows a hash.

AlexHedley commented 3 years ago

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

neeraj9 commented 2 years ago

Will this be available anytime soon?

AlexHedley commented 2 years ago

GitHub adds support

Include diagrams in your Markdown files with Mermaid

webprofusion-chrisc commented 2 years ago

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.

jldubz commented 2 years ago

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/mermaid@9.1.3/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.

timstokman commented 2 years ago

@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" />

jldubz commented 2 years ago

@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?

timstokman commented 2 years ago

@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/mermaid@9.1.3/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.

timstokman commented 1 year ago

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.

  • © Githubissues.
  • Githubissues is a development platform for aggregating issues.