8 releases (5 stable)

2.1.0 Nov 11, 2023
2.0.1 Oct 9, 2023
1.2.0 Oct 3, 2023
1.0.0 Sep 18, 2023
0.1.1 Aug 27, 2022

#143 in Text processing

Download history 26/week @ 2023-11-04 45/week @ 2023-11-11 36/week @ 2023-11-18 27/week @ 2023-11-25 37/week @ 2023-12-02 19/week @ 2023-12-09 53/week @ 2023-12-16 29/week @ 2023-12-23 36/week @ 2023-12-30 50/week @ 2024-01-06 18/week @ 2024-01-13 38/week @ 2024-01-20 71/week @ 2024-01-27 39/week @ 2024-02-03 63/week @ 2024-02-10 279/week @ 2024-02-17

456 downloads per month

MIT license

550KB
704 lines

Logo
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>
    

Acknowledgement

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

πŸ’ Thanks to

 

Copyright Β© 2021-present Catppuccin Org

Dependencies

~14–27MB
~377K SLoC