3 Embeded objects

Pheasant can embed codes from source files or include other source files.

3.1 Embeded codes

Extenal source files are read from file system by Pheasant syntax: {%=object%}. For example,

{%=/mkdocs.yml%}

writes the content of the real mkdocs.yml of this document:

site_name: Pheasant
site_url: https://pheasant.daizutabi.net/
site_description: Project documentation with MkDocs.
site_author: daizutabi

repo_url: https://github.com/daizutabi/pheasant/
edit_uri: ""

theme: ivory

plugins:
  - pheasant:
      version: pheasant

nav:
  - Home: index.md
  - User Guide:
    - Images: user-guide/images.md
    - Embed: user-guide/embed.md
    - SymPy: user-guide/sympy.md
    - Script: user-guide/script.py
    - Kernel: user-guide/kernel.md
  - About:
    - Release Notes: about/release-notes.md
    - License: about/license.md

markdown_extensions:
  - admonition
  - pymdownx.arithmatex

The root directory is the directory where mkdocs.yml exists.

If the file is too long to display the whole content, you can specify the lines as the same way of Python's slice notation.

{%=/mkdocs.yml[3:8]%}
site_author: daizutabi

repo_url: https://github.com/daizutabi/pheasant/
edit_uri: ""

Imported file can be numbered like figures and tables. Use this inline notation:

#File {%=/mkdocs.yml[:8]%}

File 1

site_name: Pheasant
site_url: https://pheasant.daizutabi.net/
site_description: Project documentation with MkDocs.
site_author: daizutabi

repo_url: https://github.com/daizutabi/pheasant/
edit_uri: ""

3.2 Include other file as Markdown source.

Assume that there is a directory named link under the same directory of this file and there are some files under the link directory. You can include the content of a file like below:

{% link/included.md %}

[The content of included.md]

You can also include a pure Python source code.

{% link/included.py %}

Script can be included.

def func(x, y):
    return x + y

[1] 2019-05-12 09:32:45 (5.01ms) python3 (1.97s)

If the included file contains header statements, the document structure may be broken. For example, a file to be included contains:

File 2 link/section.md

# Title

## Section

Text.

If you include the file, a new <h1> section starts that you don't want to. To maintain the document structure, you can shift the header level like below. Note that we are under a <h2> section now.

{% link/section.md>2 %}

In this case, "# Title" becomes "### Title" by ">2".