catppuccin/mdbook

🎊 Soothing pastel theme for mdBook

Catppuccin for mdBook

Previews

🌻 Latte

🪴 Frappé

🌺 Macchiato

🌿 Mocha

Usage

1. Install the binary using one of the methods below.

   Installation Method	Instructions
   Rust	cargo install mdbook-catppuccin
   Homebrew	brew install catppuccin/tap/mdbook-catppuccin
   Nix	nix profile install github:catppuccin/mdbook
   GitHub	Download the latest release
   Manual	See below

2. Navigate to your mdBook's root directory (same location where the book.toml lives) and run mdbook-catppuccin install

3. Build using mdbook build and enjoy your new catppuccin flavours!

Manual Installation

1. Navigate to src/bin/assets within this repository

2. Download all assets: index.hbs, catppuccin.css and catppuccin-admonish.css

   [!NOTE] The catppuccin-admonish.css file is NOT required if you are not using the mdbook-admonish plugin.

3. Transfer downloaded assets to your mdBook's theme directory (the default directory is ./theme beside book.toml)

4. Update additional-css key within the book.toml as shown below

   [output.html]
   -additional-css = []
   +additional-css = ["./theme/catppuccin.css", "./theme/catppuccin-admonish.css"]

5. Build using mdbook build and enjoy your new catppuccin flavours!

Version Compatibility

This table shows the compatibility between the mdBook version and the mdbook-catppuccin version.

Important

Updates to the major version may contain BREAKING CHANGES to the index.hbs file, which means that you will have to update the file manually or use mdbook-catppuccin install --force flag to overwrite the index.hbs upon installation.

mdbook-catppuccin	mdBook
1.x.x	0.4.22 → 0.4.34
2.x.x	0.4.35 → latest

Development

1. Clone the repository and navigate to the repository root.

   git clone https://github.com/catppuccin/mdbook
   cd mdbook

2. Run the following command to generate the CSS files that will be packaged by the rust binary:

   cd palette
   npm install
   npm run build

3. Build the rust binary using the following command:

   Note that the Minimum Rust Version is 1.63.0

   cargo build --release

4. Test the binary by installing the new assets on the example directory:

   cd example
   ../target/release/mdbook-catppuccin install
   mdbook serve

🙋 FAQ

• Q: "What's the point of the mdbook-catppuccin binary?"
  A: Arguably, it's better to transfer over the files manually to avoid installing another tool. However, the assets will NOT be managed for you. It is also worth mentioning that the binary will be able to detect differences in versions of assets.

• Q: "What's the catppuccin-admonish.css file?"
  A: It is a CSS file that is used to style the admonishments that are generated by mdbook-admonish. You can remove this file if you are not using this plugin.

  E.g.

  [output.html]
  - additional-css = ["./theme/catppuccin.css", "./theme/catppuccin-admonish.css"]
  + additional-css = ["./theme/catppuccin.css"]

• Q: "How can I remove the default themes?"
  A: Navigate to index.hbs (L154 - L162) and remove the themes that you don't want. Remember to run mdbook build again!

  E.g. To remove all default themes:

  - <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
  - <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
  - <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
  - <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
  - <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
  + <li role="none"><button role="menuitem" class="theme" id="latte">Latte</button></li>
  + <li role="none"><button role="menuitem" class="theme" id="frappe">Frappé</button></li>
  + <li role="none"><button role="menuitem" class="theme" id="macchiato">Macchiato</button></li>
  + <li role="none"><button role="menuitem" class="theme" id="mocha">Mocha</button></li>

  Additionally, you can use default-theme and preferred-dark-theme keys for setting default light/dark mode themes.

  E.g. To set the default theme to latte and default dark mode to mocha:

  [output.html]
  + default-theme = "latte"
  + preferred-dark-theme = "mocha"

Acknowledgement

Inspiration for the install command came from mdbook-admonish which is another great mdBook pre-processor!

💝 Thanks to

• Hamothy
• winston

 

Copyright © 2021-present Catppuccin Org

mdbook's Issues

Add developer documentation

What

Documentation for other developers wanting to contribute should be included.

Why

We want the repository to be as accessible as possible for developers looking to contribute. Contributing shouldn't require pre-requisite knowledge of all of the rust, so we should be kind and detail the commands needed.

Acceptance Criteria

- [ ] Add Contributing section in the current README.md
- [ ] Thank the user for looking to contribute to the repository
- [ ] Link off to the current contributing guidelines defined in Catppuccin's .github repository

• Add Building Locally section in the current README.md
  • Instructions for building locally are clearly defined
  • Make sure to specify versions of mdbook and rust used

The instructions for building locally are as follows:

Building Locally

1. Install the latest version of rust on your preferred choice of operating system, we recommend
   using rustup.

2. Clone the repository

   git clone https://github.com/catppuccin/mdBook

3. Navigate to root directory

   cd mdBook

4. Build the binary!

   cargo build --release

Add a reminder on README for those who want to replace all the built-in themes

In the mdBook documentation there's a reminder for those who want to replace all the built-in themes:

"If you completely replace all built-in themes, be sure to also set output.html.preferred-dark-theme in the config, which defaults to the built-in navy theme."

I suggest adding the same reminder to the 'How can I remove the default themes?' section in the FAQ.

Additionally, 'default-theme' isn't mentioned, but perhaps it should also be set to new values alongside 'preferred-dark-theme'?

Here's how I set them for my project:

[output.html]
default-theme = "latte"
preferred-dark-theme = "mocha"

I would like to take this opportunity to thank everyone for the great work on this repository.

How to set theme rust as default theme?

Add a .catppuccin.yaml

It seems you don't have a .catppuccin.yaml. Please create one. Thanks! (This issue was auto-generated)

Add a .catppuccin.yaml

It seems you don't have a .catppuccin.yaml. Please create one. Thanks! (This issue was auto-generated)

code block missing background

I've updated to the new css and it improves json highlighting, but the background is now gone (with the exception of Latte).
Is this intentional?

before

after:

Add example mdBook to show off colourscheme

What

An example mdbook should live in the root directory of the repository. This book should also be deployed under GitHub Pages.

Why

Providing a visual preview of the colour scheme will significantly enhance the user experience and offer easy access to the latest version of the extension. We should use the domain mdbook.catppuccin.com

Acceptance Criteria

• Example mdBook created with pages showcasing different types of highlights (headings, paragraphs, codeblocks etc)
• GitHub Actions workflow for deploying to GitHub Pages
• Page deployed under mdbook.catppuccin.com

cargo install failure

Running cargo install mdbook-catppuccin or cargo install --git https://github.com/catppuccin/mdBook will result to an error E0432

Output from running the command with just

   Compiling hyper v0.14.27
   Compiling warp v0.3.5
   Compiling mdbook v0.4.32
   Compiling mdbook-catppuccin v0.2.0
error[E0432]: unresolved import `clap::crate_version`
 --> /root/.cargo/registry/src/index.crates.io-6f17d22bba15001f/mdbook-catppuccin-0.2.0/src/bin/mdbook-catppuccin.rs:3:12
  |
3 | use clap::{crate_version, Arg, ArgMatches, Command};
  |            ^^^^^^^^^^^^^ no `crate_version` in the root

error: cannot determine resolution for the macro `crate_version`
  --> /root/.cargo/registry/src/index.crates.io-6f17d22bba15001f/mdbook-catppuccin-0.2.0/src/bin/mdbook-catppuccin.rs:29:18
   |
29 |         .version(crate_version!())
   |                  ^^^^^^^^^^^^^
   |
   = note: import resolution is stuck, try simplifying macro imports

For more information about this error, try `rustc --explain E0432`.
error: could not compile `mdbook-catppuccin` (bin "mdbook-catppuccin") due to 2 previous errors
error: failed to compile `mdbook-catppuccin v0.2.0`, intermediate artifacts can be found at `/tmp/cargo-installj2MPyu`
error: Recipe `get-deps-book` failed on line 38 with exit code 101

Add highlight overrides for mdbook-admonish

What

Highlight overrides for all types of admonishments included within mdbook-admonish should be added

Why

We want to improve the user experience when the user chooses to use other popular mdbook preprocessors, enabling good highlighting support will be more visually appealing for the user.

Acceptance Criteria

All items referenced here have good highlight overrides relevant to the catppuccin theme

docs: mention homebrew & Nix flake

We should mention https://github.com/catppuccin/homebrew-tap and the flake.nix as installation methods, since both are using bottles/cachix now.

Does mdbook-catppuccin add help version info

E.g:

➜  mdbook-catppuccin -V
mdbook-catppuccin 0.1.1
➜  

Right now, cli not show version help:

➜  mdbook-catppuccin -h
mdbook-catppuccin
A mdbook preprocessor that implements catppuccin flavours as default themes

USAGE:
    mdbook-catppuccin [SUBCOMMAND]

OPTIONS:
    -h, --help    Print help information

SUBCOMMANDS:
    help        Print this message or the help of the given subcommand(s)
    install     Install the necessary files needed and update the config to include them
    supports    Check whether a renderer is supported by this preprocessor
➜ 

Like mdbook cli:

➜  mdbook -V
mdbook v0.4.15
➜  

How to use custom themes to make bold fonts change color

I want to use a custom theme to make the *title* modified font bold and change color,
Title
because there are a lot of places to use, so I don't want to use in markdown syntax.
please tell me how to do it? There is a lack of instructions here.

How to totally uninstall catppuccin

I was trying to use catppuccin, it looks good on desktop web broswer. But somehow it was having issue on mobile broswer (tried on safari and chrome, side bar is not populating all the items). So i tried to uninstall catppuccin (just force reset commit version and uninstall catppuccin with cargo uninstall mdbook-catppuccin then mdbook build, but it's causing some other issues:

1. When I push my reverted changes to github it's running fine with default themes. But locally it's not loading default theme list and the default style looks weird as below

2. The categories in side bar can not be fold or expanded when clicking on arrows.

I tried to re-install rust entirely for cleaning the whole environment, and create new mdbook, but still it's not working properly on my local.. Just curious is there any solution to recover it ? Thanks