Very unclear how to edit other (non-default) themes or add new themes

[JaneSmith]

I'm trying to use mdBook and am finding it extremely unclear how to edit other themes (aside from the default light theme) or add entirely new themes. I've read through the user guide but I don't feel like it addresses this at all.

I understand that you can run mdbook init --theme to generate the "theme" directory. I understand that you can edit files in this directory, and whatever is in here will override what mdBook uses. I can for example edit book.js to edit the theme pop-up menu, and can edit book.css to change some colours - but it only changes the default light theme.

I don't want to change the default light theme. I want to leave that as it is. What I want to do is override one of the other themes, e.g. the Rust theme. Or otherwise add a new theme entirely. And there appears to be no documentation on how to do this, or if there is then I'm missing it entirely.

I've tried adding a "theme/stylus" directory, and copying in / adding files there (e.g. "rust.styl" or "custom-theme.styl"), but it appears that any files in there are just ignored and don't override what mdBook uses. I don't know what I'm doing here.

Could I get any help with this? Thanks.

[mattico]

Hello!

All of the themes are in book.css. If you edit e.g. .light blockquote {} you're changing the style of <blockquote> in the light theme, or you can edit .rust blockquote {} to change the rust theme.

The stylus files are simply used to help generate book.css. If you want to use stylus rather than editing book.css directly:

1. Install stylus and nib: npm install -g stylus nib
2. Copy the theme/stylus directory to your theme folder
3. Change some stylus stuff
4. From your theme directory, run stylus stylus\book.styl --use nib

There isn't currently a specific configuration for adding a theme, but it's not that hard:

1. Create a copy of a theme in stylus/themes, and change the variables as you'd like
2. Add the theme to stylus/themes/index.styl (and regenerate book.css)
3. (here's the part where having a specific theme configuration would help) Now we need to add an option for the theme to the theme list. Add this JS to book.js or a JS file added to additional-js in book.toml:

var theme_list = document.getElementById('theme-list');
var theme = document.createElement('li');
theme.innerHTML = '<button class="theme" id="YOUR THEME NAME HERE">And here</button>';
theme_list.appendChild(theme);

[JaneSmith]

Thanks. That helps clear it up a lot.

[Michael-F-Bryan]

@mattico, would it be worth adding these instructions to the user guide?

[mattico]

Yes, of course. Also theme support wouldn't be that hard.