exaclior / books.jl

Create books with Julia

Books.jl

Create books with Julia

In a nutshell, this package is meant to generate books (or reports or dashboards) with embedded Julia output. Via Pandoc, the package can live serve a website and build various outputs including a website and PDF. For many standard output types, such as DataFrames and plots, the package can run your code and will automatically handle proper embedding in the output documents, and also try to guess suitable captions and labels. Also, it is possible to work via the live server, which shows changes within seconds.

This package assumes that:

• the user is comfortable with managing two REPLs,
• the user wants to run Julia code and embed the output in a book,
• the book (website and PDF) is built via CI, and
• Markdown sections and subsections (level 2) should be numbered and listed in the HTML menu.

The reason that numbering of sections is always assumed is to allow the book to be printed. Without section numbers, it is difficult to refer to other parts of the book.

If you do not want numbered sections, but instead a more dynamic website with links, then checkout Franklin.jl or my template repository for Franklin with Pluto. If you want a small report instead of a book with numbered sections, then Weave.jl might be more suitable for your problem.

This package is used to create the Julia Data Science book.

Usage

To install this package (Julia 1.6/1.7/1.8 on MacOS/Linux), use

pkg> add Books

See, the documentation for more information.

Windows

Currently, this package (probably) does not work on Windows. This seems to be due to differences in maximum file path lengths. I have to look into it a bit more to fix it, but it's not a priority for me.

Getting help

If you run into problems when using this package, feel free to open an issue here at GitHub or click this link to ask a question at Discourse. For short questions, feel free to send me a PM at https://julialang.zulipchat.com/.