1 Pheasant

1.1 Overview

Pheasant is a Markdown converter which is designed to be used as a plugin for static site generators such as MkDocs or Pelican.

Highlights include:

  • Auto generation of outputs for a fenced code block or inline code in Markdown source using Jupyter client. The code language is not restricted to Python.
  • Auto numbering of headers, figures, and tables. Numbered objects can be linked from Markdown source.
  • [Windows only] Extract shapes from Microsoft PowerPoint presentations.
  • Simple interface to use Pheasant as a plugin for other site generators.
  • Easy to introduce any extensions you want to Pheasant.

1.2 How to install

You can install Pheasant from PyPI.

$ pip install pheasant

If you use Pheasant as a plugin for MkDocs or Pelican, you also need to instal them.

$ pip install mkdocs pelican

1.3 Plugin settings

1.3.1 MkDocs

In your mkdocs.yml, add lines below:

plugins:
  - pheasant:
      jupyter:
        enabled: true
      number:
        enabled: true

1.3.2 Pelican

In your pelicanconf.py, add lines below:

PLUGINS = ['pheasant']
PHEASANT = {'jupyter': {'enabled': True}, 'number': {'enabled': True}}

1.4 Examples

1.4.1 Auto generation of outputs with Jupyter client

A markdown soure below:

```python 
print(1)
```

is converted into:

```python 
>>> print(1)
1
```

after execution of print function via Jupyter client and finally rendered as:

print(1)
1

"Inline code" can also be converted. For example:

```python 
name = 'Pheasant'
```

Then, "My name is {{name}}." becomes "My name is Pheasant." You can assign a variable in an inline code. "{{a=5}}$2a$ is equal to {{2*a}}." becomes "2a is equal to 10." Note that an inline code without outputs is not shown after conversion.

Pheasant supports various output formats other than standard stream. For example, you can create a PNG image using Matplotlib.

```python 
import matplotlib.pyplot as plt
plt.plot([1, 3, 2])
```

The above Markdown source creates an input Python code block and a PNG image:

import matplotlib.pyplot as plt
plt.plot([1, 3, 2])
[<matplotlib.lines.Line2D at 0x1cf698c9358>]

png

You may want to display only graphics. You can use display option for a fenced code.

```python display
plt.plot([1, 3, 2])
```

This creates only a PNG image without a code block like below:

png

Note

Matplotlib package already has been imported in the previous code block so that we don't need to import it again here.

Pheasant also supports Bokeh's HTML output.

```python hide
from bokeh.plotting import figure
from bokeh.embed import components

plot = figure(plot_width=250, plot_height=250)
plot.circle([1, 2, 3, 4, 5], [1, 2, 3, 4, 5], size=10)
```

{{plot}}
from bokeh.plotting import figure
from bokeh.embed import components

plot = figure(plot_width=250, plot_height=250)
plot.circle([1, 2, 3, 4, 5], [1, 2, 3, 4, 5], size=10)
GlyphRenderer(
id = '1038', …)

1.4.2 Auto numbering of headers, figures, and tables.

As you can see, all of headers are numbered in this document. This is done by Pheasant automatically. In addition, Pheasant can count the number of figures and tables and give the identical number to each figure or table.

You can use a special header statement for figure (#Figure) and table (#Table) to number them like below:

#Figure This is a cat. {#cat#}

![jpg](img/cat.jpg)

jpg

Figure 1.1 This is a cat.

Note

In the above Markdown source, {#<tag>#} is a tag for hyperlink described below.

Off course, you can use any code to create a figure:

#Fig A Matplotlib figure

```python display
plt.plot([3, 2])
```

png

Figure 1.2 A Matplotlib figure

Like figures, tables can be numbered.

#Table A Markdown table

a | b
--|--
0 | 1
2 | 3

Table 1.1 A Markdown table

a b
0 1
2 3

Pandas DataFarme is useful to create a table programmatically.

#Table A Pandas DataFrame

```python display
import pandas as pd
pd.DataFrame([[1, 2], [3, 4]], columns=list('ab')) * 2
```

Table 1.2 A Pandas DataFrame

a b
0 2 4
1 6 8

A Markdown source for figures and tables is a source block separated by a blank line from following text. If a figure or table has a blank line within it, you have to explicitly show the content range with <!-- begin --> and <!-- end --> statement.

#Fig A Bokeh's HTML figure

<!-- begin -->
```python inline
{{plot}}
```
<!-- end -->

Figure 1.3 A Bokeh's HTML figure

Numbered objects are linked from Markdown source using {#<tag>#}:

For example, go to Fig. {#cat#}

For example, go to Fig. 1.1