[toc2] add more detail about skipping headings to readme & yaml

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:
@@ -108,5 +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)
-- @louisabraham, @jcb91 July 2017. Add support for skipping h1 headings,
-  enabling their use as unnumbered notebook titles
+- @jfbercher, @louisabraham, @jcb91 July 2017. Add support for skipping h1
+  headings, enabling their use as unnumbered notebook titles

src/jupyter_contrib_nbextensions/nbextensions/toc2/toc2.yaml

@@ -19,7 +19,8 @@ Parameters:
 
 - name: toc2.skip_h1_title
   description: |
-    Skip h1 headings from numbering, so that they can serve as a notebook title
+    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