Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/geckoeidechse/mdbook-gitbook
mdBook preprocessor to render GitBook specific syntax
https://github.com/geckoeidechse/mdbook-gitbook
gitbook mdbook mdbook-preprocessor rust
Last synced: 7 days ago
JSON representation
mdBook preprocessor to render GitBook specific syntax
- Host: GitHub
- URL: https://github.com/geckoeidechse/mdbook-gitbook
- Owner: GeckoEidechse
- License: mpl-2.0
- Created: 2024-01-30T16:47:03.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-04-22T11:23:13.000Z (8 months ago)
- Last Synced: 2024-04-22T12:40:21.778Z (8 months ago)
- Topics: gitbook, mdbook, mdbook-preprocessor, rust
- Language: Rust
- Homepage: https://crates.io/crates/mdbook-gitbook
- Size: 1.3 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# mdbook-gitbook
[](https://crates.io/crates/mdbook-gitbook)
[](LICENSE)
[](https://docs.rs/mdbook-gitbook)
[](https://github.com/GeckoEidechse/mdbook-gitbook/actions/workflows/build.yml)
[](https://github.com/GeckoEidechse/mdbook-gitbook/actions/workflows/test.yml)
[mdBook](https://github.com/rust-lang/mdBook) preprocessor to properly render [GitBook](https://www.gitbook.com/) specific syntax in mdBook.
You can compare this preprocessor to GitBook by looking at the same sample book on:
- [GitBook](https://mdbook.gitbook.io/mdbook-gitbook/)
- [mdBook](https://geckoeidechse.github.io/mdbook-gitbook/) (via GitHub pages)
To see the list of existing and supported syntax, see [this GitHub issue](https://github.com/GeckoEidechse/mdbook-gitbook/issues/1).
> **Note:**
>
> This mdBook preprocessor was written for local rendering of the [NorthstarWiki](https://github.com/R2Northstar/NorthstarWiki/) where it covers the majority of the used GitBook-specific syntax.
> As such I'm not planning to add support for more GitBook widgets etc, however contributions to expand the supported syntax are more than welcome <3
>
> Similarly, if you'd like to take over maintainership or ownership of this crate, please get in touch via an issue in the GitHub repo of this crate.
## Usage
First, install the preprocessor:
```bash
cargo install mdbook-gitbook
```
Then, add the preprocessor to your `book.toml`:
```toml
[book]
authors = ["Jill Doe"]
language = "en"
multilingual = false
src = "src"
title = "My awesome Book"
# ADD THIS
[preprocessor.gitbook]
```
## Development
### How it works
The way this preprocessor works is primarily by using regexes to search for specific patterns like
```
{% embed url="URL_HERE" %}
```
and then replacing it with the corresponding HTML code like
```html
```
### Expanding the preprocessor
The currently supported syntax is tracked in [this GitHub issue](https://github.com/GeckoEidechse/mdbook-gitbook/issues/1)
To add support for some currently unsupported syntax, expand the existing existing main render loop in `lib.rs`
```rust
/// Apply to all chapters
fn handle_chapter(chapter: &mut Chapter) -> Result<(), Error> {
chapter.content = hints::render(&chapter.content)?;
chapter.content = embeds::render(&chapter.content)?;
chapter.content = content_refs::render(&chapter.content)?;
// Add your additional syntax parsing here
Ok(())
}
```
with a function that calls the corresponding parsing logic.
In your parsing logic, use regex or any other methods to scan for the specific pattern of the syntax you want to support and replace it with the corresponding HTML code.