documentation-generationdocfx

How can I customize Docfx documentation (themes or templates)?


I just started using Docfx and set up some basic conceptual documentation. Now I want to make some adjustments to the theme (company logo, perhaps some font changes, etc.) Minor stuff.

The official documentation only gives a high-level description of how to create a new template. I've never used a templating language before, so I'd like to avoid that for now if possible.

My question is: how can I make small adjustments to the default theme, like some CSS changes and perhaps adding external resources (like font awesome)?

Do I have to create an entire template (or a part of it) or can I include a CSS file somehow? The documentation mentions a theme option but so far I've found no examples or existing themes to learn from.

A mere link to a project that uses a custom theme or template would already be very helpful. The docfx repo has a docfx.website.themes folder and the default template is also in there I believe, but I couldn't really figure out which files I would have to provide to roll my own.


Solution

    1. Export template:
      • Run docfx template export default, then you'll see default template in _exported_templates\default
    2. Change themes in default template, e.g:
      • Adding external resource: modify styles\head.tmpl.partial
      • CSS change: modify styles\docfx.css or styles\main.css
    3. Use customized template:
      • Run docfx -t _exported_templates\default, which will use your customized template!

    NOTE: It is possible that DocFX updates its embedded templates when releasing new version. So please make sure to re-export the template if you overwrite or dependent on that template in your custom template.