## 5.1. Introduction¶

All additional information, used to specify how a particular notebook/cell/output will be represented, when converted, is stored in the metadata under:

{
"ipub": {}
}


There are three levels of metadata:

• For notebook level: in the Jupyter Notebook Toolbar go to Edit -> Edit Notebook Metadata

• For cell level: in the Jupyter Notebook Toolbar go to View -> Cell Toolbar -> Edit Metadata and a button will appear above each cell.

• For output level: using IPython.display.display(obj,metadata={"ipub":{}}), you can set metadata specific to a certain output. Options set at the output level will override options set at the cell level. For an example of this, see Multiple Outputs from a Single Code Cell.

Important

setting a value to "value":{} is the same as "value":false so, if you are not setting additional options, use "value":true.

## 5.2. Document Level¶

The full schema can be viewed at Document Level Metadata Schema.

### 5.2.1. Language¶

To change the language of the document:

{
"ipub": {
"language" : "french"
}
}


where the language can be any specified in the babel package.

### 5.2.2. Bibliography¶

To specify where the bibliography is and choose a style:

{
"ipub": {
"bibliography" : "path/to/bibliograph.bib",
"bibstyle": "unsrtnat",
"biboptions": ["super", "sort"],
}
}

• The path can be absolute or relative.

• The bibstyle must be a natbib stylename

New in version 0.7.1:
• The biboptions is a list of options to parse to natbib. The default is: [“numbers”, “square”, “super”, “sort&compress”], and some common options are:

• round: (default) for round parentheses;

• square: for square brackets;

• curly: for curly braces;

• angle: for angle brackets;

• colon: (default) to separate multiple citations with colons;

• comma: to use commas as separators;

• authoryear: (default) for author-year citations;

• numbers: for numerical citations;

• super: for superscripted numerical citations, as in Nature;

• sort: orders multiple citations into the sequence in which they appear in the list of references;

• sort&compress: as sort but in addition multiple numerical citations are compressed if possible (e.g. 3-6, 15);

• longnamesfirst: makes the first citation of any reference the equivalent of the starred variant (full author list) and subsequent citations normal (abbreviated list);

### 5.2.3. Title Page¶

For titlepage, enter in notebook metadata:

{
"ipub": {
"titlepage": {
"author": "Authors Name",
"email": "authors@email.com",
"supervisors": [
"First Supervisor",
"Second Supervisor"
],
"title": "Main-Title",
"subtitle": "Sub-Title",
"tagline": "A tagline for the report.",
"institution": [
"Institution1",
"Institution2"
],
"logo": "path/to/logo_example.png"
}
}
}

• all keys are optional

• if there is no title, then the notebook filename will be used

• if nbpublish.py is called on a folder, then the meta data from the first notebook will be used

• logo should be the path (absolute or relative) to a logo image file

### 5.2.4. Contents Tables¶

To control the output of contents tables:

{
"ipub": {
"toc": true,
"listfigures": true,
"listtables": true,
"listcode": true
}
}


New in version v0.8.3: You can now control the depth of the contents table:

{
"ipub": {
"toc": {"depth": 2}
}
}


### 5.2.5. Figures and Tables¶

To override the default placement of figures and tables:

{
"ipub": {
"figure": {
"placement": "!bp"
},
"table": {
"placement": "!bp"
}
}
}


See Positioning_images_and_tables for placement options.

### 5.2.6. Adding a stylesheet to slides¶

For slide output, the following notebook-level metadata:

{
"ipub": {
"customcss": "mystylesheet.css"
}
}


will link the additional stylesheet mystylesheet in the resulting html. This can be used, for example, to display a log on each slide.

### 5.2.7. Pandoc Markdown Conversion¶

To control how the ipypandoc filters convert markdown cells, the following options are available:

{
"ipub": {
"sphinx": {
"apply_filters": true,
"convert_raw": true,
"hide_raw": false,
"at_notation": true,
"use_numref": true,
"reftag": "cite"
}
}
}


Writing Markdown

### 5.2.8. Sphinx Output Control¶

ipypublish.sphinx.notebook, for documentation on the Sphinx extension.

To suppress the output of a bibliography or glossary:

{
"ipub": {
"sphinx": {
"no_bib": true,
"no_glossary": true
}
}
}


To change the title text of the bibliography and glossary:

{
"ipub": {
"sphinx": {
"bib_title": "My Title",
"glossary_title": "My Title"
}
}
}


To control the addition of toggle buttons for code/output cells:

{
"ipub": {
"sphinx": {
"toggle_input": true,
"toggle_output": true,
"toggle_input_all": true,
"toggle_output_all": true
}
}
}


To denote the notebook as an orphan (i.e. not required in an index):

{
"ipub": {
"sphinx": {
"orphan": true
}
}
}


## 5.3. Cell/Output Level¶

The full schema can be viewed at Cell/Output Level Metadata Schema.

### 5.3.1. Ignore¶

To ignore any cell for all outputs:

{
"ipub": {
"ignore" : true
}
}


To mark any cell as for output to slides only:

{
"ipub": {
"slideonly" : true
}
}


### 5.3.2. Code Block¶

To output a code block:

{
"ipub": {
"code": {
"format" : {},
"asfloat": true,
"caption": "",
"label": "code:example_sym",
"widefigure": false,
"placement": "H"
}
}
}


all extra tags are optional:

• format can contain any keywords related to the latex Listings package (such as syntax highlighting colors)

• asfloat contitutes whether the code is wrapped in a codecell (float) environment or is inline.

• all other tags work the same as figure (below).

### 5.3.3. Output Text¶

To output text produced by the code (e.g. via the print command):

{
"ipub": {
"text": {
"format": {
"basicstyle": "\\small"
},
"asfloat": true,
"caption": "",
"label": "code:example_sym",
"widefigure": false,
"placement": "H",
"use_ansi": false
}
}
}


all extra tags are optional:

• format can contain any keywords related to the latex Listings package (such as syntax highlighting colors). N.B. in place of \ use \\.

• asfloat contitutes whether the code is wrapped in a codecell (float) environment or is inline.

• if use_ansi is true then, instead of stripping ansi colors in latex output, they will be converted to latex, wrapped in % characters and the listings option escapechar=% set.

• all other tags work the same as figure (below).

### 5.3.4. Output Figures¶

For figures (i.e. any graphics output by the code), enter in cell metadata:

{
"ipub": {
"figure": {
"caption": "Figure caption.",
"label": "fig:flabel",
"placement": "H",
"height":0.4,
"widefigure": false
}
}
}

• all tags are optional

• height/width correspond to the fraction of the page height/width, only one should be used (aspect ratio will be maintained automatically)

• placement is optional and constitutes using a placement arguments for the figure (see Positioning_images_and_tables).

\begin{figure}[H]

• widefigure is optional and constitutes expanding the figure to the page width (placement arguments will then be ignored)

\begin{figure*}


### 5.3.5. Output Tables¶

For tables (e.g. those output by pandas), enter in cell metadata:

{
"ipub": {
"table": {
"caption": "Table caption.",
"label": "tbl:tlabel",
"placement": "H",
"alternate": "gray!20"
}
}
}

• caption and label are optional

• placement is optional and constitutes using a placement arguments for the table (see Positioning_images_and_tables).

\begin{table}[H]

• alternate is optional and constitutes using alternating colors for the table rows (see https://tex.stackexchange.com/a/5365/107738).

\rowcolors{2}{gray!25}{white}

• if tables exceed the text width, in latex, they will be shrunk to fit

### 5.3.6. Output Equations¶

For equations (e.g. those output by sympy), enter in cell metadata:

{
"ipub": {
"equation": {
"environment": "equation",
"label": "eqn:elabel"
}
}
}

• environment is optional and can be ‘none’ or any of those available in amsmath; ‘equation’, ‘align’,‘multline’,‘gather’, or their * variants. Additionaly, ‘breqn’ or ‘breqn*’ will select the experimental breqn environment to smart wrap long equations.

• label is optional and will only be used if the equation is in an environment

### 5.3.7. Controlling Slides¶

For slide output:

{
"ipub": {
"slide": true
}
}

• the value of slide can be true, “new” (to indicate the start of a new slide) or “notes”

### 5.3.8. Specifying the start section number in slide-shows¶

For slide output:

{
"toc": {
"base_numbering": "3",
}
}

• the above will set the first section number to 3 rather than 1

• note that the top-level key is “toc”, and not “ipub”; this allows the starting section number to be configured using the toc2 notebook extension

### 5.3.9. Captions in a Markdown cell¶

Especially for long captions, it would be prefered that they can be viewed and edited in a notebook Markdown cell, rather than hidden in the metadata. This can be achieved using the default ipypublish converters:

If a markdown cell or code cell with latex/text output has the metadata tag:

{
"ipub": {
"caption": "fig:example_mpl"
}
}


Then, during the the postprocessor stage, this cell will be removed from the notebook object, and its text stored as a resource;

• the cell’s text is the first paragraph of the markdown string, i.e. nothing after a newline (\n)

• if there are multiple instance of the same cation name, then only the last instance will be stored

During the jinja templating, if a figure, table or code cell has a label matching any stored caption name, for example:

{
"ipub": {
"figure": {
"caption": "",
"label": "fig:example_mpl"
}
}
}


Then its caption will be overriden with the stored text.

### 5.3.10. Embedding Interactive HTML¶

Packages built on IPywidgets, like PythreeJS, Pandas3JS and the excellent IPyvolume, are making it increasingly easier to render complex, interactive html in the notebook. IPywidgets offers a save notebook with widgets feature, however, this can greatly increase the size of the notebook.

A better solution, recently offered, is to save a html snippet of the current widget state to file and embed it into the html/slides output as an iframe. This is also particularly useful in reveal.js slides, since the iframe content can be lazy loaded. To embed html, use the embed_html tag:

{
"ipub": {
"embed_html": {
"filepath": "path/to/file.html",
"other_files": ["path/to/file.js"],
"url": "https//path/to/url.html",
"width":0.5,
"height":0.5
},
"figure": {
"caption": "An example of embedded html"
}
}
}


If the cell already contains an output, then this tag will create/overwrite the first output’s “text/html” type. This allows for a single notebook cell with a static image of the widget in the output, and a path to the embed html in the metadata so that a) if you export to latex/pdf, you get the static image or b) if you export to html/reveal slides, you get the html.

• use either filepath or url

• other_files are files required by the html file (e.g. javascript libraries). These files will be copied to the the same folder as the html

• width/height refers to the fraction of the viewspace used (e.g. 0.5 width -> 50vw and 0.5 height -> 50vh)

An example of how this works is in the Example.ipynb, and the Example.html and Example.slides.html outputs.