mdbook-scientific

Crates.iomdbook-scientific
lib.rsmdbook-scientific
version0.5.0-beta.3
sourcesrc
created_at2022-09-23 13:04:29.214497
updated_at2023-01-17 11:12:31.92499
descriptionEnables inline equations for mdbook to set by $..$ signs and $$..$$
homepage
repositoryhttps://github.com/drahnr/mdbook-scientific
max_upload_size
id672491
size100,590
rust-libp2p Maintainers (github:libp2p:rust-libp2p-maintainers-old)

documentation

README

Scientific mdbook plugin

This plugin adds functionality to mdbook for scientific application.

It allows the writer to generate named LaTeX, named Gnuplots and supports bibtex files. Further cross-referencing in text to equation, figures or literature is possible. A sample output can be seen here.

Install

Compile this crate and add the mdbook-scientific to your search path. Also bib2xhtml is required if you want to generate a bibliography. Then add the following to your book.toml:

[preprocessor.scientific]
renderer = ["html"]

bibliography = "literature.bib"
bib2xhtml = "/home/lorenz/Documents/tmp/bib2xhtml/"

assets = "src/"

[output.html]
additional-css = ["src/scientific.css"]

Prerequisites

  • Formulae and general latex rendering latex and dvisvgm
  • Graphs require gnuplot

Syntax

For block equation rendering use the following syntax

$$equation, <name>
...
$$

the equation identifier is only needed if you want to name the equation block. You can cross-reference it then with $ref:equ:<name>$ in the whole mdbook.

The same syntax is working with latex and gnuplot figures, both are requiring a subtitle for the plot. Further a gnuplotonly figure only uses Gnuplot to render the file to SVG.

Example for gnuplot rendering

$$gnuplot, <name>, <subtitle>
...
$$

and then cross-reference with $ref:fig:<name>$.

If block is empty, then the preprocessor looks into the assets path specified in the configuration. So for a block $$latex, legendrepoly, Legendre Polynomials$$ it looks for the file src/legendrepoly.tex.

The BibTeX file referenced in the configuration file is added as a additional chapter and citations can be generated with $ref:bib:<name>$.

Stability / Viability

Proof of concept, with the following outstanding urgent todos for practical viability:

  • handle $ signs in code blocks
  • migrate to a full markdown parser rather than impl heuristics
  • remove dependencies on host binaries as much as possible
Commit count: 50

cargo fmt