Integrate DocFX into a C# .NET library and deploy to GitHub Pages

DocFX is a static documentation generator for .NET that will generate a documentation website that you can deploy to a host, such as GitHub Pages. Refer to the DocFX documentation for more information.

To get started, inside your .NET project add the docfx.console package via NuGet.

Then rebuild your project. This will generate a default DocFX project with the following:

• _site folder that contains the output from the documentation generator. This is what will eventually be served on GitHub pages or whichever host.
• api folder containing the api documentation based off of the XML comments in your source code. This will be re-generated so do not modify directly, update your XML comments.
• articles folder that contains the pages in markdown format of your documentation to explain how to use, how it works, and more.
• .gitignore file if it doesn’t already exist. This will add _site to your gitignore and more. Make sure to add them to your .gitignore if it already exists. See below the default settings:

###############
#    folder   #
###############
/**/DROP/
/**/TEMP/
/**/packages/
/**/bin/
/**/obj/
_site

• docfx.json that contains the settings used when generating the documentation. If you delete this file and rebuild your project, it will re-create the missing folders and files.
• index.md that’s the home page for your website.
• log.txt for DocFX logging.
• toc.yml is the table of contents on the top bar of the website. By default it creates two, called Articles and Api Documentation.

This will only generate the default documentation. In order to generate the documentation from your source code, open a command prompt and run the following. Make sure you have docfx installed by first running

choco install docfx

Then the following.

docfx "C:\path\to\your\docfx\file\docfx.json" --serve

You can also run it from the same directory as your docfx.json file.

docfx --serve

Navigate to localhost:8080 in the browser to see it in action. As of this posting, hot module reloading is not supported. Therefore, if you make a change, quit the running docfx — serve command, and re-run it after making your updates.

The home page looks like this. Up top is where the toc.yml generates the top bar. The logo navigates to the home page.

Articles looks like this. As you add more, they’ll appear on the left hand side.

Api Documentation looks like this. This is what is generated off of your XML comments in your source code.

If you want to update the favicon and logo used, you have to first add them to your project, then reference them in your docfx.json. By default it looks for a folder named images in the same directory as docfx.json. Add your files there. They must be named favicon.ico and logo.svg. The logo.svg must be 51x51 pixels to match what’s already there.

You’ll need to add the following to your docfx.json file underneath “build”

"globalMetadata": {
"_appFaviconPath": "images/favicon.ico",
"_appLogoPath": "images/logo.svg"
},

This tells DocFX where to look when getting the favicon and logo.

Next, rename the _site folder to docs, move docs to the root of your repository, and push your code. Setup GitHub pages by navigating to your repository’s home page, Settings -> Pages and select your branch, and “docs” as the folder to build from. Wait, and refresh until it gives you the url.

DocFX rocks and I used this to generate the documentation for another project found here. You can see the github repository here.