Configuring DocFX

Install latest .NET, and after the installation run this command if you don't want Microsoft to collect your .NET usage data:
setx DOTNET_CLI_TELEMETRY_OPTOUT 1

Follow the DocFX Quick Start, it's quite straight forward.  And here are some more tips on how to customize your DocFX experience.

Git adjustments
Add _site folder to .gitignore in addition to any other items your DocFX git repository should avoid having.

Favicons configuration
Add all the favicons to the root folder. It's advisable to generate all the favicons using a generator.
Add all the favicon images to the resource list in the docfx.json.

UI customizations
  • Add customizations using your own new template (i.e. logo and its size).
    • Add a new template folder in the root of your repo - name it repo-name-template, as an example.
    • Add main.css to the repo-name-template\public\ subfolder.
    • Use the main.css to specify customizations.
  • Add the source folder for the modern template to the root of your DocFX repo and add it to the list of templates in the docfx.json.
  • Edit the modern template's _master.tmpl and add all the <link> references for all the icon sizes and the Apple touch icon.

DocFX Companion Tools
These tools are very useful, for example, using the DocFXTocGenerator your site will generate all the menu links from existing content (.md files) recursively.
To set up DocFxTocGenerator, simply install the DocFxTocGenerator on your machine using the dotnet tool:
dotnet tool install DocFxTocGenerator -g

The instructions for doing the above are here.

Then add this line of code for each of your documentation folder in your DocFx site:
DocFxTocGenerator -d ./docs -vs

The explanation for the parameters v and s is here.

With the DocFxTocGenerator it's easiest to employ a couple of these commands to your git sync file, so that the table of contents are generated automatically before the pages are pushed to the repository.

To find more extensions to DocFX be sure to visit DocFX Tools.

A list of organizations that use DocFX:
To use DocFX, include it in your API project to generate its documentation.  There are some free guides how to include good comments in your code, add DocFX references, and generate API docs or code documentation with DocFX on project build.


Other popular notes

Popular posts from this blog

SharePoint PowerShell Quick Guide

If you manage an online SharePoint tenant you will run into a lot of situations where PowerShell will be the surest way to accomplish your tasks. Permanently deleting a site via PowerShell Remove-SPOSite -Identity https://site.sharepoint.com Managing Hub Sites 2,000 hub sites per tenant A modern SharePoint site can be promoted to a Hub site As a team site As a communications site Global navigation added automatically Configure who is allowed to add sites to the hub Can also configure an approval workflow Hub site can be registered in the admin center Admins can choose who can associate sites with hub - Users, Security Groups, Office 365 Groups Hub site can be registed with PowerShell (to make it a hub site) Register-SPOHubSite -Site https://site.sharepoint.com/sites/hubsite -Principals $null To associate other sites to a hub Unregistering a hubsite disconnects it from the hub Unregister-SPOHubSite     -Identity https://sites.sharepoint.com/sites/an-existing-associated-site In ...
Read more

Dependency Injection in .NET

Here are some noteworthy takeaways from a course on Dependency Injection in .NET Core. DI Container Basics A container isn't a requirement but simplifies management of dependencies Services are registered at start up and resolve at runtime when they are required Container creates and disposes of instances while maintaining them for a specific lifetime Two primary interfaces for dependency injection in the .NET container IServicesCollection  - registers and configures a service IServiceProvider  - provides a mechanism for resolving a service at runtime Apply dependency via the constructor Register all services with the container Understand the service lifetimes Scoped Transient Singleton Identifying Dependencies to Register in the Container First, locate the  new  keyword usage. Is it the instance a dependency?  If a class instantiates another class whose methods are used, it's a dependency. Repeat the above approach throughout your app code (there should be code...
Read more

Git Guide

A few handy commands in one handy place. Updating .gitignore and enforcing it When you want to ignore additional files or folders, you have to update your . gitignore . After you make the additions or changes, you have to remove the cached files from the local repository, add them back, commit again to the local and push to the remote repositories: git rm -r --cached . git add . git commit -m "Ignore list update" To push the locally committed changes back to your remote repo: git push PowerShell script to sync with git This is a handy script I keep on my desktop (or an easy to find document folder) which I launch whenever I work with documents outside of a coding tool that need to be quickly pushed to Git. Write-Host 'Pushing changes to Git for my app!'; $dir = "C:\Users\username\source\repos\reponame\" Set-Location $dir Write-Output ''; Write-Output 'Adding locally...' git add . Write-Output ''; Write-Output "Committing locally....
Read more