Markdown + .NET = Interactive docs?

LadyNaggaga — Fri, 17 May 2019 18:38:39 +0000

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 😃.

You can see this for yourself by visiting this page, 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.

Console Tab: WASM Initialized

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.

A sample project that users could download and run.
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, the dotnet try global tool, Visual Studio / VS Code, and your repo.

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:

var name ="Rain";
Console.WriteLine($"Hello {name.ToUpper()}!");

With Try .NET we have extended our code fences to include additional options.

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:

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.

Try the `dotnet try` global tool

Clone this repo
Install .NET Core SDK 3.0 and 2.1. Currently, the dotnet try global tool targets 2.1.
Go to your terminal
Install the Try .NET tools

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.
This will launch the browser.
Sorry broken image link 😿. You can view the launch experience here

Try .NET is now Open Source

Try .NET source code is now on GitHub! 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. Looking forward to your feedback.