From b24eb2d066dd46cdf68e6e71f578b89d741804b6 Mon Sep 17 00:00:00 2001
From: Stefan van der Walt <stefanv@berkeley.edu>
Date: Fri, 11 Feb 2022 00:37:37 -0800
Subject: [PATCH] Add section to `customizing` showing how to use template
 inheritance

---
 docs/source/customizing.rst | 65 +++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/docs/source/customizing.rst b/docs/source/customizing.rst
index f7e02c202..1ae191f70 100644
--- a/docs/source/customizing.rst
+++ b/docs/source/customizing.rst
@@ -140,3 +140,68 @@ from the Jupyter data directory.
 For example, in the reveal template, ``index.html.j2`` extends ``base.html.j2`` which is in the same directory, and
 ``base.html.j2`` extends ``lab/base.html.j2``. This approach allows using content that is available in other templates
 or may be overriden in the current template.
+
+A practical example
+~~~~~~~~~~~~~~~~~~~
+
+Say you would like to modify the existing Markdown template to wrap each
+output statement in a fenced code block:
+
+.. code::
+
+   ```output
+   (1, 2, 3)
+   ```
+
+Start by creating a new template directory, say ``mdoutput``.  In it,
+you have the following files::
+
+  conf.json
+  index.md.j2
+
+The configuration file, ``conf.json`` states that your template
+applies to markdown files::
+
+  {
+    "mimetypes": {
+      "text/markdown": true
+    }
+  }
+
+The ``index.md.j2`` template entrypoint extends the existing markdown
+template, and redefines how output blocks are rendered:
+
+.. code::
+
+   {% extends 'markdown/index.md.j2' %}
+
+   {%- block traceback_line -%}
+   ```output
+   {{ line.rstrip() | strip_ansi }}
+   ```
+   {%- endblock traceback_line -%}
+
+   {%- block stream -%}
+   ```output
+   {{ output.text.rstrip() }}
+   ```
+   {%- endblock stream -%}
+
+   {%- block data_text scoped -%}
+   ```output
+   {{ output.data['text/plain'].rstrip() }}
+   ```
+   {%- endblock data_text -%}
+
+You can now convert your notebook to markdown using the new template::
+
+  jupyter nbconvert --execute notebook.ipynb --to markdown --template=mdoutput
+
+(If you put your template folder in a different location than your
+notebook, remember to add
+``--TemplateExporter.extra_template_basedirs=path/to/template/parent``.)
+
+To further explore the possibilities of templating, take a look at the
+root of all templates: ``null.j2``.  You can find it in the
+``./nbconvert/templates/base`` subfolder of one of the data paths given
+by ``jupyter --paths``.