Docsify + C# – Code Docs Made Easy… Finally!
Introduction
I have been a software developer for 20 years, and have been coding professionally for over 10 years now.. in all that time, one area that I have always struggled with is documentation. I mean, really.. how many of us developers are able to stand writing documentation, let alone “enjoy” doing so? I do know one guy at work who enjoys it, but it would seem that he is the exception that proves the rule. Anyways.. if you are like me and you hate writing separate documentation, then read on!
I have tried quite a few code documentation tools over the years. I will not mention them here because I don’t want this post to come across in any way as an attempt to bash on any of the tools out there. It is quite possible that my issue with each of the projects I used was my own issue. Lack of knowledge, lack of patience, or something to that effect. Every tool I tried seemed to be too complicated, too simplified, the output was too ugly or outdated looking, etc. Long story short, I never found the tool that was “just right” for my needs… until now!
What I’m Looking for
When I’m searching for a way to present my code documentation, I have a few simple requirements:
- Ability to write the documentation using markdown – Just because I can write in HTML5, CSS3, Javascript, TypeScript, etc.. doesn’t mean I want to spend any time using any of that for simply creating documentation.
- Dark theme! – the generated output MUST be a dark theme.. or at least have a toggle to easily display as a dark theme. A surprising number of projects I’ve tried over the years have no simple way to generate a dark theme output.
- Simple to setup and adjust generated docs – I don’t want to spend much time setting up the doc project, I want to spend my time writing docs (or better, writing code!)
- Mobile friendly – I spend an embarrassing amount of my reading time doing so on my phone. I don’t use my phone for all that much other than reading, actually. In the modern world, sites have no choice but to be mobile friendly.. and not as an afterthought.
- Minimal steps to integrate in-code documentation – I always do my best to document my code while I am writing it, in the form of
xmldoccode comments. Unfortunately it would seem, there is not wide support for using these docs in a C# project.
What I found
This past weekend I stumbled across a project called Docsify that claims to be “A magical documentation site generator.” Now, I’ve seen projects makes claims like this before and was very disappointed each time, but I decided to give it a shot because I am always hopeful! I gotta say, I was blown away by how quickly I was able to produce a site and get back to writing docs (and code)!
Take a look for yourself at what was able to be generated with minimal configuration:
Creating Your Own Site with Docsify
When I say minimal configuration, I mean it.. Getting started with Docsify could not be easier. There are two choices to create your own project, you can either use the docsify global tool for npm, or you can simply create an index.html file and start creating your markdown files. Docsify has a quickstart guide that you can easily follow, and I encourage you to read it, but it basically says to do this…
# Install the docsify tool globally
npm i docsify-cli -g
# Init the subdirectory "docs" with the skeleton project consisting of three files:
# index.html - main entry point
# README.md - the default markdown file that Docsify will read
# .nojekyll - This is only needed if you are hosting your output on GitHub Pages
docsify init ./docs
# Spin up a local webserver on port 3000 that will watch for changes in the docs directory
docsify serve docsThe index.html file that it creates is very basic, as shown below, and the Markdown file is basically empty, but that, to me, is the beauty of it… the site is basic and to the point. Start adding some content to README.md and then see how the page evolves very quickly.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Document</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: '',
repo: ''
}
</script>
<!-- Docsify v4 -->
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
</body>
</html>I mean, it really can’t get more simple than that! Simply change the name and the repo URL and you are good to go.
Customizing Your Site
Now, if you are like me and like things a bit more customized, I feel that is where Docsify really shines. There are a pile of awesome plugins for it that are easy to add and configure. They have a list of plugins that you can look through. For most plugins, installation is as easy as adding another <script> tag to the bottom of the file, and maybe add a line or two in the window.$docsify = { } block. That’s it!
A more complete example can be seen here, this is the configuration I used to generate the documentation in the screenshot above..
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>TerminalUI</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-darklight-theme@3.2.0/dist/style.min.css" title="docsify-darklight-theme" type="text/css" />
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: 'TerminalUI',
nameLink: 'https://code.foxhollow.cc/terminal-ui/',
repo: 'https://git.foxhollow.cc/hairlesshobo/TerminalUI',
coverpage: false,
loadSidebar: true,
maxLevel: 2,
subMaxLevel: 3,
loadNavbar: true,
relativePath: true,
progress: {
position: "top",
color: "var(--theme-color,#42b983)",
height: "3px",
}
}
</script>
<!-- Docsify v4 -->
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.25.0/components/prism-csharp.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.25.0/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@3.2.0/dist/index.min.js" type="text/javascript"></script>
<script src="//cdn.jsdelivr.net/npm/docsify-progress@1.0.3/dist/progress.min.js"></script>
</body>
</html>As you can see, there are a few more script imports, several more lines in the window.$docsify block, and I changed the theme that I am using to the “darklight” theme. So just those few extra lines and I was able to highly customize my output.
Integrating XmlDoc Code Comments
Now so far, with the basic configuration I have above, I was able to meet requirements 1 – 4 listed above. That’s awesome, that really is.. because most other projects can’t meet the first 4 without a significant amount of work. Now for number 5. For me, this one is very important. Nearly all of the code I write is done in C# and I spent a lot of time writing code docs in the source code for use by IntelliSense and similar IDE helpers. In my ideal world, I want to be able to extract all those comments and present them in the same site as the rest of my documentation. Thankfully, I was able to do a basic integration of these code comments in just a few easy steps.
First, I need to tell dotnet that I want to enable generation of xml docs, which is super easy to do. Simply enable GenerateDocumentationFile in your .csproj file, as I did below:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<PackageId>FoxHollow.TerminalUI</PackageId>
<TargetFramework>netstandard2.0</TargetFramework>
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
</Project>Next, I need to install a little tool called xmldoc2md, which can be found here. Simply install the tool to dotnet and run it.
# Install XMLDoc2Markdown as a dotnet tool
dotnet tool install -g XMLDoc2Markdown
# Then build your app
dotnet build
# Then run the tool
xmldoc2md ./bin/Debug/netstandard2.0/MyLibrary.dll ./docs/api/This will convert any XMLDoc code comments found in MyLibrary to markdown files. Once you’ve generated this, you can add the output of xmldoc2md to your Docsify site!
Hosting
The Docsify website has quite a few examples of ways to host the generated site, but one they failed to mention was that you can simply drop the entire docs folder onto a static webserver and let it be served. I have hosted the output on both Apache and nginx and it just works. Just place the index.html file, and all the other files/folders you have in your docs folder on a webserver somewhere and you are good to go.
Conclusion
This article was meant to be an introduction to Docsify and XMLDoc2Markdown, and how simple it is to get code docs online. I am still very new to Docsify but so far I am extremely impressed with what I have seen. I plan to do a follow up article in the coming days about some other tricks I have learned. I am also working on a few scripts to help with the automatic generation and formatting of XMLDoc comments (mainly to better integrate the sidebar), so be sure to stay tuned!