3.5 Other notes

3.5.1 Multilingual books

For an example of a multilingual book setup, say English and Chinese, see https://juliadatascience.io.

3.5.2 Footnotes

Footnotes can be added via regular Markdown syntax:

Some sentence[^foot].

[^foot]: Footnote text.

Some sentence2.

3.5.3 Show

When your method returns an output type T which is unknown to Books.jl, it will be passed through show(io::IO, ::MIME"text/plain", object::T). So, if the package that you’re using has defined a new show method, this will be used. For example, for a grouped DataFrame:

groupby(DataFrame(; A=[1]), :A)
GroupedDataFrame with 1 group based on key: A
Group 1 (1 row): A = 1
 Row │ A
     │ Int64
   1 │     1

3.5.4 Note box

To write note boxes, you can use

> **_NOTE:_**  The note content.

NOTE: The note content.

This way is fully supported by Pandoc, so it will be correctly converted to outputs such as PDF.

3.5.5 Advanced sco options

To enforce output to be embedded inside a code block, use scob. For example,

df = DataFrame(A = [1], B = [Date(2018)])
df = DataFrame(A = [1], B = [Date(2018)])

1×2 DataFrame
 Row │ A      B
     │ Int64  Date
   1 │     1  2018-01-01

or, with a string

s = "Hello"


Another way to change the output is via the keyword arguments pre, process and post for sco. The idea of these arguments is that they allow you to pass a function to alter the processing that Books.jl does. pre is applied before Books.convert_output, process is applied instead of Books.convert_output and post is applied after Books.convert_output. For example, to force books to convert a DataFrame to a string instead of a Markdown table, use:

s = "df = DataFrame(A = [1], B = [Date(2018)])"
sco(s; process=string, post=output_block)

which shows the following to the reader:

df = DataFrame(A = [1], B = [Date(2018)])
1×2 DataFrame
 Row │ A      B
     │ Int64  Date
   1 │     1  2018-01-01

Without process=string, the output would automatically be converted to a Markdown table by Books.jl and then wrapped inside a code block, which will cause Pandoc to show the raw output instead of a table.

df = DataFrame(A = [1], B = [Date(2018)])
|   A |          B |
| ---:| ----------:|
|   1 | 2018-01-01 |

Without post=output_block, the DataFrame would be converted to a string, but not wrapped inside a code block so that Pandoc will treat is as normal Markdown:

df = DataFrame(A = [2], B = [Date(2018)])

Options(1×2 DataFrame Row │ A B │ Int64 Date ─────┼─────────────────── 1 │ 2 2018-01-01, missing, nothing, nothing, missing)

This also works for @sco. For example, for my_data we can use:

@sco process=string post=output_block my_data()

which will show as:

function my_data()
    DataFrame(A = [1, 2], B = [3, 4], C = [5, 6], D = [7, 8])
2×4 DataFrame
 Row │ A      B      C      D
     │ Int64  Int64  Int64  Int64
   1 │     1      3      5      7
   2 │     2      4      6      8

3.5.6 Fonts

The code blocks default to JuliaMono in HTML and PDF. For the HTML, this package automatically handles JuliaMono. However, for the PDF, this just doesn’t work out (see, e.g., 257). To get JuliaMono to work with the PDF build, install it globally. See the instructions at the JuliaMono site. On Linux, you can use Books.install_extra_fonts(), but beware that it might override user settings.

Ligatures from JuliaMono are disabled. For example, none of these symbols are combined into a single glyph.

|> => and <=

3.5.7 Long lines in code blocks

When code or output is getting too long, a horizontal scrollbar is visible on the website to scroll horizontally and a red arrow is visible in the PDF.

3.5.8 Code blocks in lists

To embed code blocks inside lists, indent by 3 spaces and place an empty line before and after the code block. For example, this will show as:

  1. This is a list item with some code and output:

    x = 2 + 1
  2. And the list continues

    • with an example on the third level:

      x = 3 + 1
    • another third level item

    • and another

CC BY-NC-SA 4.0 Rik Huijzer, and contributors