From 741cdb764a9a388e67cd792fcb17ce42da2fd5a5 Mon Sep 17 00:00:00 2001
From: Louis Kaplan <j.kiszle@gmail.com>
Date: Sat, 6 Jun 2020 12:51:02 +0100
Subject: [PATCH] add example docs for custom parsing admonitions into
 notebooks

---
 docs/src/tips.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/docs/src/tips.md b/docs/src/tips.md
index cffc106..c0930f1 100644
--- a/docs/src/tips.md
+++ b/docs/src/tips.md
@@ -58,4 +58,61 @@ interprets the first `#md` as a markdown exclusive line, and then strips it out.
 second `#` tells Literate.jl that the line should be parsed as markdown and not a 
 Julia code block. If you only include `#md` and not the second `#` then it will 
 be parsed into Julia example block in the final documentation and not an actual 
-admonition.
\ No newline at end of file
+admonition.
+
+### [Custom parsing for markdown and notebook compatible admonitions](@id admonitions-compatibility)
+
+As mentioned above, admonitions are not compatible with Jupyter notebooks.
+(Though at time of writing this documentation,
+[this is an open issue in Jupter](https://github.com/jupyter/notebook/issues/1292)
+ so may change in the future.) For now, we can write a custom preprocessor function
+ so that admonitions are interpreted as quotes (with their own special formatting)
+ in notebooks and proper admonitions in markdown. For the case of note admonitions,
+ this can be written as follows:
+
+```julia
+function md_note(str)
+           str = replace(str, r"^#note # (.*)$"m => s"""
+           # !!! note
+           #     \1""")
+           return str
+       end
+
+function nb_note(str)
+           str = replace(str, r"^#note # (.*)$"m => s"""
+           # > *Note*
+           # > \1""")
+           return str
+       end
+
+using Literate
+
+Literate.markdown("example.jl", "tmp/"; preprocess = md_note)
+
+Literate.notebook("example.jl", "tmp/"; preprocess = nb_note)
+```
+
+This will allow us to turn the following source code in `example.jl`:
+
+```julia
+#note # This is a useful note.
+```
+
+into the correct admonition syntax in the markdown file generated:
+
+```julia
+!!! note
+    This is a useful note.
+```
+
+and a quotation style formatting in the generated notebook cell:
+
+```julia
+> *Note*
+> This is a useful note.
+```
+
+which, in an actual notebook cell, will look similar to:
+
+> *Note*\
+> This is a useful note.