.local/share/jupyter/nbextensions/highlighter/export_highlights.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exporting the notebook\n",
    "\n",
    "As suggested by @juhasch, it is interesting to keep the highlights when exporting the notebook to another format. We give and explain below some possibilities:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Short version\n",
    "- Html export:\n",
    "```bash\n",
    " jupyter nbconvert FILE  --config JUPYTER_DATA_DIR/extensions/highlight_html_cfg.py \n",
    "```\n",
    "- LaTeX export:\n",
    "```bash\n",
    " jupyter nbconvert FILE  --config JUPYTER_DATA_DIR/extensions/highlight_latex_cfg.py \n",
    "```\n",
    "where JUPYTER_DATA_DIR can be found from the output of\n",
    "```bash\n",
    " jupyter --paths\n",
    "```\n",
    "eg `~/.local/share/jupyter` in my case. Seems to be `c:\\users\\NAME\\AppData\\Roaming\\jupyter` under Windows. \n",
    "\n",
    "Examples can be found here: [initial notebook](tst_highlights.ipynb), [html version](tst_highlights.html), [pdf version](tst_highlights.pdf) (after an additional LaTeX $\\rightarrow$ pdf compilation). "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##  Html export\n",
    "This is quite easy. Actually, highlight formatting embedded in markdown cells is preserved while converting with the standard\n",
    "```bash\n",
    "jupyter nbconvert file.ipynb\n",
    "```\n",
    "\n",
    "However, the css file is missing and must be added. Here we have several possibilities\n",
    "\n",
    "- Embed the css *within* the notebook. For that, consider the last cell of the present notebook. This code reads the css file `highlighter.css` in the extension directory and displays the corresponding style. So doing the `<style> ...</style>` section will be present in the cell output and interpreted by the web browser. Drawbacks of this solution is that user still have to execute this cell and that the this is not language agnostic. \n",
    "- Use a **template file** to link or include the css file during conversion. Such a file is provided as `templates/highlighter.tpl`. It was choosen here to *include* the css content in the produced html file rather than linking it. This avoids the necessity to keep the css file with the html files. \n",
    "  - This works directly if the css resides in the same directory as the file the user is attempting to convert --thus requires the user to copy `highlighter.css` in the current directory. Then the conversion is simply \n",
    "```bash\n",
    "  jupyter nbconvert file.ipynb --template highlighter\n",
    "```\n",
    "\n",
    "- It still remains two problems with this approach. First, it can be annoying to have to systematically copy the css file in the current directory. Second, the data within the html tags is not converted (and thus markdown remains unmodified). A solution is to use a pair of preprocessor/postprocessor that modify the html tags and enable the subsequent markdown to html converter to operate on the included data. Also,  a config file is provided which redefines the template path to enable direct inclusion of the css file in the extension directory. Unfortunately, <span class=\"mark\">it seems that the *full path* to the config file has to be provided</span>. This file resides in the extensions subdirectory of the jupyter_data_dir. The path can be found by looking at the output of\n",
    "```bash\n",
    " jupyter --paths\n",
    "```\n",
    "Then the command to issue for converting the notebook to html is\n",
    "```bash\n",
    " jupyter nbconvert FILE  --config JUPYTER_DATA_DIR/extensions/highlight_html_cfg.py \n",
    "```\n",
    "\n",
    "For instance\n",
    "```bash\n",
    "jupyter nbconvert tst_highlights.ipynb  --config ~/.local/share/jupyter/extensions/highlight_html_cfg.py \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## LaTeX export\n",
    "This is a bit more complicated since the direct conversion removes all html formatting present in markdown cells. Thus use again a **preprocessor** which runs before the markdown $\\rightarrow$ LaTeX conversion. In turn, it appears that we also need to postprocess the result. \n",
    "\n",
    "Three LaTeX commands, namely *highlighta, highlightb, highlightc*, and three environments *highlightA, highlightB, highlightC*  are defined. Highlighting html markup is then transformed into the corresponding LaTeX commands and the text for completely highlighted cells is put in the adequate LaTeX environment.  \n",
    "\n",
    "Pre and PostProcessor classes are defined in the file `pp_highlighter.py` located in the `extensions` directory. A LaTeX template, that includes the necessary packages and the definitions of commands/environments is provides as `highlighter.tplx` in the template directory. \n",
    "The template inherits from `article.ltx`. For more complex scenarios, typically if the latex template file has be customized, the user shall modify its template or inherit from his base template rather than from article. \n",
    "\n",
    "Finally, a config file fixes the different options for the conversion. Then the command to issue is simply \n",
    "```bash\n",
    " jupyter nbconvert FILE  --config JUPYTER_DATA_DIR/extensions/highlight_latex_cfg.py \n",
    "```\n",
    "e.g. \n",
    "```bash\n",
    "jupyter nbconvert tst_highlights.ipynb  --config ~/.local/share/jupyter/extensions/highlight_latex_cfg.py \n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configuring paths\n",
    "\n",
    "<span class=\"mark\">For those who do not have taken the extension from the `jupyter_contrib_nbextensions` repository or have not configured extensions via its `setup.py` utility,</span> a file `set_paths.py` is present in the extension directory (it is merely a verbatim copy of the relevant parts in setup.py). This file configure the paths to the `templates` and `extension` directories. It should be executed by something like\n",
    "```bash\n",
    "python3 set_paths.py\n",
    "```\n",
    "Additionaly, you may also have to execute `mv_paths.py` if you installed from the original repo via `jupyter nbextension install ..`\n",
    "```bash\n",
    "python3 mv_paths.py\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example for embedding the css within the notebook before conversion"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>.mark {\n",
       "    background-color: yellow;\n",
       "    color: red;\n",
       "    display:inline-block;\n",
       "}\n",
       "\n",
       ".burk {\n",
       "    background-color: red;\n",
       "    color: yellow;\n",
       "    display:inline-block;\n",
       "}\n",
       "\n",
       ".girk {\n",
       "    background-color: lime;\n",
       "    color: red;\n",
       "    display:inline-block;\n",
       "}\n",
       "\n",
       "\n",
       ".btnw{\n",
       "    background-color: white;\n",
       "}\n",
       "\n",
       ".ret {\n",
       "    margin-left: -1em;\n",
       "}\n",
       "</style>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.core.display import display, HTML\n",
    "from jupyter_core.paths import jupyter_config_dir, jupyter_data_dir\n",
    "import os\n",
    "csspath=os.path.join(jupyter_data_dir(),'nbextensions',\n",
    "                       'highlighter','highlighter.css')\n",
    "HTML('<style>'+open(csspath, \"r\").read()+'</style>')"
   ]
  }
 ],
 "metadata": {
  "interactive_sols": {
   "cbx_id": 1
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.4.3+"
  },
 },
 "nbformat": 4,
 "nbformat_minor": 0
}