Markdown + .NET = Interactive docs?
Tags: net, webassembly, markdown
Published: 2019-05-17 18:38:39

---
title: Markdown + .NET = Interactive docs?
published: true
description: Creating interactive .NET documentation
tags: C#, .NET, webassembly, Markdown
---

 My team and I have been trying to figure out ways for developers from the newbies to the more experienced that would enable them to try and explore .NET easily. Our work lead to the development of Try .NET.

**What is Try .NET**: Try .NET is an interactive documentation generator for .NET Core.

## Try .NET Online 
When Try .NET initially launched in September 2017, on docs.microsoft.com, we executed all our code server side using Azure Container Instances. However, over the past five months, we switched our code execution client side using Blazor and Web Assembly. By moving  client side execution it allowed us to provided Try .NET to a larger audience for FREE :smiley:.

You can see this for yourself by visiting [this page](https://docs.microsoft.com/dotnet/csharp/tutorials/intro-to-csharp/hello-world?tutorial-step=5), and opening your browser's developer tools. Under the *Console* tab, you will see the  message `WASM:Initialized`. Now, switch over to the *Network* tab, and you will see all the DLLs now running on the client side. 

![WASm](https://user-images.githubusercontent.com/2546640/57245063-c6d10f00-6fee-11e9-860e-ddd6327c79c5.PNG)
*Console Tab: WASM Initialized*

![Network](https://user-images.githubusercontent.com/2546640/57245056-c3d61e80-6fee-11e9-91f3-628aaa125a1f.PNG)
*Network tab: DLLs*

## Try .NET Offline

It was essential for us to provide interactive documentation both online and offline. For our offline experience, it was crucial for us to create an experience that plugged into our content writers' current workflow.
In our findings, we noticed that our content developers had two common areas they consistently used while creating developer documentation.  
1.  A sample project that users could download and run.
2.  Markdown files with a set of instructions, and code snippets they copied and pasted from their code base. 

Try .NET enables .NET developers to create interactive markdown files with the use of the `dotnet try` global tool.
To make your markdown files interactive, you will need the [.NET Core SDK](https://dotnet.microsoft.com/download/dotnet-core/3.0), the [dotnet try global tool](https://www.nuget.org/packages/dotnet-try/), [Visual Studio](https://visualstudio.microsoft.com/) / [VS Code](https://code.visualstudio.com/), and your repo.
![interactive_doc](https://user-images.githubusercontent.com/2546640/57158389-47a2c780-6db1-11e9-96ad-8c6e9ab52853.png) 

### How are we doing this?

**Extending Markdown**

In markdown, you use fenced code blocks to highlight code snippets. You place triple backticks before and after code blocks. You can add optional language identifiers to enable syntax highlighting in your fenced code block. For example, a C# code block would look like this:


```cs 
var name ="Rain";
Console.WriteLine($"Hello {name.ToUpper()}!");
```
With Try .NET we have extended our code fences to include additional options.

 
```cs
cs --region methods --source-file .\myapp\Program.cs --project .\myapp\myapp.csproj 
var name ="Rain";
Console.WriteLine($"Hello {name.ToUpper()}!");
```

We have created the following options:
- The `--region` option points to a C# region. 
- The `--source-file` option points to a file containing source code.
- The `--project` option points to a project file, which you can use to reference NuGet packages.

So, what we are doing here is accessing code from a `#region` named `methods` in a backing project `myapp` and enabling you to run it within your markdown.

**Using #regions**

In our markdown we extended the code fence to include a `--region` option that points to a C# region which targets a region named `methods`.

So, your `Program.cs` would look like this:

```cs
using System;

    namespace HelloWorld
    {
        class Program
        {
            static void Main(string[] args)
            {
                #region methods
                var name ="Rain"
                Console.WriteLine($"Hello{name.ToUpper()}!");  
                #endregion
            }
        }
    }
```
**dotnet try verify**

`dotnet try verify` is a compiler for your documentation. With this command, you can make sure that every code snippet will work and is in sync with the backing project. 

The goal of  `dotnet try verify ` is to validate that your documentation works as intended.

By running `dotnet try verify` you will be able to detect markdown and compile errors. For example, if  I removed a semicolon from the code snippet above and renamed the region from `methods` to `method`, I would get the following errors. 
 
![dotnettryverify](https://user-images.githubusercontent.com/2546640/57272892-67a0e800-704a-11e9-83f0-c0f2181e888e.PNG)


### Try  the `dotnet try` global tool
- Clone [this repo](https://github.com/dotnet/try)
- Install .NET Core SDK [3.0](https://dotnet.microsoft.com/download/dotnet-core/3.0) and [2.1](https://dotnet.microsoft.com/download/dotnet-core/2.1). Currently, the `dotnet try` global tool targets 2.1. 
- Go to your terminal 
- Install the [Try .NET tools](https://www.nuget.org/packages/dotnet-try/)

`dotnet tool install --global dotnet-try --version 1.0.19266.1`

Updating to the latest version of the tool is easy just run the command below

`dotnet tool update -g dotnet-try`

- Navigate to the Samples directory of this repository and, type the following  `dotnet try`.
![dotnet try](https://user-images.githubusercontent.com/2546640/57164943-ab35f080-6dc3-11e9-8230-ee521e00e428.gif)

- This will launch the browser.
Sorry broken image link 😿. You can view the launch experience [here](https://thepracticaldev.s3.amazonaws.com/i/63cddcradm72ck2tdhhv.gif)

### Try .NET is now Open Source
Try .NET source code is now on [GitHub](https://github.com/dotnet/try)! Please feel free to file any bugs reports under our issues. And if you have any feature suggestion, please submit them under our issues using the community suggestions label.

To learn more about Try .NET, check out the [dotnet try repo](https://github.com/dotnet/try). Looking forward to your feedback.