Merge pull request #1029 from jcb91/toc

[toc2] add option toskip h1 headings for use as notebook title

Author: jcb91

src/jupyter_contrib_nbextensions/nbextensions/toc2/README.md

@@ -10,9 +10,15 @@ The toc2 extension enables to collect all running headers and display them in a
 #### Second demo:
 ![](demo2.gif)
 
-The table of contents is automatically updated when modifications occur in the notebook. The toc window can be moved and resized. It can be docked as a sidebar or dragged from the sidebar into a floating window. The table of contents can be collapsed or the window can be completely hidden. The navigation menu can be enabled/disabled via the nbextensions configuration utility. It can also be resized. The position, dimensions, and states (that is 'collapsed' and 'hidden' states) are remembered (actually stored in the notebook's metadata) and restored on the next session. Headers can be skipped from being inserted in the toc by adding the html tag "<a class='tocSkip'>" at the end of the header line; eg in 
+The table of contents is automatically updated when modifications occur in the notebook. The toc window can be moved and resized. It can be docked as a sidebar or dragged from the sidebar into a floating window. The table of contents can be collapsed or the window can be completely hidden. The navigation menu can be enabled/disabled via the nbextensions configuration utility. It can also be resized. The position, dimensions, and states (that is 'collapsed' and 'hidden' states) are remembered (actually stored in the notebook's metadata) and restored on the next session.
+
+There is a configurable option to skip h1 headers from the ToC, to allow their use as a notebook
+title. However, this cause issues in latex exports, where h1 are converted to sections.
+Alternatively, headers of any level can be omitted from being the toc by adding an html tag with the
+css class `tocSkip` at the end of the header line; e.g. as in
+
 ```
-## title <a class='tocSkip'>"
+## title <a class="tocSkip">
 ```
 
 The toc window also provides two links in its header for further functionalities:
@@ -34,6 +40,7 @@ The initial configuration can be given using the IPython-contrib nbextensions fa
 - Widening the display area to fit the browser window (may be useful with sidebar option; default: true)    
 - The numbering of headers (true by default)
 - Moving header title and menus on the left (default: true)
+- Skipping h1 headers, useful if you want to use h1 as unnumbered notebook title (default: false)
 - Customization of highlighting the title of currently selected/running sections.  
 - Customization of background, fonts, border and highlighting colors in the toc window and navigation menus (as third demo).
 
@@ -107,3 +114,5 @@ This option requires the IPython kernel and is not present with other kernels.
      - Updated README to please @KadeG in #871
 - @hiiwave, april 2017.
      - Support customization of background, fonts, border and highlighting colors in the toc window and navigation menus with PR [#969](https://github.com/ipython-contrib/jupyter_contrib_nbextensions/pull/969)
+- @jfbercher, @louisabraham, @jcb91 July 2017. Add support for skipping h1
+  headings, enabling their use as unnumbered notebook titles

src/jupyter_contrib_nbextensions/nbextensions/toc2/main.js

@@ -32,7 +32,8 @@ define(["require", "jquery", "base/js/namespace",  'services/config',
                 'sidebar_border': '#EEEEEE',
                 'navigate_text': '#333333',
                 'navigate_num': '#000000',
-              }
+              },
+              skip_h1_title: false,
 }
 
 //.....................global variables....

src/jupyter_contrib_nbextensions/nbextensions/toc2/toc2.js

@@ -535,15 +535,15 @@ var table_of_contents = function (cfg,st) {
     var depth = 1; //var depth = ol_depth(ol);
     var li= ul;//yes, initialize li with ul! 
     var all_headers= $("#notebook").find(":header");
-    var min_lvl=1, lbl_ary= [];
+    var min_lvl = 1 + Number(Boolean(cfg.skip_h1_title)), lbl_ary = [];
     for(; min_lvl <= 6; min_lvl++){ if(all_headers.is('h'+min_lvl)){break;} }
     for(var i= min_lvl; i <= 6; i++){ lbl_ary[i - min_lvl]= 0; }
 
     //loop over all headers
     all_headers.each(function (i, h) {
       var level = parseInt(h.tagName.slice(1), 10) - min_lvl + 1;
-      // skip below threshold
-      if (level > cfg.threshold){ return; }
+      // skip below threshold, or h1 ruled out by cfg.skip_h1_title
+      if (level < 1 || level > cfg.threshold){ return; }
       // skip headings with no ID to link to
       if (!h.id){ return; }
       // skip toc cell if present

src/jupyter_contrib_nbextensions/nbextensions/toc2/toc2.yaml

@@ -16,6 +16,14 @@ Parameters:
   min: -1
   step: 1
   default: 4
+
+- name: toc2.skip_h1_title
+  description: |
+    Skip h1 headings from numbering, so that they can serve as a notebook title.
+    See the README for details, caveats and alternatives
+  input_type: checkbox
+  default: false
+
 - name: toc2.toc_cell
   description: Add a Table of Contents cell at the top of the notebook
   input_type: checkbox