8

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.

enzi
  • 4,057
  • 3
  • 35
  • 53

1 Answers1

23
  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.

Yuby
  • 808
  • 7
  • 19
  • Do you know how to control the template to use within docfx.json file? Or simply replace/override the default template that gets used? – Marc Apr 17 '18 at 05:44
  • 1
    @Marc You can use "template": ["default", "_exported_templates\default"]. Here is an example: https://github.com/dotnet/docfx/blob/c73c7982cacfe53d80e793dddeb3974961e91614/Documentation/docfx.json#L66-L69 – Yuby Apr 17 '18 at 15:27
  • That I did already. But if I don't specify the -t ... argument the default template will be used. – Marc Apr 18 '18 at 06:42
  • Is the order same as the sample? The latter one will overwrite the former one in `template`. – Yuby Apr 18 '18 at 09:30
  • 1
    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. – escape-llc Jun 29 '18 at 11:37
  • @escape-llc Not sure what's the problem. It may help to open an issue with detailed reproduce steps in https://github.com/dotnet/docfx/issues/new – Yuby Jul 02 '18 at 08:09