Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/badboy/mdbook-open-on-gh

mdbook preprocessor to add a open-on-github link on every page
https://github.com/badboy/mdbook-open-on-gh

Last synced: 9 days ago
JSON representation

mdbook preprocessor to add a open-on-github link on every page

Host: GitHub
URL: https://github.com/badboy/mdbook-open-on-gh
Owner: badboy
License: mpl-2.0
Created: 2020-01-30T09:56:35.000Z (almost 5 years ago)
Default Branch: main
Last Pushed: 2024-05-13T12:11:57.000Z (8 months ago)
Last Synced: 2024-12-24T02:01:28.458Z (12 days ago)
Language: Rust
Size: 256 KB
Stars: 29
Watchers: 3
Forks: 9
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# mdbook-open-on-gh

A preprocessor for [mdbook][] to add a open-on-github link on every page.

[mdbook]: https://github.com/rust-lang/mdBook

It adds an "Edit this file on GitHub" link on the bottom of every page, linking directly to the source file.
It uses the configured `git-repository-url` as the base.

## Installation

If you want to use only this preprocessor, install the tool:

```
cargo install mdbook-open-on-gh
```

Add it as a preprocessor to your `book.toml`:

```
[preprocessor.open-on-gh]
command = "mdbook-open-on-gh"
renderer = ["html"]
```

## Configuration

`mdbook-open-on-gh` is configured using additional options under `[output.html]`:

```toml
[output.html]
# Required: Your repository URL used in the link.
git-repository-url = "https://github.com/$user/$project"

# Your git branch. Defaults to `main`
git-branch = "main"

# The text to use in the footer.
# The link text is marked by `[]`
open-on-text = "Found a bug? [Edit this page on GitHub.]"
```

To style the footer add a custom CSS file for your HTML output:

```toml
[output.html]
additional-css = ["open-in.css"]
```

And in `open-in.css` style the `` element or directly the CSS element id `open-on-gh`:

```css
footer {
font-size: 0.8em;
text-align: center;
border-top: 1px solid black;
padding: 5px 0;
}
```

This code block shrinks the text size, center-aligns it under the rest of the content
and adds a small horizontal bar above the text to separate it from the page content.

Finally, build your book as normal:

```
mdbook path/to/book
```

## License