Implement nbShow and highlight.js support for nim and other langs' code in markdown (#179)

HugoGranstrom · pietroppeter · web-flow · commit d144ac5efb8d · 2023-02-23T17:15:32.000+01:00
* add nbShow

* add highlight.js

* add nohighlight class to nbCodeSource partial

* take back nim class

* take back hljs

* disable highlight.js for Show source

* fix tests

* update readme

* add option to disable highlight.js with `nb.disableHighlightJs`

* hide warnings in index and readme

* Update docsrc/penguins.nim

Co-authored-by: Pietro Peterlongo &lt;pietro.peterlongo@gmail.com&gt;

* mention dynamic highlighting in readme

---------

Co-authored-by: Pietro Peterlongo &lt;pietro.peterlongo@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -156,6 +156,7 @@ Currently most of the documentation on customization is given by the examples.
 
 * `nbImage`: image command to show images (see `penguins.nim` example linked above)
 * `nbFile`: content (string or untyped) is saved to file (see example document [files](https://pietroppeter.github.io/nimib/files.html))
+* `nbShow`: show a variable that has a `toHtml` proc defined. For example to pretty print a dataframe.
 * `nbRawHtml`: called with string content, it will add the raw content to document (html backend)
 * `nbTextWithCode`: a variant of `nbText` that also reads nim source. See example of usage
   at the end of the source in `numerical.nim` linked above.
@@ -190,6 +191,14 @@ and [counter](https://pietroppeter.github.io/nimib/counters.html) for examples o
 In [caesar](https://pietroppeter.github.io/nimib/caesar.html) we have an example of a karax app
 that implements [Caesar cipher](https://en.wikipedia.org/wiki/Caesar_cipher).
 
+### highlighting
+Code blocks produced by `nbCode` are statically highlighted, but code in markdown code blocks are dynamically highlighted using 
+[highlightjs](https://highlightjs.org/). The dynamic highlighting can be disabled by running `nb.disableHighlightJs()`. 
+The supported languages are the ones listed as "common" [here](https://highlightjs.org/download/) plus Nim, Julia and Latex.
+
+Highlight styling classes are the same of [highlightjs](https://highlightjs.org/)
+and you can pick a different styling (`atom-one-light` is default for light mode, `androidstudio` is default for dark mode).
+
 ### latex
 
 See [numerical](https://pietroppeter.github.io/nimib/numerical.html) for an example of latex usage.
@@ -235,7 +244,7 @@ All the options available can be seen by running any nimib file with option `nbH
 ```nim
 import osproc
 withDir nb.srcDir:
-  echo execProcess(&quot;nim r --verbosity:0 --hints:off hello --nbHelp&quot;)
+  echo execProcess(&quot;nim r --verbosity:0 --hints:off --warnings:off hello --nbHelp&quot;)
 ```
 
 
@@ -368,6 +377,3 @@ because I made a [package](https://github.com/pietroppeter/nimoji) for that and
 because [someone made it into an art form](https://github.com/oakes/vim_cubed#q--a)
 and they tell me [imitation is the sincerest form of flattery](https://www.goodreads.com/quotes/558084-imitation-is-the-sincerest-form-of-flattery-that-mediocrity-can)
 
-
-
-
diff --git a/docsrc/index.nim b/docsrc/index.nim
@@ -134,6 +134,7 @@ Currently most of the documentation on customization is given by the examples.
 
 * `nbImage`: image command to show images (see `penguins.nim` example linked above)
 * `nbFile`: content (string or untyped) is saved to file (see example document [files]({docs}/files.html))
+* `nbShow`: show a variable that has a `toHtml` proc defined. For example to pretty print a dataframe.
 * `nbRawHtml`: called with string content, it will add the raw content to document (html backend)
 * `nbTextWithCode`: a variant of `nbText` that also reads nim source. See example of usage
   at the end of the source in `numerical.nim` linked above.
@@ -168,6 +169,14 @@ and [counter]({docs}/counters.html) for examples of how to create widgets using
 In [caesar]({docs}/caesar.html) we have an example of a karax app
 that implements [Caesar cipher](https://en.wikipedia.org/wiki/Caesar_cipher).
 
+### highlighting
+Code blocks produced by `nbCode` are statically highlighted, but code in markdown code blocks are dynamically highlighted using 
+[highlightjs](https://highlightjs.org/). The dynamic highlighting can be disabled by running `nb.disableHighlightJs()`. 
+The supported languages are the ones listed as "common" [here](https://highlightjs.org/download/) plus Nim, Julia and Latex.
+
+Highlight styling classes are the same of [highlightjs](https://highlightjs.org/)
+and you can pick a different styling (`atom-one-light` is default for light mode, `androidstudio` is default for dark mode).
+
 ### latex
 
 See [numerical]({docs}/numerical.html) for an example of latex usage.
@@ -212,7 +221,7 @@ All the options available can be seen by running any nimib file with option `nbH
 nbCode:
   import osproc
   withDir nb.srcDir:
-    echo execProcess("nim r --verbosity:0 --hints:off hello --nbHelp")
+    echo execProcess("nim r --verbosity:0 --hints:off --warnings:off hello --nbHelp")
 
 let renderProcType = "type NbRenderProc = proc (doc: var NbDoc, blk: var NbBlock) {. nimcall .}"
 
diff --git a/docsrc/penguins.nim b/docsrc/penguins.nim
@@ -17,7 +17,10 @@ nbCode:
   let df = readCsv("data/penguins.csv")
 nbText: "let us see how it looks"
 nbCode:
-  echo df # why so wide the first column?
+  echo df
+nbText: "or even nicer using `nbShow(df.head(10))`:"
+nbShow(df.head(10))
+
 nbText: """Note that among the 7 columns of the dataframe, the first 2 and the last one have datatype string.
 The remaining 4 are numeric but they have datatype object. Why?
 
diff --git a/src/nimib.nim b/src/nimib.nim
@@ -5,7 +5,7 @@ export types, blocks, docs, boost, sugar, jsutils
 # types exports mustache, tables, paths
 
 from nimib / themes import nil
-export themes.useLatex, themes.darkMode, themes.`title=`
+export themes.useLatex, themes.darkMode, themes.`title=`, themes.disableHighlightJs
 
 from nimib / renders import nil
 
@@ -127,6 +127,9 @@ when moduleAvailable(nimpy):
         captureStdout(nb.blk.output):
           discard nbPythonBuiltins.exec(pythonStr)
 
+template nbShow*(obj: untyped) =
+  nbRawHtml(obj.toHtml())
+
 template nbRawOutput*(content: string) {.deprecated: "Use nbRawHtml instead".} = 
   nbRawHtml(content)
 
diff --git a/src/nimib/renders.nim b/src/nimib/renders.nim
@@ -16,7 +16,7 @@ proc useHtmlBackend*(doc: var NbDoc) =
   doc.partials["nbCode"] = """
 {{>nbCodeSource}}
 {{>nbCodeOutput}}"""
-  doc.partials["nbCodeSource"] = "<pre><code class=\"nim hljs\">{{&codeHighlighted}}</code></pre>"
+  doc.partials["nbCodeSource"] = "<pre><code class=\"nohighlight hljs nim\">{{&codeHighlighted}}</code></pre>"
   doc.partials["nbCodeOutput"] = """{{#output}}<pre class="nb-output"><samp>{{output}}</samp></pre>{{/output}}"""
   doc.partials["nimibCode"] = doc.partials["nbCode"]
   doc.partials["nbImage"] = """<figure>
diff --git a/src/nimib/themes.nim b/src/nimib/themes.nim
@@ -23,6 +23,9 @@ const head* = """
   {{^no_normalize}}<link rel='stylesheet' href='https://unpkg.com/normalize.css'>{{/no_normalize}}
   {{{stylesheet}}}
   {{{highlight}}}
+  {{^disableHighlightJs}}
+    {{{highlightJs}}}
+  {{/disableHighlightJs}}
   {{{nb_style}}}
   {{{latex}}}
   {{> head_other }}
@@ -43,6 +46,10 @@ const waterLight* = """<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/
 const waterDark* = """<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/kognise/water.css@latest/dist/dark.min.css">"""
 const atomOneLight* = """<link rel='stylesheet' href='https://cdn.jsdelivr.net/gh/pietroppeter/nimib/assets/atom-one-light.css'>"""
 const androidStudio* = """<link rel='stylesheet' href='https://cdn.jsdelivr.net/gh/pietroppeter/nimib/assets/androidstudio.css'>"""
+const highlightJsTags* = """
+<script src="https://cdn.jsdelivr.net/gh/pietroppeter/nimib@main/assets/highlight.min.js"></script>
+<script>hljs.highlightAll();</script>
+"""
 const latex* = """<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">
 <script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js" integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>
 <script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js" integrity="sha384-mll67QQFJfxn0IYznZYonOWZ644AWYC+Pt2cHqMaRhXVrursRwvLnLaebdGIlYNa" crossorigin="anonymous" onload="renderMathInElement(document.body,{delimiters:[{left: '$$', right: '$$', display: true},{left: '$', right: '$', display: false}]});"></script>"""
@@ -100,7 +107,7 @@ const footer* = """
 const madeWithNimib* = """<span class="nb-small">made with <a href="https://pietroppeter.github.io/nimib/">nimib 🐳</a></span>"""
 const showSourceButton* = """<button class="nb-small" id="show" onclick="toggleSourceDisplay()">Show Source</button>"""
 const sourceSection* = """<section id="source">
-<pre><code class="nim hljs">{{{source_highlighted}}}</code></pre>
+<pre><code class="nohighlight nim hljs">{{{source_highlighted}}}</code></pre>
 </section>"""
 const showSourceScript* = """<script>
 function toggleSourceDisplay() {
@@ -131,6 +138,7 @@ proc useDefault*(doc: var NbDoc) =
   doc.context["favicon"] = faviconWhale
   doc.context["stylesheet"] = waterLight
   doc.context["highlight"] = atomOneLight
+  doc.context["highlightJs"] = highlightJsTags
   doc.context["nb_style"] = nbStyle
   # header
   doc.partials["header"] = header
@@ -157,6 +165,9 @@ proc darkMode*(doc: var NbDoc) =
 proc useLatex*(doc: var NbDoc) =
   doc.context["latex"] = latex
 
+proc disableHighlightJs*(doc: var NbDoc) =
+  doc.context["disableHighlightJs"] = true
+
 proc `title=`*(doc: var NbDoc, text: string) =
   # to deprecate?
   doc.context["title"] = text
diff --git a/tests/trenders.nim b/tests/trenders.nim
@@ -11,9 +11,9 @@ suite "render (block), html default backend":
 
   test "nbCode without output":
     nbCode: discard
-    check nb.render(nb.blk).strip == """<pre><code class="nim hljs"><span class="hljs-keyword">discard</span></code></pre>"""
+    check nb.render(nb.blk).strip == """<pre><code class="nohighlight hljs nim"><span class="hljs-keyword">discard</span></code></pre>"""
 
   test "nbCode with output":
     nbCode: echo "hi"
     check nb.render(nb.blk).strip == """
-<pre><code class="nim hljs"><span class="hljs-keyword">echo</span> <span class="hljs-string">&quot;hi&quot;</span></code></pre><pre class="nb-output"><samp>hi</samp></pre>"""
+<pre><code class="nohighlight hljs nim"><span class="hljs-keyword">echo</span> <span class="hljs-string">&quot;hi&quot;</span></code></pre><pre class="nb-output"><samp>hi</samp></pre>"""
