Typedoc: CSS overrides don't seem to be taking effect when creating custom themes

[crhistianramirez]

• [x] I have checked issues with bug label and found no duplicates

Expected Behavior

I would expect adding the path to a saas file in my custom themes directory would allow me to override some styles like it lets me override html by providing the path to a handlebars file.

Specifically I'm updating css in:
assets/css/layouts/_default.saas

Actual Behavior

No style changes are observed. It uses the same css

Steps to reproduce the bug

1. Create a theme directory
2. Add assets/css/layouts/_default.saas to it
3. Update styles in this file
4. generate output by calling typedoc path/to/src --theme path/to/custom-theme-directory
5. Observe no style changes from the file in step two are taking effect

Environment

• Typedoc version: 0.15.0
• Node.js version: 10.16.0
• OS: windows

[Gerrit0]

I'm not sure how TypeDoc would know to import _default.saas (also, shouldn't it be .sass?).

Unfortunately there isn't a way to directly include just extra CSS right now. Forking the default theme repo and modifying the theme inside it is probably your best bet.

[crhistianramirez]

Hi, thanks for your reply :)

Forking the default theme repo and modifying the theme inside it is probably your best bet.

That's sort of what I did, sorry if it wasn't very clear. I grabbed all the contents of this folder: https://github.com/TypeStrong/typedoc-default-themes/tree/master/src/default and stuck it in my project. Then called the cli with the path to that folder after modifying the _default.saas file. Am I missing something? Should I fork the entire thing and not just the default branch? A little surprised about how changes to mustache templates seem to be working though.

also, shouldn't it be .sass?
I'm not sure what you mean here. I marked the extension as .saas

[aciccarello]

@crhistianramirez You can definitely have a repo that only has one theme. With the default themes, there is a build process which creates the final files (the sass needs to be compiled for it to be used. Can you share the theme code you are working on?

[crhistianramirez]

@aciccarello thank you for your attention. Here's a minimal reproducible example

Steps to recreate:

1. git clone https://github.com/crhistianramirez/typedocs-styles-repro
2. cd typedocs-styles-repro
3. npm install
4. npm run repro to generate the docs
5. open the globals.html file
   
   
   
   • windows: start docs/globals.html
   
   
   • mac: open docs/globals.html
   
   

I made two overrides in custom-themes:

• added partials/index.html and changed the text Index to CUSTOM_TEXT_ADDED_HERE
• added assets folder as described in the custom theme guide and then changed the last line in custom-theme/assets/css/layouts/_default.saas which should update the breadcrumb separator to /CUSTOM_BREADCRUMB_SEPARATOR

The only change that I see is for the update to the handlebars file. I would expect my override to the saas file would also take place. Doesn't handlebars have to get compiled as well?

[Gerrit0]

I'm not sure what you mean here. I marked the extension as .saas

saas != sass

---

Thanks for the repro. I pulled it down and now that I see what you are doing, it makes sense to me.

TypeDoc compiles the handlebars templates at documentation-time because each project is different, however the sass files don't change from project to project, so they are compiled before the theme is published. This makes it possible to gain a not-insignificant speed boost when rendering docs and removes the need to bundle a sass compiler.

If you want to use some custom sass, you'll need to compile it yourself before passing it off to TypeDoc. If you compile to custom-theme/assets/css/main.css, you will replace the default styles.

[crhistianramirez]

saas != sass

oops! 🤦‍♂

If you want to use some custom sass, you'll need to compile it yourself

I don't particularly care to use sass, I just thought that was the route I had to take to have custom styles. Is there a simpler way of providing custom styles that would allow me to avoid having to compile sass to css?

[Gerrit0]

Yes, just create custom-theme/assets/css/main.css.

---

There isn't a built in way to just include some extra CSS. You could follow the above use, but then you'll remove all the default styling. If you don't want to do this you can create custom-theme/layouts/default.hbs with the default text and add <link rel="stylesheet" href="{{relativeURL "assets/css/custom.css"}}">, then adding custom-theme/assets/css/custom.css should let you include some custom CSS without overwriting the default.

[crhistianramirez]

Beautiful! Thank you so much for your help. I think it might be a good idea to add that to the theme guide. I will make a PR and tag you if that's ok

[crhistianramirez]

@Gerrit0 link to docs update PR: https://github.com/TypeStrong/typedoc-site/pull/19

[KarishmaGhiya]

Thank you @Gerrit0 and @crhistianramirez . I stumbled upon this discussion while going through the exact same issue. It is probably a good idea to merge this PR soon to update the docs