From 779a24e940d9df47827e1f8461eb7c97a028eccd Mon Sep 17 00:00:00 2001 From: Ircama Date: Tue, 8 Jan 2019 23:24:14 -0500 Subject: [PATCH 1/3] add description of how headings are searched Extracted from https://github.com/afeld/bootstrap-toc/pull/26. --- index.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/index.md b/index.md index e9fb43d..3626997 100644 --- a/index.md +++ b/index.md @@ -90,6 +90,14 @@ All options are optional, unless otherwise indicated. | `$scope` | jQuery Object | The element where the search for headings will be limited to, or the list of headings that will be used in the navigation. Defaults to `$(document.body)`. | {: .table } +## Headings + +By default, the plugin finds the first heading level (`

`, then `

`, etc.) that has more than one element and defaults to 1 (for `

`). The identified level becomes the top heading and the plugin supports a single nesting level associated to it, including the subsequent heading only. E.g., if the identified top level is `

`, the nested level will be `

`, which is the next below it; if the top level is `

`, the nested one will be `

`. No additional level to the nested one and no previous level to the top one will be shown. + +The plugin allows an option to customize this behavior: + +The jQuery object created for the `$scope` [option](#options) can consist of a set of header selectors (in the form *hN,hM,...* where N, M, ... are levels, e.g., `h1,h2,h3`), all of them are searched instead of the first declared one and of its subsequent heading. Example: `$scope: $('h1,h2,h3,h4,h5,h6')` (in this case, all of them are searched and not only `

` and `

` in case `

` is the top level). + ## Customization The following options can be specified at the heading level via `data-toc-*` attributes. From 64125b381339e0f2f93a2c5cde307590ecc99729 Mon Sep 17 00:00:00 2001 From: Aidan Feldman Date: Tue, 8 Jan 2019 23:49:50 -0500 Subject: [PATCH 2/3] reword and expand on Headings section of docs --- index.md | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/index.md b/index.md index 3626997..8d773fd 100644 --- a/index.md +++ b/index.md @@ -92,11 +92,37 @@ All options are optional, unless otherwise indicated. ## Headings -By default, the plugin finds the first heading level (`

`, then `

`, etc.) that has more than one element and defaults to 1 (for `

`). The identified level becomes the top heading and the plugin supports a single nesting level associated to it, including the subsequent heading only. E.g., if the identified top level is `

`, the nested level will be `

`, which is the next below it; if the top level is `

`, the nested one will be `

`. No additional level to the nested one and no previous level to the top one will be shown. +By default, the plugin chooses the top-level navigation items by searching for headings at the first heading level, then works its way down (`

`, then `

`, etc.) It will stop when it finds the first set of headings where more than one exists at that level. For example: -The plugin allows an option to customize this behavior: +```html +

The title

+

Some sub-title

+... +

Section 1

+

Subsection A

+... +

Subsection B

+... +

Section 2

+``` + +The plugin would see there's only one `

`, then that there's only one `

`, then stop when it sees there's more than one `

`. The identified level becomes the top-level navigation items in the Table of Contents, and any headings under those (the `

`s in this case) would be the second-level navigation. + +This behavior can be customized with the `$scope` [option](#options). That jQuery object can be created with one or more selectors to force certain headings to be used. + +In the above example, let's say that you wanted the navigation to only contain the Subsections. You could pass: + +```javascript +Toc.init({ + $scope: $("h4") + // ... +}); +``` + +and the resulting Table of Contents would only contain: -The jQuery object created for the `$scope` [option](#options) can consist of a set of header selectors (in the form *hN,hM,...* where N, M, ... are levels, e.g., `h1,h2,h3`), all of them are searched instead of the first declared one and of its subsequent heading. Example: `$scope: $('h1,h2,h3,h4,h5,h6')` (in this case, all of them are searched and not only `

` and `

` in case `

` is the top level). +> * Subsection A +> * Subsection B ## Customization From 6df46226ccc07de67bbb94559813765f18f7e891 Mon Sep 17 00:00:00 2001 From: Aidan Feldman Date: Tue, 8 Jan 2019 23:51:51 -0500 Subject: [PATCH 3/3] move Headings section under Customization --- index.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/index.md b/index.md index 8d773fd..a2531c5 100644 --- a/index.md +++ b/index.md @@ -90,7 +90,9 @@ All options are optional, unless otherwise indicated. | `$scope` | jQuery Object | The element where the search for headings will be limited to, or the list of headings that will be used in the navigation. Defaults to `$(document.body)`. | {: .table } -## Headings +## Customization + +### Headings By default, the plugin chooses the top-level navigation items by searching for headings at the first heading level, then works its way down (`

`, then `

`, etc.) It will stop when it finds the first set of headings where more than one exists at that level. For example: @@ -124,13 +126,9 @@ and the resulting Table of Contents would only contain: > * Subsection A > * Subsection B -## Customization - -The following options can be specified at the heading level via `data-toc-*` attributes. - ### Displayed text -By default, Bootstrap TOC will use the text from the heading element in the table of contents. If you want to customize what is displayed, add a `data-toc-text` attribute with the desired text. For example: +By default, Bootstrap TOC will use the text from the heading element in the table of contents. If you want to customize what is displayed, add a `data-toc-text` attribute to the heading with the desired text. For example: ```html

Longer text

@@ -140,7 +138,7 @@ displays "Longer text" as the heading, but "Short text" in the sidebar. ### Skipping -To prevent a particular heading from being added to the table of contents, add a `data-toc-skip` [boolean attribute](https://www.w3.org/TR/2008/WD-html5-20080610/semantics.html#boolean). +To prevent a particular heading from being added to the table of contents, add a `data-toc-skip` [boolean attribute](https://www.w3.org/TR/2008/WD-html5-20080610/semantics.html#boolean) to the heading. ```html

Some heading you don't want in the nav