mdBook Pikchr

A mdBook preprocessor to render Pikchr code blocks as images in your book.

Taken from the Pikchr homepage:

Pikchr (pronounced like "picture") is a PIC-like markup language for diagrams in technical documentation. Pikchr is designed to be embedded in fenced code blocks of Markdown (or in similar mechanisms in other markup languages) to provide a convenient means of showing diagrams.

This crate use builtin copy of the pikchr.c file downloaded from that website.

How it's work

Installation

Install it via cargo:

$ cargo install mdbook-pikchr

Configuration

Just type next line in your book.toml file:

[preprocessor.pikchr]

Source code

Source code available on GitHub.

Demos

Several demos illustrating the work of the preprocessor are presented.

Diagram

The diagram:

Is generated by 7 lines of Markdown:

```pikchr
arrow right 200% "Markdown" "Source"
box rad 10px "Markdown" "Formatter" "(mdbook)" fit
arrow right 200% "HTML+SVG" "Output"
arrow <-> down 70% from last box.s
box same "Pikchr" "Preprocessor" "(mdbook-pikchr)" fit
```

Error

The error will be output:

box "hello" "pikchr

/*    1 */  box "hello" "pikchr
                       ^^^^^^^^
ERROR: unrecognized token

Configuration

The preprocessor.pikchr table used for preprocessor configuration.

Supported variables:

Here is an example of what a book.toml file might look like:

[book]
title = "Example book"
authors = ["John Doe"]
description = "The example book covers examples."

[preprocessor.pikchr]
align = "left"

Alignment

Global

By default, the generated images appears centered.

You can change default behavior by setting the variable align in table preprocesso.pikchr at your book.toml file .

If you would prefer that the pictures be left-justifed, put the value "left".

If you would prefer that the pictures be right-justifed, put the value "right".

The value "center" also possible, but it will do nothing.

Per-picture

Additionaly you can control alignment for individual picture by adding similar keyword after the pikchr class tag. Thus:

```pikchr,left
box "left" radius 10px fill white
```

Results in the following:

Then:

```pikchr,center
box "center" radius 10px fill white
```

Results in the following:

And:

```pikchr,right
box "right" radius 10px fill white
```

Reults in the following: