Skip to content

Commit

Permalink
docs(README): standardise with template repository
Browse files Browse the repository at this point in the history
closes #4
  • Loading branch information
sgoudham committed Jun 14, 2023
1 parent 0e368a9 commit 3844bd1
Show file tree
Hide file tree
Showing 6 changed files with 71 additions and 46 deletions.
117 changes: 71 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,80 +15,105 @@
<img src="assets/catwalk.webp"/>
</p>

## Installation
It is important to know that there are 2 ways to install this theme:

1. Install `mdbook-catppuccin` using [Cargo](https://doc.rust-lang.org/cargo/) (It comes installed with [Rust](https://rustup.rs/) by default!)
## Previews

<details>
<summary>🌻 Latte</summary>
<img src="assets/latte.webp"/>
</details>
<details>
<summary>🪴 Frappé</summary>
<img src="assets/frappe.webp"/>
</details>
<details>
<summary>🌺 Macchiato</summary>
<img src="assets/macchiato.webp"/>
</details>
<details>
<summary>🌿 Mocha</summary>
<img src="assets/mocha.webp"/>
</details>

- **Binaries** are also available if that's more your style! You can always find the latest releases [here](https://github.com/catppuccin/mdBook/releases/latest)!

2. Transfer files to your mdBook from this GitHub manually
## Installation

### Rust (Preferred)

1. Install `mdbook-catppuccin` by running `cargo install mdbook-catppuccin`
1. Install `mdbook-catppuccin` by running `cargo install mdbook-catppuccin` or download the latest [release](https://github.com/catppuccin/mdBook/releases/latest).

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

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

### Manual

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

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

3. Transfer downloaded assets to your mdBook theme directory (the default directory would be `theme/` from the mdBook root if not already specified within the `book.toml`)
3. Transfer downloaded assets to your mdBook theme directory (the default
directory would be `theme/` from the mdBook root if not already specified
within the `book.toml`)

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

```diff
[output.html]
-additional-css = []
+additional-css = ["./theme/catppuccin.css", "./theme/catppuccin-highlight.css"]
```

5. Build your mdBook using `mdbook build` and enjoy your new catppuccin flavours!
```diff
[output.html]
-additional-css = []
+additional-css = ["./theme/catppuccin.css", "./theme/catppuccin-highlight.css"]
```

## FAQ
5. Build your mdBook using `mdbook build` and enjoy your new catppuccin
flavours!

### How Can I Remove The Default mdBook Themes?
### Building Locally

Navigate to [`index.hbs (L125 - L132)`](https://github.com/catppuccin/mdBook/blob/main/src/bin/assets/index.hbs#L125-L132) and remove each theme that you do not want appearing on the mdBook
**Minimum Rust Version:** 1.63.0

For example, to remove all the default themes:

```diff
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
- <li role="none"><button role="menuitem" class="theme" id="light">{{ theme_option "Light" }}</button></li>
- <li role="none"><button role="menuitem" class="theme" id="rust">{{ theme_option "Rust" }}</button></li>
- <li role="none"><button role="menuitem" class="theme" id="coal">{{ theme_option "Coal" }}</button></li>
- <li role="none"><button role="menuitem" class="theme" id="navy">{{ theme_option "Navy" }}</button></li>
- <li role="none"><button role="menuitem" class="theme" id="ayu">{{ theme_option "Ayu" }}</button></li>
+ <li role="none"><button role="menuitem" class="theme" id="latte">{{ theme_option "Latte" }}</button></li>
+ <li role="none"><button role="menuitem" class="theme" id="frappe">{{ theme_option "Frappé" }}</button></li>
+ <li role="none"><button role="menuitem" class="theme" id="macchiato">{{ theme_option "Macchiato" }}</button></li>
+ <li role="none"><button role="menuitem" class="theme" id="mocha">{{ theme_option "Mocha" }}</button></li>
</ul>
```shell
git clone https://github.com/catppuccin/mdbook
cd mdbook
cargo build --release
```

Running `mdbook build` again should get rid of the themes appearing in the theme picker, enjoy!

### What's The Point Of This mdBook Preprocessor If I Can Just Install Everything Manually?

Arguably, it's actually better to transfer over the assets individually as you won't have to install this mdBook preprocessor.
However, the assets will _**NOT**_ be managed for you. You are in charge of upgrading/modifying the assets as you see fit. The preferred method of installation is through Rust as the pre-processor will be able to detect differences in versions of assets.
## 🙋 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: **_"How can I remove the default themes?"_**\
A:

- Navigate to
[`index.hbs (L125 - L132)`](https://github.com/catppuccin/mdBook/blob/main/src/bin/assets/index.hbs#L125-L132)
and remove the themes that you don't want. Remember to run `mdbook build` again!
- E.g. To remove all default themes:

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

## Acknowledgement

Inspiration for the `install` command came from [mdbook-admonish](https://github.com/tommilligan/mdbook-admonish) which is another great mdBook pre-processor!
Inspiration for the `install` command came from
[mdbook-admonish](https://github.com/tommilligan/mdbook-admonish) which is
another great mdBook pre-processor!

## 💝 Thanks to

- [Hamothy](https://github.com/sgoudham)
- [winston](https://github.com/nekowinston)
- [Hamothy](https://github.com/sgoudham)
- [winston](https://github.com/nekowinston)

&nbsp;
&#160;

<p align="center">
<img src="https://raw.githubusercontent.com/catppuccin/catppuccin/main/assets/footers/gray0_ctp_on_line.svg?sanitize=true" />
Expand Down
Empty file removed assets/.gitkeep
Empty file.
Binary file added assets/frappe.webp
Binary file not shown.
Binary file added assets/latte.webp
Binary file not shown.
Binary file added assets/macchiato.webp
Binary file not shown.
Binary file added assets/mocha.webp
Binary file not shown.

0 comments on commit 3844bd1

Please sign in to comment.