boozook / mdbook-svgbob

SvgBob mdbook preprocessor which swaps code-blocks with neat SVG.

Svgbob plugin for mdbook

Svgbob-based preprocessor for mdbook transform your ascii diagrams into a svg.

This renders a code-block marked bob into neat svg diagrams and inline it into the output.

Usage

Firstly add the following to your book's manifest file (usually book.toml)

[preprocessor.svgbob] # all fields by default

See config for more information.

Add some ascii graphics:

chapter_1.md

```bob
    0       3
     *-------*      +y
  1 /|    2 /|       ^
   *-------* |       |
   | |4    | |7      | ◄╮
   | *-----|-*     ⤹ +-----> +x
   |/      |/       / ⤴
   *-------*       v
  5       6      +z
```

Build your book and open:

mdbook build
open book/index.html

Config

Default preprocessor config:

[preprocessor.svgbob]
# svgbob configuration:
# doc: https://docs.rs/svgbob/latest/svgbob/struct.Settings.html
# default values: https://github.com/ivanceras/svgbob/blob/master/packages/svgbob/src/settings.rs#L29-L38
font_size = 14
font_family = "Iosevka Fixed, monospace"
fill_color = "black"
background = "transparent"               # default overridden, differs from svgbob's default
stroke_color = "var(--fg)"               # default overridden, differs from svgbob's default
stroke_width = 2.0
scale = 8.0
enhance_circuitries = true
include_backdrop = true
include_styles = true
include_defs = true
merge_line_with_shapes = false

# preprocessor configuration:
code_block = "bob"                       # render only code-blocks marked as "bob", e.g.: ```bob

All properties are optional.

See svgbob's settings doc and default values.

---

For more information about mdbook see mdbook manual, svgbob spec and editor.

Contribution

Contributions are appreciated. Don't hesitate to participate to discussions in the issues, propose new features and ask for help.

Useful hint for one-command builds crate + book:

1. add command to the manifest:

# book.toml

[preprocessor.svgbob]
command = "cargo run --manifest-path /path/to/mdbook-svgbob/Cargo.toml --quiet"

2. So then you only need to rebuild the book. Run something like this:

RUST_LOG=mdbook_svgbob=trace mdbook build

mdbook-svgbob's Issues

Maintenance?

Hi.

This crate seems to be unmaintained. Would you like to give away maintainership? I would love to at least passively maintain this, especially after bringing it up to date with the currrent mdbook version!

Please feel free to transfer this repository to me and give me write access to crates.io!

Only process code fences with a 'process' flag present

Hey, thanks for the preprocessor!

I've noticed that mdbook-graphviz requires a process flag to be present before processing them as graphviz diagrams:

```dot process
digraph {
    processed -> graph
}
```

Just as a matter of 'preprocessor hygiene', it would be really cool if mdbook-svgbob did similar! This would mean you could talk about bob documents as well as processing them as SVGs. I realise this is a breaking change though.

Cannot compile mdbook-svgbob v0.2.1(2023.07.19)

andadac@HP-BSPARK:~/repos/comprehensive-rust$ cargo install mdbook-svgbob
Updating crates.io index
Installing mdbook-svgbob v0.2.1
Updating crates.io index
Compiling proc-macro2 v1.0.66
Compiling unicode-ident v1.0.11
Compiling autocfg v1.1.0
Compiling libc v0.2.147

...

Compiling pulldown-cmark-to-cmark v10.0.4
Compiling toml v0.5.11
Compiling svg v0.12.1
Compiling mdbook-svgbob v0.2.1
error[E0277]: the trait bound Cfg: From<&toml::map::Map<std::string::String, toml::value::Value>> is not satisfied
--> /home/andadac/.cargo/registry/src/index.crates.io-6f17d22bba15001f/mdbook-svgbob-0.2.1/src/preprocessor.rs:58:42
|
58 | ... .and_then(|map| map.try_into().map_err(|err| error!("{}", err)).ok())
| ^^^^^^^^ the trait From<&toml::map::Map<std::string::String, toml::value::Value>> is not implemented for Cfg
|
= note: required for &toml::map::Map<std::string::String, toml::value::Value> to implement Into<Cfg>
= note: required for Cfg to implement TryFrom<&toml::map::Map<std::string::String, toml::value::Value>>
= note: required for &toml::map::Map<std::string::String, toml::value::Value> to implement TryInto<Cfg>

For more information about this error, try rustc --explain E0277.
error: could not compile mdbook-svgbob (bin "mdbook-svgbob") due to previous error
error: failed to compile mdbook-svgbob v0.2.1, intermediate artifacts can be found at /tmp/cargo-installWvoAmecd

---

in WSL2, after sudo-apt update, upgrade, rustup update, install mdbook done

Missing git tag for v0.2.0

Thanks for your work and the cool project! :)

I just recognized that the git tag is missing for the already on crates.io released v0.2.0 version and therefore also the precompiled binaries that you normally build and attach to a github release.

I would really appreciate this, as to fetch the binaries from the github release is a fast way to install the plugin (especially in the CI) without going through the rust compilation process.

Update dependencies

attempted to update some of the libraries in Cargo.toml to latest versions .. specifically:
[dependencies]
-mdbook = "0.3"
-svgbob = "0.4"
-svg = "0.7"
+mdbook = "0.4.18"
+svgbob = "0.6.6"
+svg = "0.10.0"

-clap = "2.33"
+clap = "3.1.18"
log = "0.4"
-env_logger = "0.7"
-semver = "0.9.0"
+env_logger = "0.9.0"
+semver = "1.0.9"

toml = "0.5"
serde = "1.0"
serde_json = "1.0"
-pulldown-cmark = "0.7"
-pulldown-cmark-to-cmark = "3.0"
+pulldown-cmark = "0.9.1"
+pulldown-cmark-to-cmark = "10.0.1"

---

errors generated:

Compiling mdbook-svgbob v0.1.1 (/home/xxx/fungiblefarm-dots/mdbook-svgbob)
error[E0432]: unresolved import pulldown_cmark_to_cmark::fmt::cmark
--> src/preprocessor.rs:70:6
|
70 | use pulldown_cmark_to_cmark::fmt::cmark;
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ no cmark in fmt

error[E0432]: unresolved import svgbob::Grid
--> src/svgbob.rs:5:5
|
5 | use svgbob::Grid;
| ^^^^^^^^^^^^ no Grid in the root

error[E0603]: module fmt is private
--> src/preprocessor.rs:70:31
|
70 | use pulldown_cmark_to_cmark::fmt::cmark;
| ^^^ private module
|
note: the module fmt is defined here
--> /home/xxx/.cargo/registry/src/github.com-1ecc6299db9ec823/pulldown-cmark-to-cmark-10.0.1/src/lib.rs:5:5
|
5 | fmt,
| ^^^

warning: use of deprecated struct clap::App: Replaced with Command
--> src/main.rs:10:12
|
10 | use clap::{App, Arg, ArgMatches, SubCommand};
| ^^^
|
= note: #[warn(deprecated)] on by default

warning: use of deprecated struct clap::SubCommand: Replaced with Command::new unless you intended the Subcommand trait
--> src/main.rs:10:34
|
10 | use clap::{App, Arg, ArgMatches, SubCommand};
| ^^^^^^^^^^

warning: use of deprecated struct clap::App: Replaced with Command
--> src/main.rs:28:5
|
28 | Ok(App::new(NAME).version(VERSION)
| ^^^

warning: use of deprecated struct clap::SubCommand: Replaced with Command::new unless you intended the Subcommand trait
--> src/main.rs:32:9
|
32 | SubCommand::with_name("supports")
| ^^^^^^^^^^

error[E0107]: this struct takes 0 lifetime arguments but 1 lifetime argument was supplied
--> src/main.rs:25:29
|
25 | pub fn init_cli() -> Result<ArgMatches<'static>> {
| ^^^^^^^^^^--------- help: remove these generics
| |
| expected 0 lifetime arguments
|
note: struct defined here, with 0 lifetime parameters
--> /home/xxx/.cargo/registry/src/github.com-1ecc6299db9ec823/clap-3.1.18/src/parse/matches/arg_matches.rs:70:12
|
70 | pub struct ArgMatches {
| ^^^^^^^^^^

Some errors have detailed explanations: E0107, E0432, E0603.
For more information about an error, try rustc --explain E0107.
warning: mdbook-svgbob (bin "mdbook-svgbob") generated 4 warnings
error: could not compile mdbook-svgbob due to 4 previous errors; 4 warnings emitted

`cargo install mdbook-svgbob` failed

Rust toolchain: 1.67.0

https://github.com/HollowMan6/mdbook-pdf/actions/runs/4134900407/jobs/7146633379

Compiling mdbook-svgbob v0.2.1
error[E0277]: the trait bound `Cfg: From<&toml::map::Map<std::string::String, toml::value::Value>>` is not satisfied
  --> /Users/runner/.cargo/registry/src/github.com-1ecc6299db9ec823/mdbook-svgbob-0.2.1/src/preprocessor.rs:58:38
   |
58 | ...                   .and_then(|map| map.try_into().map_err(|err| error!("{}", err)).ok())
   |                                       ^^^ -------- required by a bound introduced by this call
   |                                       |
   |                                       the trait `From<&toml::map::Map<std::string::String, toml::value::Value>>` is not implemented for `Cfg`
   |
   = note: required for `&toml::map::Map<std::string::String, toml::value::Value>` to implement `Into<Cfg>`
   = note: required for `Cfg` to implement `TryFrom<&toml::map::Map<std::string::String, toml::value::Value>>`
   = note: required for `&toml::map::Map<std::string::String, toml::value::Value>` to implement `TryInto<Cfg>`

For more information about this error, try `rustc --explain E0[277](https://github.com/HollowMan6/mdbook-pdf/actions/runs/4134900407/jobs/7146633379#step:6:278)`.
error: could not compile `mdbook-svgbob` due to previous error

Error: The "svgbob" preprocessor exited unsuccessfully with exit status: 1 status

I had this working earlier on a very basic mdbook, then I added a bunch of content and now I'm stuck here -- beginning investigation, and will post as I try.

repo is here:
https://github.com/elasticdotventures/fungiblefarm-dots

2022-06-08 14:46:33 [INFO] (mdbook::book): Book building has started
[2022-06-08T04:46:33Z ERROR mdbook_svgbob] Unable to parse the input
2022-06-08 14:46:33 [WARN] (mdbook::preprocess::cmd): Error writing the RenderContext to the backend, Broken pipe (os error 32)
2022-06-08 14:46:33 [ERROR] (mdbook::utils): Error: The "svgbob" preprocessor exited unsuccessfully with exit status: 1 status

Diagrams don't use theme colors

I got a PR from @nofurtherinformation to fix the diagram colors when a dark theme is used in mdbook: google/comprehensive-rust#48.

The problem is that the diagrams use black as the text color — even when the background color is very dark.

The fix is simply to include a style sheet with

svg text {
  fill: var(--fg);
}

I'm not sure where the right place is to add such a CSS rule since mdbook-svgbob is a preprocessor. Perhaps it could be a style="fill: var(--fg)" attribute instead somewhere on the generated SVG?