PSC.Blazor.Components.MarkdownEditor 8.0.2

Blazor Markdown Editor

This is a Markdown Editor component for Blazor WebAssembly and Blazor Server with .NET8. The component is based on EasyMDE version 1.0.x to create the editor. I decided to create my repository for the JavaScript library because I wanted to have control over the updates and the changes. The component is a wrapper around the JavaScript library and it is a Blazor component that allows you to use the Markdown Editor in your Blazor application.

For more documentation and help this component, visit the post I created here.

Try Markdown Editor online (upload is not enabled)

Usage

Add the Editor to your _Imports.razor

@using PSC.Blazor.Components.MarkdownEditor 
@using PSC.Blazor.Components.MarkdownEditor.EventsArgs

Then, in your index.html or host.html add those lines:

<link href="/_content/PSC.Blazor.Components.MarkdownEditor/css/easymde.min.css" rel="stylesheet" />

<script src="/_content/PSC.Blazor.Components.MarkdownEditor/js/easymde.min.js"></script>
<script src="/_content/PSC.Blazor.Components.MarkdownEditor/js/markdownEditor.js"></script>

Remember that jQuery is also required. The component contains the Easy Markdown Editor script version 1.0.x that is also maintain by myself. You can add this script in your project but if you use the script in the component, you are sure it works fine and all functionalities are tested.

Add MarkdownEditor in a page

In a Razor page, we can add the component with these lines

<div class="col-md-12">
    <MarkdownEditor @bind-Value="@markdownValue" 
                    ValueHTMLChanged="@OnMarkdownValueHTMLChanged" />

    <hr />

    <h3>Result</h3>
    @((MarkupString)markdownHtml)
</div>

@code {
    string markdownValue = "#Markdown Editor\nThis is a test";
    string markdownHtml;

    Task OnMarkdownValueChanged(string value)
    {
        return Task.CompletedTask;
    }

    Task OnMarkdownValueHTMLChanged(string value)
    {
        markdownHtml = value;
        return Task.CompletedTask;
    }
}

The main different between value and ValueHTMLChanged is that Value return the text written in the editor as a string whereas ValueHTMLChanged returns the rendered HTML code for the text. The ValueHTMLChanged includes the code for displaying mermaid graphs in a SVG tag.

The result is a nice Markdown Editor like in the following screenshot. This is a screenshot from the demo in this repository.

Add a custom toolbar

In your Markdown Editor add the following code

<MarkdownEditor @bind-Value="@markdownValue"
                ValueHTMLChanged="@OnMarkdownValueHTMLChanged"
                SpellChecker="false"
                CustomButtonClicked="@OnCustomButtonClicked">
    <Toolbar>
        <MarkdownToolbarButton Action="MarkdownAction.Bold" Icon="fa fa-bolt" Title="Bold" />
        <MarkdownToolbarButton Separator Name="Custom button" 
                               Value="@("Hello from your custom Toolbar Button")" 
                               Icon="fa fa-star" 
                               Title="A Custom Button" />
        <MarkdownToolbarButton Separator Name="https://github.com/erossini/BlazorMarkdownEditor" 
                               Icon="fa fab fa-github" Title="A Custom Link" />
    </Toolbar>
</MarkdownEditor>

@code {
    // omitted code...

    Task OnCustomButtonClicked(MarkdownButtonEventArgs eventArgs)
    {
        Console.WriteLine("OnCustomButtonClicked -> " + eventArgs.Value);
        buttonText += "OnCustomButtonClicked -> " + eventArgs.Value + "<br />";

        return Task.CompletedTask;
    }
}

In the tag MarkdownEditor, you add the new tab Toolbar that contains one or more MarkdownToolbarButton.

Each MarkdownToolbarButton can have one of the default Action (see table below) or a custom value for example a link to a website. If you want to display before a MarkdownToolbarButton a vertical line, add the property Separator in the MarkdownToolbarButton.

Change the content after the first init

In same cases, you want to refresh the content of the Markdown Editor after the first init, for example because your application has to read the value from an API and it takes time. For that, you have to add a ref to the MarkdownEditor and then use it to call SetValueAsync property, as in the following code

<MarkdownEditor @bind-Value="@markdownValue"
                ValueHTMLChanged="@OnMarkdownValueHTMLChanged"
                SpellChecker="false" @ref="Markdown1" />

@code {
    MarkdownEditor Markdown1;

    // omitted code...

    async Task ChangeText()
    {
        markdownValue = "Test!";
        await Markdown1.SetValueAsync(markdownValue);
    }
}

Add Mermaid render

In order to add more functionaties to the component, it includes the version of mermaid.js 10.2.1 that allows to add impressive diagrams and chart in the Markdown component like

• Flowchart
• Sequence Diagram
• Class Diagram
• State Diagram
• Entity Relationship Diagram
• User Journey
• Gantt
• Pie Chart
• Quadrant Chart
• Requirement Diagram
• Gitgraph (Git) Diagram
• C4C Diagram (Context) Diagram
• Mindmaps
• Timeline

To add this functionality to the Markdown Editor, it is enough to add in the index.html this script

<script src="/_content/PSC.Blazor.Components.MarkdownEditor/js/mermaid.min.js"></script>

The script will check if this library is called. If it is added to the page, the Markdown Editor automatically will add a button in the toolbar to insert the tag for mermaid. That tag is

    ```mermaid
    ```

An example of the mermaid graphs

A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order.

sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!

A Gantt chart is useful for tracking the amount of time it would take before a project is finished, but it can also be used to graphically represent "non-working days", with a few tweaks.

gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2014-01-01, 30d
    Another task     :after a1  , 20d
    section Another
    Task in sec      :2014-01-12  , 12d
    another task      : 24d

An entity–relationship model (or ER model) describes interrelated things of interest in a specific domain of knowledge. A basic ER model is composed of entity types (which classify the things of interest) and specifies relationships that can exist between entities (instances of those entity types).

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

Add Highlight.js

This script is not included in the component but the component can detect if Highlight.js is loaded. In this case, the Markdown Editor renders also the code in one of the supported languages.

To enable this function, add the script in your project and then in the index.html add the following lines

<link rel="stylesheet" href="/path/to/styles/default.min.css">
<script src="/path/to/highlight.min.js"></script>

Known issue using mermaid and Highlight.js

If both libraries are loaded in the index.html, the mermaid render will not work.

Alerts

In the Markdown, there are some missing tags to display some useful information on the page like a highlight note, a tip, a warning or an attention message. So, I added them in this Markdown Editor. An example of the result of this implementation is in the following screenshot.

To add the message, click on the icons in the toolbar in the editor or add those commands:

| Command | Color | Description | |---------|--------|-------------------------------| | att | Red | Display an attention message | | note | Azure | Add a note in the documentt | | tip | Green | Shows a tip message | | warn | Orange | This is a warning message |

In the Markdown Editor component, there is a CSS for the them called alert.css and you can add it to the index.html with this line

<link href="/_content/PSC.Blazor.Components.MarkdownEditor/css/alert.css" rel="stylesheet" />

Clean saved documentation

By default, the Markdown Editor saves the text in the browser local storage.

The AutoSaveEnabled is True and the AutoSaveSubmitDelay is set up to 5000 milliseconds. This means that the text is saved every 5 seconds.

If you want to clean the saved text, you can use the following code

<MarkdownEditor @bind-Value="@markdownValue" MaxHeight="300px"
                ValueHTMLChanged="@OnMarkdownValueHTMLChanged"
                SpellChecker="false" @ref="Markdown1" 
                AutoSaveEnabled="true" />

@code {
    MarkdownEditor Markdown1;

    async Task DeleteStorage()
    {
        await Markdown1.CleanAutoSave();
    }
}

Documentation

The Markdown Editor for Blazor has a estensive collection of properties to map all the functionalities in the JavaScript version. In this repository, there are 2 projects:

• MarkdownEditorDemo is a Blazor Web Assembly project that contains 2 pages: Index.razor where I show how to use the component with the basic functions and Upload.razor that shows how to cope with the image upload. To test the upload, the project MarkdownEditorDemo.Api must run
• MarkdownEditorDemo.Api this is an ASP.NET Core WebApi (.NET6) how to implement a proper API for uploading images. For more details, I wrote a post about Uploading image with .NET.

Properties

Events

Upload file

The Markdown Editor for Blazor can take care of uploading a file and add the relative Markdown code in the editor. For that, the property UploadImage has to set to true. Also, the upload API must be specified in the property ImageUploadEndpoint. In some cases, the API requires an authentication. The properties ImageUploadAuthenticationSchema and ImageUploadAuthenticationToken allow you to pass the correct schema and token to use in the call.

Those values will be added to the HttpClient POST request in the header. Only if both properties are not null, they will be added to the header.

If you want to understand better how to create the API for the upload, I have created a specific post on PureSourceCode.

Toolbar icons

Below are the built-in toolbar icons (only some of which are enabled by default), which can be reorganized however you like. "Name" is the name of the icon, referenced in the JS. "Action" is either a function or a URL to open. "Class" is the class given to the icon. "Tooltip" is the small tooltip that appears via the title="" attribute. Note that shortcut hints are added automatically and reflect the specified action if it has a key bind assigned to it (i.e. with the value of action set to bold and that of tooltip set to Bold, the final text the user will see would be "Bold (Ctrl-B)").

Additionally, you can add a separator between any icons by adding "|" to the toolbar array.

Keyboard shortcuts

EasyMDE comes with an array of predefined keyboard shortcuts, but they can be altered with a configuration option. The list of default ones is as follows:

Licence and contribution

A lot of people sent me the same question. My components (MarkdownEditor, DataTable, SVG Icon and others that you find on my GitHub) are freeware.

I ask you to contribute to the project in one of the following ways:

• sending your feedback
• highlight bugs
• ask for improvement
• submit code and fixes
• share the project
• share my website PureSourceCode.com

If you don't know how to do it or you:

• want to support this project
• find very useful this project and it saves you a lot of time and work
• like to sustain my work
• want to pay my a beer
• are using this component for commercial purpose and you want to set your conscience at rest and/or put a hand on one's heart 😂

then, you can buy one of the support licence I created. There are different prices. The amount is your decision. You find have a full list on PureSourceCode Shop

The contribution gives you:

• dedicate email support
• priority access to the support
• fast bug fix
• receive preview and beta of the components
• help to fix your code with Visual Studio Live Share

Other Blazor components

More examples and documentation

• Write a reusable Blazor component
• Getting Started With C# And Blazor
• Setting Up A Blazor WebAssembly Application
• Working With Blazor Component Model
• Secure Blazor WebAssembly With IdentityServer4
• Blazor Using HttpClient With Authentication
• InputSelect component for enumerations in Blazor
• Use LocalStorage with Blazor WebAssembly
• Modal Dialog component for Blazor
• Create Tooltip component for Blazor
• Consume ASP.NET Core Razor components from Razor class libraries | Microsoft Docs