Using Docsify with ASP.NET (NOT Core)

Using a site document generator like Docsify with an older .NET project can cause general functionality issues, but in today's post, we'll address them and show solutions for ASP.NET MVC projects.

I know, you don't need to tell me.

I know every developer loves to write documentation.

Over the holiday, I was working on an older codebase (ASP.NET MVC, 4.5.2 .NET with Owin) and, as large as the project was, it required some documentation.

I decided to install the documenting site generator called Docsify. While Docsify provides quick documentation using markdown, it was a simple JavaScript-based document generator.

I thought, "what could go wrong? It's a JavaScript engine. It runs in the browser."

So I wanted to see how Docsify would play with ASP.NET MVC since it was client-side and different from the MVC approach.

Installing Docsify

After performing an installation using npm, I created a docs folder and started writing my markdown.

After writing some rudimentary "hello world" markdown pages, I dug into the configuration options available to me.

Configuration was pretty standard. Nothing out of the ordinary.

<div id="app"></div>
<script>
    window.$docsify = {
        loadSidebar: true,
        loadNavbar: false,
        basePath: '/docs/',
        repo: ''
    }
</script>

After running the project, I tried to access Docsify through the docs directory.

I received this.

Hmm. Well, that's no bueño.

Ohh-win!

Since this was an ASP.NET MVC application, my first thought was this won't work because I need a controller and action to point to the index.html file.

Then I thought, this is simply an HTML file. There's no reason why it can't return a static file.

DOH!

The application is using SignalR and required OWIN. For those wondering what OWIN is, it was the beginnings of middleware for ASP.NET Core and used with SignalR.

The problem was OWIN didn't know how to handle static and default files. It only understood MVC-speak.

So I headed to NuGet.org, found the package I needed, and installed it through the NuGet Package Manager.

  <package id="Microsoft.Owin.StaticFiles" version="4.1.1" targetFramework="net452" />

I also had to set up the application so it could serve static and default files as well. I added this to my Startup.cs (in the root, NOT in the App_Start folder)

public void Configuration(IAppBuilder app)
{
    app.UseDefaultFiles(); // default.html, default.htm, index.html, and index.htm
    app.UseStaticFiles();

    ConfigureAuth(app);

    app.MapSignalR();
}

While I did feel this was a step in the right direction, it still wasn't working.

What's missing?

I was running through the MVC pipeline in my head wondering what was missing.

Then it hit me.

Docsify runs in a single page and uses JavaScript TO LOAD MARKDOWN FILES. We didn't define .MD files as part of the site. We needed to tell IIS that .md files were valid to return to the browser when JavaScript called them.

Since it's static content, I created an entry in the <configuration> -> <system.webServer> to define what an .md file was and how to handle it.

    <staticContent>
      <remove fileExtension=".md" />
      <mimeMap fileExtension=".md" mimeType="text/markdown" />
    </staticContent>

Once I added this to my web.config, the site lit up because it could load the _sidebar.md and README.md.

Everything was working.

BONUS: Authorized Users

One other feature I needed for the docs was the ability to hide the docs to anonymous users. Anyone who wasn't authorized in the system wasn't allowed to view the docs since they were specific to registered users.

Again, this required another web.config entry. This time, at the end of the web.config, we identify the path that was off-limits to anonymous users.

  <location path="docs">
    <system.web>
      <authorization>
        <deny users="?" />
      </authorization>
    </system.web>
  </location>

<deny users="*" /> means deny everyone from accessing the docs directory and <deny users="?" /> means deny unauthorized users from accessing the directory.

So essentially, if someone types in https://www.myurl.com/docs, they'll be redirected to a login page.

Conclusion

In today's post, we implemented Docsify into an older ASP.NET MVC application while showing some gotchas along the way.

While Docsify was just one example of a site document generator, these types of projects really test the older implementations of .NET. As you can see, there were some hoops you need to jump through to get this working properly.

With ASP.NET Core, implementation details are simpler because of the architecture. You still need to include static files in your Startup.cs, but it definitely makes installing separate, independent libraries easier to work with because they just work with minimal tweaking (like pushing content into the wwwroot folder)

Are you using a site document generator? Docusaurus? GitBook? Were they easy to install? Post your comments below and let's discuss.