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

Question

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.

Animal

Answer 1

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.

Correctitude

Do you know how to control the template to use within docfx.json file? Or simply replace/override the default template that gets used? – Hickox

@Hickox You can use "template": ["default", "_exported_templates\default"]. Here is an example: github.com/dotnet/docfx/blob/… – Correctitude

That I did already. But if I don't specify the -t ... argument the default template will be used. – Hickox

Is the order same as the sample? The latter one will overwrite the former one in template. – Correctitude

I'm using 2.36.2 and the only way i could make it work was export, edit-in-place, and use the -t option with that folder. The site says you should copy only changed files, but that doesn't appear to work. – Tor

@Tor Not sure what's the problem. It may help to open an issue with detailed reproduce steps in github.com/dotnet/docfx/issues/new – Correctitude

Answer 2

By setting "template" docfx.json, the last templates override the first ones if the file name inside the template matches. Therefore, it is enough to create a new folder for your template, copy the changed files into it, adhering to the folder structure of the original template. Include the custom template in the config file. The "default" template is required. Look at the example template default(zh-cn)

Abrams