Skip to content

elaborate on how to customize the list of headings #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
afeld merged 3 commits into from
Jan 9, 2019
Merged

elaborate on how to customize the list of headings #51

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
779a24e
add description of how headings are searched
Ircama Jan 9, 2019
64125b3
reword and expand on Headings section of docs
afeld Jan 9, 2019
6df4622
move Headings section under Customization
afeld Jan 9, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 35 additions & 3 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,11 +92,43 @@ All options are optional, unless otherwise indicated.

## Customization

The following options can be specified at the heading level via `data-toc-*` attributes.
### 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 (`<h1>`, then `<h2>`, etc.) It will stop when it finds the first set of headings where more than one exists at that level. For example:

```html
<h1>The title</h1>
<h2>Some sub-title</h2>
...
<h3>Section 1</h3>
<h4>Subsection A</h4>
...
<h4>Subsection B</h4>
...
<h3>Section 2</h3>
```

The plugin would see there's only one `<h1>`, then that there's only one `<h2>`, then stop when it sees there's more than one `<h3>`. The identified level becomes the top-level navigation items in the Table of Contents, and any headings under those (the `<h4>`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:

> * Subsection A
> * Subsection B

### 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
<h2 data-toc-text="Short text">Longer text</h2>
Expand All @@ -106,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
<h2 data-toc-skip>Some heading you don't want in the nav</h2>
Expand Down