Skip to content

Usage

mkdocs configuration

Add the nbconvert into configuration file (mkdocs.yml)'s plugins list

plugins:
    - nbconvert

Options

  • input_dir: Directory where to scan *.ipynb files

    Either absolute or relative path. When relative, it's from mkdocs configuration file's directory.

    When omitted, default value is notebooks

  • output_dir: Export notebook files to markdown files in the directory.

    It MUST be a relative path to doc_dir

    When omitted, default value is notebooks.

  • recursive: Whether scan *.ipynb files in subdirectories recursively

    When omitted, default value is True

  • execute_enabled: Whether executing notebooks before convert. false by default

  • max_workers: Number of concurrent threads used to process notebooks. Defaults to the number of CPU cores.

  • execute_options: Options for execution:

    • execute_options.run_path: Specifies in which folder to execute the notebook. The plugin in will take input_dir as the path if not specified.

    • execute_options.kernel_name: The execution kernel. When not specified, the default Python kernel is chosen.

    • execute_options.timeout: The cell execution timeout. No timeout when not specified.

    • execute_options.write_back: Whether save executed result to the notebook file. false by default.

    • exit_on_error: Whether exit when an error occurred. Default is true.

Options can be add to configuration file as below:

plugins:
    - nbconvert:
         input_dir: notebooks
         recursive: true
         output_dir: notebooks
         execute_enabled: true
         max_workers: 4
         execute_options:
             write_back: true

In the above example, the plugin recursively searches Jupyter notebook files in {{project_dir}}\notebooks, then converts them to markdown files to {{project_dir}}\docs\notebooks, where {{project_dir}}\docs is the default value of doc_dir configure. A pre-execution will be performed, and the running result will be saved to original notebook files. The conversion will be processed using 4 concurrent threads.

In nav section, add *.ipynb files as normal markdown files with replacing extension *.ipynb to *.md, since they're converted to markdown files in output_dir:

nav:
    - index.md
    - Notebooks:
          - notebooks/installation.md
          - notebooks/usage.md
          - notebooks/image.md
          - notebooks/matplotlib.md
    - authors.md
    - changelog.md

Warning:

converted notebooks/*.md files will be removed at the end of building.