Using Markdown in Visual Studio

By Apr 27, 2017

Description:

This article explains that Markdown can be installed in Visual Studio and used as a text editor and HTML converter or as a library, with examples of conversion on the fly.

Preferencesoft

This article shows how to install and use Markdown / MarkDig in Visual Studio.
Markdown can be integrated into Visual Studio and can be used as a text editor or a converter to HTML.

Interest of Markdown

The HTML language has a syntax that does not allow easy editing of a text. It requires an HTML code editor that you can find in Visual Studio for example.
But if a web developer decides to insert into a page of his website a comment editor, he has several possibilities:

  •          use a plain text box,

  •          use a rich text box,

  •          or design a WYSIWYG HTML editor

The last two solutions are ideal for a visitor to the site. Indeed, he will be able to format his comment, write text in italics, bold or color, etc.
The first solution allows to write only plain text and if posted it such, we would get an unsatisfactory result. To make more attractive viewing of comments, it is possible to use tags to represent emoticons, to create links to other sites, etc. But avoid asking a visitor to encode its comments in HTML.
Currently, the solution the most widespread is to ask the user to type his comment under certain rules, like placing his text between two dashes _ to get it in italics, etc.
This text is then automatically converted into HTML and viewed in another part of the page.

There are many languages including basic text formatting rules, but one that is widely used is Markdown. An interesting extension of Markdown is Markdig and can be installed on Visual Studio.

Markdown has other uses. Some web master use it to create the content of the pages of their site. The text of a page is placed in a text file, automatically converted to HTML and inserted into a web page template. In keeping with the style of their site, they customize the CSS file that is created by default by Markdown. Pages may be also generated by the server, by converting on the fly the Markdown files to HTML.

On the other hand, Markdown can be useful for developers to write documentation for their software.

Use of Markdown as text editor

You can find a Markdown for Visual Studio editor at the following address: https://marketplace.visualstudio.com/items?itemName=MadsKristensen.MarkdownEditor
It is powered by the Markdig parser.

After installing, just create a text file with the .md extension in Visual Studio.

By double clicking on the file name in solution Explorer, it brings up two windows side by side.
Type a few lines of text in the left window:

Markdown | Editor | Visual Studio

--- | --- | ---

*italic* | `code` | **emphasis**

1 | 2 | 3

We can see the result in the preview window:

Table

Converting a Markdown file to HTML

To convert a Markdown file to HTML in VS, we right click on the file and select Generate HTML file.
A HTML file with the same name is created.

Give an example. Type the following text file:

File.md

# Header1

## Header2

### Header3

 

**Bold**, ^superscript^, ++underlined++

 

```csharp

int i=0;

int j=5;

String s = "aaaa";

```

 

---

 

In the preview window, we get:

Markdown preview

And converting to HTML:

<!DOCTYPE html>
<html>
 
<body>
    <h1 id="header1">Header1</h1>
    <h2 id="header2">Header2</h2>
    <h3 id="header3">Header3</h3>
    <p><strong>Bold</strong>, <sup>superscript</sup>, <ins>underlined</ins></p>
<pre><code class="language-csharp">int i=0;
int j=5;
String s = &quot;aaaa&quot;;
</code></pre>
    <hr />
</body>
</html>

We remark that the header is reduced to a minimum and there is no link to bootstrap for example.
You can resolve this problem by creating the md-template.html template file and placing the necessary references to style sheets and JavaScript files.
It is possible to change the default template file name in Visual Studio. You can search: Tools > Options > Markdown > Advanced HTML > Template file name > file name.

This is the default template file:

<!DOCTYPE html>
<html>
<head>
    <title>[title]</title>
</head>
 
<body>
 
    [content]
 
</body>
</html>

Conversion of Markdown in HTML code by programming

If we stored Markdown text in files or in a database, such as for example comments, it may be useful to convert to HTML and insert the code into a Web page.

This conversion can be done on the server side when generating a page. We will give an example in ASP.NET MVC.

Create an ASP.NET MVC application, install the Markdig package on Nuget and in the index.cshtml file, insert the following instructions:

@Html.Raw(Markdig.Markdown.ToHtml("This is a text with some *emphasis*"))

The display shows:

This is a text with some emphasis

In fact, we have not all features of Markdig. For example, missing citations, task lists, media links, …
If we want to use emoticons, for example, we need to add a few lines of code:

@{
    var pipelineBuild = new Markdig.MarkdownPipelineBuilder();
    pipelineBuild = Markdig.MarkdownExtensions.UseAdvancedExtensions(pipelineBuild);
    pipelineBuild = Markdig.MarkdownExtensions.UseEmojiAndSmiley(pipelineBuild);
    var pipeline = pipelineBuild.Build();
    @Html.Raw(Markdig.Markdown.ToHtml("# Heading 8-)\nThis is a text with some *emphasis* ;)", pipeline));
}

We get:

Emoji

Now, load the file.md file, convert it to HTML:

@{
    var pipelineBuild = new Markdig.MarkdownPipelineBuilder();
    pipelineBuild = Markdig.MarkdownExtensions.UseAdvancedExtensions(pipelineBuild);
    pipelineBuild = Markdig.MarkdownExtensions.UseEmojiAndSmiley(pipelineBuild);
    var pipeline = pipelineBuild.Build();
    string FilePath = Server.MapPath("file.md");
    StreamReader sr = new StreamReader(FilePath);
    @Html.Raw(Markdig.Markdown.ToHtml(sr.ReadToEnd(), pipeline));
}

Conclusion

That conversion can of course be done in an ASP.NET Webforms application.

If your site is not extremely fast, I advise you to convert Markdown files beforehand.

 


Visual Studio

Categories

Share

Follow


KodFor Privacy Policy