Markdown Editor component for Blazor

markdown editor blazor logo

Few weeks ago, I created a package for a Markdown Editor component for Blazor with very basic functionalities. After a couple of months of work, finally, I created a very nice Markdown Editor component based on EasyMDE flexible and rich of functionalities for Blazor WebAssembly and Blazor Server with .NET6.

Markdown Editor component for Blazor in action
Markdown Editor component for Blazor in action

The full source code of the component is available on GitHub. In the same repository, there is a demo project and another project for the integration between the Markdown Editor for Blazor and the API for uploading images.

How to use

First, in your Blazor project, add the NuGet package called PSC.Blazor.Components.MarkdownEditor. Then, add the Markdown Editor to your _Imports.razor

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

Now, 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 EasyMDE script version 2.15.0. Obviously, 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

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

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

    <hr />

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

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

    protected override void OnInitialized()
    {
        markdownHtml = Markdig.Markdown.ToHtml(markdownValue ?? string.Empty);
        base.OnInitialized();
    }

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

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

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

Markdown Editor component for Blazor in action
Markdown Editor component for Blazor in action

Code explained

So, the initial text for the Markdown Editor is coming from the markdownValue that is a string containing Markdown text. For every change in the editor, the Value changes and the component raises an event, in this case OnMarkdownValueChanged: this event receives the Markdown text as a value.

From here, I can process with my procedure the Markdown text to obtain the HTML but I want to simplify this step. So, the component converts the Markdown text in a HTML and raises the event ValueHTMLChanged.

Documentation

The Markdown Editor for Blazor has an 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

NameDescriptionTypeDefault
AutoSaveEnabledGets or sets the setting for the auto save. Saves the text that’s being written and will load it back in the future. It will forget the text when the form it’s contained in is submitted. Recommended to choose a unique ID for the Markdown Editor.boolfalse
AutoSaveIdGets or sets the automatic save identifier. You must set a unique string identifier so the component can autosave. Something that separates this from other instances of the component elsewhere on your website.stringDefault value
AutoSaveDelayDelay between saves, in milliseconds. Defaults to 10000 (10s).int10000 (10s)
AutoSaveSubmitDelayDelay before assuming that submit of the form failed and saving the text, in milliseconds.int5000 (5s)
AutoSaveTextText for autosavestringAutosaved:
AutoSaveTimeFormatLocaleSet the format for the datetime to display. For more info, see the JavaScript documentation DateTimeFormat instancesstringen-US
AutoSaveTimeFormatYearSet the format for the yearstringnumeric
AutoSaveTimeFormatMonthSet the format for the monthstringlong
AutoSaveTimeFormatDaySet the format for the daystring2-digit
AutoSaveTimeFormatHourSet the format for the hourstring2-digit
AutoSaveTimeFormatMinuteSet the format for the minutestring2-digit
AutoDownloadFontAwesomeIf set to true, force downloads Font Awesome (used for icons). If set to false, prevents downloading.bool?null
CustomButtonClickedOccurs after the custom toolbar button is clicked.EventCallback
Directionrtl or ltr. Changes text direction to support right-to-left languages. Defaults to ltr.stringltr
ErrorMessagesErrors displayed to the user, using the errorCallback option, where image_name, image_size and image_max_size will be replaced by their respective values, that can be used for customization or internationalization.MarkdownErrorMessages
HideIconsAn array of icon names to hide. Can be used to hide specific icons shown by default without completely customizing the toolbar.string[]‘side-by-side’, ‘fullscreen’
ImageAcceptA comma-separated list of mime-types used to check image type before upload (note: never trust client, always check file types at server-side). Defaults to image/png, image/jpeg, image/jpg, image.gif.stringimage/png, image/jpeg, image/jpg, image.gif
ImageCSRFTokenCSRF token to include with AJAX call to upload image. For instance, used with Django backend.string
ImageMaxSizeMaximum image size in bytes, checked before upload (note: never trust client, always check image size at server-side). Defaults to 1024 * 1024 * 2 (2Mb).long1024 * 1024 * 2 (2Mb)
ImagePathAbsoluteIf set to true, will treat imageUrl from imageUploadFunction and filePath returned from imageUploadEndpoint as an absolute rather than relative path, i.e. not prepend window.location.origin to it.string
ImageTextsTexts displayed to the user (mainly on the status bar) for the import image feature, where image_name, image_size and image_max_size will be replaced by their respective values, that can be used for customization or internationalization.MarkdownImageTextsnull
ImageUploadAuthenticationSchemaIf an authentication for the API is required, assign to this property the schema to use. Bearer is the common one.stringempty
ImageUploadAuthenticationTokenIf an authentication for the API is required, assign to this property the tokenstringempty
LineNumbersIf set to true, enables line numbers in the editor.boolfalse
LineWrappingIf set to false, disable line wrapping. Defaults to true.boolfalse
MaxHeightSets fixed height for the composition area. minHeight option will be ignored. Should be a string containing a valid CSS value like “500px”. Defaults to undefined.string
MaxUploadImageMessageSizeGets or sets the max message size when uploading the file.long20 * 1024
MinHeightSets the minimum height for the composition area, before it starts auto-growing. Should be a string containing a valid CSS value like “500px”. Defaults to “300px”.string300px
PlaceholderIf set, displays a custom placeholder message.stringnull
SegmentFetchTimeoutGets or sets the Segment Fetch Timeout when uploading the file.TimeSpan1 min
ShowIconsAn array of icon names to show. Can be used to show specific icons hidden by default without completely customizing the toolbar.string[]‘code’, ‘table’
TabSizeIf set, customize the tab size. Defaults to 2.int2
ThemeOverride the theme. Defaults to easymde.stringeasymde
Toolbar[Optional] Gets or sets the content of the toolbar.RenderFragment
ToolbarTipsIf set to false, disable toolbar button tips. Defaults to true.booltrue
UploadImageIf set to true, enables the image upload functionality, which can be triggered by drag-drop, copy-paste and through the browse-file window (opened when the user clicks on the upload-image icon). Defaults to false.boolfalse
ValueGets or sets the markdown value.stringnull
ValueHTMLGets the HTML from the markdown value.stringnull

Events

NameDescriptionType
ErrorCallbackA callback function used to define how to display an error message. Defaults to (errorMessage) => alert(errorMessage).Func
ImageUploadChangedOccurs every time the selected image has changed.Func
ImageUploadEndedOccurs when an individual image upload has ended.Func
ImageUploadEndpointThe endpoint where the images data will be sent, via an asynchronous POST request. The server is supposed to save this image, and return a json response.string
ImageUploadProgressedNotifies the progress of image being written to the destination stream.Func
ImageUploadStartedOccurs when an individual image upload has started.Func
ValueChangedAn event that occurs after the markdown value has changed.EventCallback
ValueHTMLChangedAn event that occurs after the markdown value has changed and the new HTML code is available.EventCallback

Upload file

Now, 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.

So, the result is quite nice and you can see the Markdown Editor for Blazor in action in the following screenshot. How you can see, I drag an image on the editor and immediately the upload process starts. When the API returns then URL for the image, the editor adds a new Markdown text for the image.

Markdown Editor component for Blazor Upload example
Markdown Editor component for Blazor Upload example

How to create the API

Now, if you want to allow users to upload pictures via the Markdown Editor for Blazor, the property UploadImage must set to true. Then, the endpoint for the API must be declared via the property ImageUploadEndpoint.

The Markdown Editor has JavaScript under the cover and this can cause same complications. For this reason, I managed in the JavaScript code to have the uploaded imaged encoded in Base64. Then, a C# function takes care to upload the file to the specified API. This API must return a 200 HTTP code and, as a content, the URL of the uploaded image.

It seems easy but I took a lot of time to figure out how to do it. So, I created the post Upload/Download Files Using HttpClient to explain in details how to create the required API.

The full source code of the component is available on GitHub.

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.

NameActionTooltip
Class
boldtoggleBoldBold
fa fa-bold
italictoggleItalicItalic
fa fa-italic
strikethroughtoggleStrikethroughStrikethrough
fa fa-strikethrough
headingtoggleHeadingSmallerHeading
fa fa-header
heading-smallertoggleHeadingSmallerSmaller Heading
fa fa-header
heading-biggertoggleHeadingBiggerBigger Heading
fa fa-lg fa-header
heading-1toggleHeading1Big Heading
fa fa-header header-1
heading-2toggleHeading2Medium Heading
fa fa-header header-2
heading-3toggleHeading3Small Heading
fa fa-header header-3
codetoggleCodeBlockCode
fa fa-code
quotetoggleBlockquoteQuote
fa fa-quote-left
unordered-listtoggleUnorderedListGeneric List
fa fa-list-ul
ordered-listtoggleOrderedListNumbered List
fa fa-list-ol
clean-blockcleanBlockClean block
fa fa-eraser
linkdrawLinkCreate Link
fa fa-link
imagedrawImageInsert Image
fa fa-picture-o
tabledrawTableInsert Table
fa fa-table
horizontal-ruledrawHorizontalRuleInsert Horizontal Line
fa fa-minus
previewtogglePreviewToggle Preview
fa fa-eye no-disable
side-by-sidetoggleSideBySideToggle Side by Side
fa fa-columns no-disable no-mobile
fullscreentoggleFullScreenToggle Fullscreen
fa fa-arrows-alt no-disable no-mobile
guideThis linkMarkdown Guide
fa fa-question-circle

Keyboard shortcuts

The Markdown Editor component for Blazor 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:

Shortcut (Windows / Linux)Shortcut (macOS)Action
Ctrl-‘Cmd-‘“toggleBlockquote”
Ctrl-BCmd-B“toggleBold”
Ctrl-ECmd-E“cleanBlock”
Ctrl-HCmd-H“toggleHeadingSmaller”
Ctrl-ICmd-I“toggleItalic”
Ctrl-KCmd-K“drawLink”
Ctrl-LCmd-L“toggleUnorderedList”
Ctrl-PCmd-P“togglePreview”
Ctrl-Alt-CCmd-Alt-C“toggleCodeBlock”
Ctrl-Alt-ICmd-Alt-I“drawImage”
Ctrl-Alt-LCmd-Alt-L“toggleOrderedList”
Shift-Ctrl-HShift-Cmd-H“toggleHeadingBigger”
F9F9“toggleSideBySide”
F11F11“toggleFullScreen”

Wrap up

In conclusion, this is a new Markdown Editor for Blazor, with a lot of functionalities, flexible and with image upload. I hope you like it and will use it. It you need help or for suggestion, please comment below or in the Forum.

Other Blazor components

  • DataTable for Blazor: DataTable component for Blazor WebAssembly and Blazor Server
  • Markdown editor for Blazor: This is a Markdown Editor for use in Blazor. It contains a live preview as well as an embedded help guide for users.
  • Modal dialog for Blazor: Simple Modal Dialog for Blazor WebAssembly
  • PSC.Extensions: A lot of functions for .NET6 in a NuGet package that you can download for free. We collected in this package functions for everyday work to help you with claim, strings, enums, date and time, expressions…
  • Quill for Blazor: Quill Component is a custom reusable control that allows us to easily consume Quill and place multiple instances of it on a single page in our Blazor application
  • Segment for Blazor: This is a Segment component for Blazor Web Assembly and Blazor Server
  • Tabs for Blazor: This is a Tabs component for Blazor Web Assembly and Blazor Server

More examples and documentation

One thought on “Markdown Editor component for Blazor

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.