Display Your Markdown Documentation using DocuPanel

Introduction

When you develop an application, you also probably write a user manual or a documentation to explain how your software works. You have the possibility to store it on the internet or include it directly in your application. If you choose to integrate your documentation in your software, you will spend quite a lot of time to create a view and build a structure which displays correctly the help.

Fortunately for you, a tool exists and makes the job for you. DocuPanel is an open source project which integrates properly and quickly your Markdown documentation in your WPF application. It's a package that you can add to your application which browses your documentation files to index and analyze them in order to provide a UserControl you can add to your view.

This article aims to explain step by step how to add DocuPanel and how to make it work with your own documentation.

To have a better understanding of the project, you can read the documentation.

The source code is maintained on GitHub.

Prerequisites

• Install the NuGet DocuPanel.
• Modify the platform in your configuration manager to be x64.
• A documentation written in Markdown.

DocuPanel uses the Chromium Browser CefSharp, that is why your application has to be x64 and not Any CPU or x86. However, you can also download the source code and build it in x86.

Usage By An Example

Let's explain DocuPanel with an example. The source code of this example is also available on GitHub.

Step 1 - Add your Help Files in Your Project

• Create a directory in your project where you will store the markdown files.

  

  In our example, the directory is Documentation and our documentation files all the .md.

• You need to create an index file which contains all the information about how to organize your documentation. In our example, the index file is book.json, but you can call it whatever you want. The only obligation is that it must be of type json and placed at the root of your Documentation directory. I explain below how to organize this file.
• The files should have the following properties:

  

It is also possible to create a subdirectory so that you can organize your files the way you want, here we have created a folder Configuration which contains the configuration.md file.

It's really important that each file has a unique name.

Step 2 - Create Your index json File

In order to know the architecture of the documentation and how to display its pages, we need to create an index file which contains all this information.

The content of book.json for this example is the following code:

{
  "Title": "Documentation",
  "Author": "RHEA System S.A.",
  "PagePath": "home.md",
  "Sections": [
    {
      "Name": "Getting Started",
      "PagePath": "getting-started.md"
    },
    {
      "Name": "How does it work",      
      "Sections": [
        {
          "Name": "Searches",
          "PagePath": "searches.md"
        },
        {
          "Name": "Configuration",
          "Sections": [
            {
              "Name": "Configuration",
              "PagePath": "Configuration\\configuration.md"
            }
          ]
        }
      ],
      "PagePath": "how-does-it-work.md"
    },
    {
      "Name": "License",
      "PagePath": "license.md"
    },
    {
      "Name": "Support",
      "Sections":[],
      "PagePath": "support.md"
    }
  ]
}

The code gives the following hierarchy:

Let's explain the code:

In DocuPanel, each entity of the treeView is called a section. A section can be associated to the path of a Markdown file, in this case when the user will select this section, the page associated will be displayed. A section can contain other sections, here How does it work and Configuration contain subesctions, that is why they appear with a folder icon. In the Json file, the attribute Sections appears with the subsections inside.

The other sections appear with a green page because they only contain a page associated.

• Title is the title of your documentation.
• Author is the author of the documentation. Can be empty.
• PagePath is the relative path of the page associated to the section. Note that a section does not necessary contain PagePath. For example, a section can contain only children pages, it's what happens with Configuration in our example.
• Sections is the list of the subsections.
• Name is the name displayed by DocuPanel. It is possible to have two sections with the same name, in this example, we have two sections with the name Configuration.

The parameters Title and Author can be set only once because they give information about the whole documentation.

Each section has the parameters Name, Sections, PagePath. If a parameter is empty, you are not obligated to write it. In the previous code, we wrote "Sections":[] for the Support section, but we didn't write anything for the License section.

Step 3 - Add DocuPanel to Your View

Our example project contains a view which is a simple Window. To integrate DocuPanel, we add the following XAML code:

<docuPanel:DocumentationView 
PathDocumentationIndex="C:\Projects\DocuPanel\DocuPanelSupport\bin\x64\Debug\Documentation\book.json"
RootAppData="Users\<userName>\AppData\Local\<YourAppDataFolder>"
UpdateIndexation="true"/>

PathDocumentationIndex: Property of type string which corresponds to the path of the index file of your documentation. As I remember, it must be at the root of the doc.

RootAppData: Property of type string which corresponds to the path of the application data folder of your application. DocuPanel will create on this path a directory called DocuPanel to store its datas.

UpdateIndexation: Property of type bool which indicates whether the indexation needs to be updated.
If true, DocuPanel will browse all the files indicated in the index, and will convert them into HTML if they don't already exist. DocuPanel converts your Markdown files into HTML files to be displayed by CefSharp. The indexation for the searches will also be updated with the new documentation content. Note that if you want to update the content of a file, to consider the changes you have to delete the HTML file from the application data folder.

This property needs to be true the first time you use DocuPanel and each time you make changes in your documentation.

In the example, the properties are bound to a view-model to show how we can dynamically change the values using the pattern MVVM.

Conclusion

You should now see DocuPanel in your view, be able to browse the different pages and perform searches. I hope this tutorial has helped you to integrate this project to yours.

If you encountered some issues during this tutorial or during your utilization, let us know.

References

DocuPanel is used in the Concurrent Design Platform 4 and other projects of the RHEA GROUP.

The following tools are used in the project:

• CefSharp to display the pages
• Json.Net to deserialize the json index
• MarkdownDeep to convert the Markdown files into HTML files
• Lucene.Net to perform the searches
• ReactiveUI to improve the quality of the development

Points of Interest

DocuPanel is my first contribution to an open source project and I enjoyed developing the initial version. If you have any idea to improve it, your help is welcome. Feel free to contribute and don't hesitate to contact us or create a pull request.