kevreed/docfx.plugins.plantuml

A DocFX plugin to render PlantUml diagrams from markdown code blocks

docfx.plugins.plantuml's Issues

PlantUml in metadata(

Is there a sample code for using PlantUml in metadata(Api documentation)Docfx?

it is like this image

For example, the following picture is another place that's means article menu no on metadat

@KevReed

PlantUml does not render diagram after build docfx

@KevReed
I had installed this plugin via nuget. by nuget install DocFx.Plugins.PlantUml -ExcludeVersion -OutputDirectory . command, after that I got this result after build docfx,
and I checked the index.html on localhost but It didn't work. I could not see plantuml diagram there was just plain text with box.
Could you find any problem?
I checked the <code class="lang-plantuml"> tag on builed html.

here is my environment.
macOS Sierra 10.12.6
NuGet Version: 4.7.0.5148
docfx Version: 2.38.1.0

[files]

(projectfolder)/docfx.json
(projectfolder)/plantuml.jar
(projectfolder)/DocFx.Plugins.PlantUml

[docfx.json]

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "**/**.cs"
          ],
          "src":"../localizedstring"
        }
      ],
      "dest": "api",
      "disableGitFeatures": false,
      "disableDefaultFilter": false
    }
  ],
  "build": {
    "content": [
      {
        "files": [
          "api/**.yml",
          "api/index.md"
        ]
      },
      {
        "files": [
          "articles/**.md",
          "articles/**/toc.yml",
          "toc.yml",
          "*.md"
        ]
      }
    ],
    "resource": [
      {
        "files": [
          "images/**"
        ]
      }
    ],
    "overwrite": [
      {
        "files": [
          "apidoc/**.md"
        ],
        "exclude": [
          "obj/**",
          "_site/**"
        ]
      }
    ],
    "dest": "_site",
    "globalMetadataFiles": [],
    "fileMetadataFiles": [],
    "template": [
        "default",
        "DocFx.Plugins.PlantUml/template"
    ],
    "postProcessors": [],
    "markdownEngineName": "markdig",
    "markdownEngineProperties": {
        "plantUml.renderingMode":"local"
    },
    "noLangKeyword": false,
    "keepFileLink": false,
    "cleanupCacheHistory": false,
    "disableGitFeatures": false
  }
}

[intro.md]

# Add your introductions here!
'''plantuml
IntroBob -> IntroAlice : intro
Alice -> Bob : Go Away
''' // this is not (') I inserted(`)

[docfx build]

➜  docfx_project docfx --serve
[18-10-23 05:20:56.495]Info:Config file docfx.json found, start generating metadata...
[18-10-23 05:20:56.794]Info:[MetadataCommand.ExtractMetadata]Loading projects...
[18-10-23 05:20:56.838]Info:[MetadataCommand.ExtractMetadata]'/Users/seonmyeong.kim/KSM/plantumltest/localizedstring/LocalizedString/FlatBuffers/ByteBuffer.cs,/Users/seonmyeong.kim/KSM/plantumltest/localizedstring/LocalizedString/FlatBuffers/FlatBufferBuilder.cs,/Users/seonmyeong.kim/KSM/plantumltest/localizedstring/LocalizedString/FlatBuffers/FlatBufferConstants.cs,/Users/seonmyeong.kim/KSM/plantumltest/localizedstring/LocalizedString/FlatBuffers/Struct.cs,/Users/seonmyeong.kim/KSM/plantumltest/localizedstring/LocalizedString/FlatBuffers/Table.cs,/Users/seonmyeong.kim/KSM/plantumltest/localizedstring/LocalizedString/FlatBuffersIDLClass/LocalizedStringData.cs,/Users/seonmyeong.kim/KSM/plantumltest/localizedstring/LocalizedString/FlatBuffersIDLClass/LocalizedStringDataEntry.cs,/Users/seonmyeong.kim/KSM/plantumltest/localizedstring/LocalizedString/Loader/StringLoader.cs' keep up-to-date since '2018/10/23 5:13:47', cached result from '/Users/seonmyeong.kim/KSM/plantumltest/docfx_project/api' is used.
[18-10-23 05:20:56.846]Info:[MetadataCommand]Completed Scope:MetadataCommand in 244.8242 milliseconds.
[18-10-23 05:20:56.895]Info:[BuildCommand]Plug-in directory: /usr/local/Cellar/docfx/2.38.1/libexec/plugins_sqtdx5e4.7jy/plugins, configuration file: /usr/local/Cellar/docfx/2.38.1/libexec/plugins_sqtdx5e4.7jy/plugins/docfx.plugins.config
[18-10-23 05:20:57.316]Info:[ImportPlugins]Searching custom plugins in directory /usr/local/Cellar/docfx/2.38.1/libexec/plugins_sqtdx5e4.7jy/plugins...
[18-10-23 05:20:57.319]Warning:[ImportPlugins]Skipping file /usr/local/Cellar/docfx/2.38.1/libexec/plugins_sqtdx5e4.7jy/plugins/System.Net.Http.dll due to load failure: Could not load file or assembly 'System.Net.Http' or one of its dependencies
[18-10-23 05:20:57.471]Info:6 plug-in(s) loaded.
[18-10-23 05:20:57.594]Info:No files are found with glob pattern apidoc/**.md, excluding obj/**,_site/**, under directory "/Users/seonmyeong.kim/KSM/plantumltest/docfx_project"
[18-10-23 05:20:57.596]Info:No files are found with glob pattern images/**, excluding <none>, under directory "/Users/seonmyeong.kim/KSM/plantumltest/docfx_project"
[18-10-23 05:20:57.606]Info:Markdown engine is markdig
[18-10-23 05:20:58.032]Info:[BuildCore.Build Document]Max parallelism is 8.
[18-10-23 05:20:58.100]Info:[BuildCore.Build Document.Prepare.CreateIncrementalBuildContext]Build strategy: IsIncrementalBuild
[18-10-23 05:20:58.414]Info:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ManagedReferenceDocumentProcessor]Building 0 file(s) in ManagedReferenceDocumentProcessor(BuildManagedReferenceDocument=>ValidateManagedReferenceDocumentMetadata=>ApplyOverwriteDocumentForMref=>FillReferenceInformation)...
[18-10-23 05:20:58.415]Info:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.ConceptualDocumentProcessor]Building 0 file(s) in ConceptualDocumentProcessor(BuildConceptualDocument=>CountWord=>ValidateConceptualDocumentMetadata)...
[18-10-23 05:20:58.415]Info:[BuildCore.Build Document.CompilePhaseHandlerWithIncremental.TocDocumentProcessor]Building 3 file(s) in TocDocumentProcessor(BuildTocDocument)...
[18-10-23 05:20:58.663]Info:[BuildCore.Build Document.LinkPhaseHandlerWithIncremental.UpdateContext]0 external references found in 1 xref maps.
[18-10-23 05:20:58.737]Info:[BuildCore.Build Document.LinkPhaseHandlerWithIncremental.Apply Templates]Applying templates to 3 model(s)...
[18-10-23 05:20:59.000]Info:[BuildCore.Build Document]XRef map exported.
[18-10-23 05:20:59.101]Info:[Postprocess]Manifest file saved to manifest.json.
[18-10-23 05:20:59.130]Info:Completed building documents in 1653.1787 milliseconds.
[18-10-23 05:20:59.181]Info:[BuildCommand]Cleaning up temporary plugin folder "/usr/local/Cellar/docfx/2.38.1/libexec/plugins_sqtdx5e4.7jy"
Serving "/Users/seonmyeong.kim/KSM/plantumltest/docfx_project/_site" on http://localhost:8080

[intro.html]

      <div role="main" class="container body-content hide-when-search">
        
        <div class="sidenav hide-when-search">
          <a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
          <div class="sidetoggle collapse" id="sidetoggle">
            <div id="sidetoc"></div>
          </div>
        </div>
        <div class="article row grid-right">
          <div class="col-md-10">
            <article class="content wrap" id="_content" data-uid="">
<h1 id="add-your-introductions-here">Add your introductions here!</h1>

<pre><code class="lang-plantuml">IntroBob -&gt; IntroAlice : intro
Alice -&gt; Bob : Go Away
</code></pre>
</article>
          </div>
          
          <div class="hidden-sm col-md-2" role="complementary">
            <div class="sideaffix">
              <div class="contribution">
                <ul class="nav">
                </ul>
              </div>
              <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
              <!-- <p><a class="back-to-top" href="#top">Back to top</a><p> -->
              </nav>
            </div>
          </div>
        </div>
      </div>

Support code inclusion blocks

When using a code inclusion directive a warning is generated that the content type is unsupported.
The raw plantUml source appears in the generated documentation where the rendered diagram should appear.

For example, the directive

[!code-plantUml[cool](cool.wsd "cool")]

results in the log warning

[18-06-06 09:41:58.906]Warning:[UnknownContentType]Unable to handle following files: cool.wsd

The plantUml source appears as a preformatted block in the generated documentation

relative Path for plantuml.jar does not work in local build mode

When I use default(remote) build mode it works perfectly fine but in local I get an Error:
Unable to access jarfile DocFx.Plugins.PlantUml/plantuml.jar
Also Building local with setting an absolut Path works fine. I guess it thinks the relative path is absolute and cant find the file.

My docfx.json

...

"markdownEngineProperties": {
"plantUml.javaPath": "C:/Program Files/Java/jre-10.0.1/bin/java.exe",
"plantUml.localGraphvizDotPath": "C:/Program Files (x86)/Graphviz2.38/bin/dot.exe",
"plantUml.localPlantUmlPath": "DocFx.Plugins.PlantUml/plantuml.jar",
"plantUml.renderingMode":"local"
}
...


Support .Net core

Plugin scanning during docfx execution visits file "DocFx.Plugins.PlantUml.dll" but does not seem to recognize it as a docfx plugin. My guess is because the assembly is not .Net core compatible.

[Feature Request] Support Links to reference Uids

Basicly the title: it would be awesome if there would be a way to reference to other Pages via Uid like in DFM. Maybe there is already a way since plantUml already features links but I couldnt find one except for inserting the full link of the later address.
Thank you for your really great plugin!

BUG: The Plugin is not working with latest docfx Version

After the update to latest docfx the plugin do not render the plantuml within the markdown files.
They are just shown as code block.

We are using the configuration with external plantuml server.

Out last version of docfx was 1.52.x, the planuml where rendered corrctly.
With the update to 1.62.x it is not working any more.

Is there a way to get it back to work with the latest docfx?

Can't generate the graph

Unfortunately it is not working and here is the re-producing steps.

1. create a new folder
2. type choco install docfx -y and hit Enter (Installed DocFx through chocolatey)
3. type docfx init -q and hit Enter
4. type cd docfx_project and hit Enter
5. type nuget install DocFx.Plugins.PlantUml -ExcludeVersion -OutputDirectory . and hit Enter
6. in docfx.json change the part

   	"template": [
   		"default"
   	],
   

   as

   	"template": [
   		"default",
   		"DocFx.Plugins.PlantUml/template"
   	],
   

7. in articles/intro.md add the following part to the bottom

   ```plantUml
   Bob->Alice : hello
   ```
   

8. type docfx docfx.json --serve and hit Enter
9. wait until you see Serving "C:\Users..\docfx_project_site" on http://localhost:8080
10. open your browser and go to http://localhost:8080/articles/intro.html
11. You will not see the graphic you are supposed to see instead you will see a code block

[Bug] Docfx build error with the latest version

When using the docfx command after following the Manual Installation instructions provided, it gives the following error.

Build failed.
[22-09-26 09:57:03.415]Error:System.IO.FileLoadException: Could not load file or assembly 'System.Memory, Version=4.0.1.1, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)
File name: 'System.Memory, Version=4.0.1.1, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51'
   at System.Signature.GetSignature(Void* pCorSig, Int32 cCorSig, RuntimeFieldHandleInternal fieldHandle, IRuntimeMethodInfo methodHandle, RuntimeType declaringType)
   at System.Reflection.RuntimeMethodInfo.FetchNonReturnParameters()
   at System.Reflection.RuntimeMethodInfo.GetParameters()
   at Newtonsoft.Json.Serialization.DefaultContractResolver.GetCallbackMethodsForType(Type type, List`1& onSerializing, List`1& onSerialized, List`1& onDeserializing, List`1& onDeserialized, List`1& onError)
   at Newtonsoft.Json.Serialization.DefaultContractResolver.ResolveCallbackMethods(JsonContract contract, Type t)
   at Newtonsoft.Json.Serialization.DefaultContractResolver.CreateArrayContract(Type objectType)
   at System.Collections.Concurrent.ConcurrentDictionary`2.GetOrAdd(TKey key, Func`2 valueFactory)
   at Newtonsoft.Json.Serialization.DefaultContractResolver.ResolveContract(Type type)
   at Newtonsoft.Json.Serialization.JsonSerializerInternalWriter.CalculatePropertyValues(JsonWriter writer, Object value, JsonContainerContract contract, JsonProperty member, JsonProperty property, JsonContract& memberContract, Object& memberValue)
   at Newtonsoft.Json.Serialization.JsonSerializerInternalWriter.SerializeObject(JsonWriter writer, Object value, JsonObjectContract contract, JsonProperty member, JsonContainerContract collectionContract, JsonProperty containerProperty)
   at Newtonsoft.Json.Serialization.JsonSerializerInternalWriter.Serialize(JsonWriter jsonWriter, Object value, Type objectType)
   at Newtonsoft.Json.JsonSerializer.SerializeInternal(JsonWriter jsonWriter, Object value, Type objectType)
   at Newtonsoft.Json.JsonConvert.SerializeObjectInternal(Object value, Type type, JsonSerializer jsonSerializer)
   at Microsoft.DocAsCode.Build.Engine.Incrementals.IncrementalBuildContext.ComputeConfigHash(DocumentBuildParameters parameter, String markdownServiceContextHash)
   at Microsoft.DocAsCode.Build.Engine.Incrementals.IncrementalBuildContext.Create(DocumentBuildParameters parameters, BuildInfo cb, BuildInfo lb, String intermediateFolder, String markdownServiceContextHash)
   at Microsoft.DocAsCode.Build.Engine.SingleDocumentBuilder.Prepare(DocumentBuildParameters parameters, DocumentBuildContext context, TemplateProcessor templateProcessor, String markdownServiceContextHash, IHostServiceCreator& hostServiceCreator, PhaseProcessor& phaseProcessor)
   at Microsoft.DocAsCode.Build.Engine.SingleDocumentBuilder.BuildCore(DocumentBuildParameters parameters)
   at Microsoft.DocAsCode.Build.Engine.SingleDocumentBuilder.Build(DocumentBuildParameters parameters)
   at Microsoft.DocAsCode.Build.Engine.DocumentBuilder.BuildCore(DocumentBuildParameters parameter, IMarkdownServiceProvider markdownServiceProvider, BuildInfo currentBuildInfo, BuildInfo lastBuildInfo)
   at Microsoft.DocAsCode.Build.Engine.DocumentBuilder.Build(IList`1 parameters, String outputDirectory)
   at Microsoft.DocAsCode.SubCommands.DocumentBuilderWrapper.BuildDocument(BuildJsonConfig config, TemplateManager templateManager, String baseDirectory, String outputDirectory, String pluginDirectory, String templateDirectory)
   at Microsoft.DocAsCode.SubCommands.DocumentBuilderWrapper.BuildDocument()

WRN: Assembly binding logging is turned OFF.
To enable assembly bind failure logging, set the registry value [HKLM\Software\Microsoft\Fusion!EnableLog] (DWORD) to 1.
Note: There is some performance penalty associated with assembly bind failure logging.
To turn this feature off, remove the registry value [HKLM\Software\Microsoft\Fusion!EnableLog].

        0 Warning(s)
        1 Error(s)

Docfx version used I am using.

docfx --version
docfx 2.59.4.0
Copyright (C) 2022 c Microsoft Corporation. All rights reserved.
This is open-source software under MIT License.

Steps to reproduce

docfx init -q
cd ./docfx_project
nuget install DocFx.Plugins.PlantUml -ExcludeVersion -OutputDirectory .

Add the template to docfx.json as shown in the readme

...
    "template": [
      "default",
      "DocFx.Plugins.PlantUml/template"
    ]
...

And then run docfx, which will give the above error I have provided.