Skip to content

Commit 94cab4e

Browse files
fzanklfzankl
authored
Merge pull request #1 from develop
Initial implementation
2 parents 510119e + f35bce8 commit 94cab4e

File tree

10 files changed

+417
-1
lines changed

10 files changed

+417
-1
lines changed

‎.editorconfig‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Editor configuration, see http://editorconfig.org
2+
root = true
3+
4+
[*]
5+
charset = utf-8
6+
indent_style = space
7+
8+
[*.js]
9+
insert_final_newline = true
10+
trim_trailing_whitespace = true
11+
indent_size = 2
12+
13+
[*.md]
14+
max_line_length = off
15+
trim_trailing_whitespace = false
16+
indent_size = 2
17+
18+
[{*.txt,*.json,*.xml}]
19+
insert_final_newline = false
20+
indent_size = 2
21+
22+
[*.yml]
23+
insert_final_newline = true
24+
indent_size = 2

‎.npmignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
*
2+
!book/**
3+
!index.js
4+
!package.json
5+
!LICENSE
6+
!README.md

‎.travis.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
language: node_js
2+
node_js:
3+
- "node"
4+
5+
deploy:
6+
provider: npm
7+
email: "$NPM_MAIL"
8+
api_key: "$NPM_TOKEN"
9+
on:
10+
tags: true
11+
branch: master

‎README.md‎

Lines changed: 113 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,113 @@
1-
# gitbook-plugin-intopic-toc
1+
# GitBook Plugin: InTopic TOC
2+
3+
This GitBook Plugin adds an inline table of contents (TOC) to each page based on configurable selectors. Inline TOC can be enabled or disabled by default or on individual pages. TOC is placed on the right side and moves to top for smaller devices automatically.
4+
5+
Inline TOC stays at the top of the page when scrolling using a sticky effect. Current position is highlighted by a scrollspy effect.
6+
7+
![Inline TOC in desktop and mobile mode](https://user-images.githubusercontent.com/44210522/50728477-ab322680-112a-11e9-92da-4de20e17758d.png)
8+
9+
## Installation
10+
11+
### Step #1 - Update book.json file
12+
13+
1. In you gitbook's book.json file, add `intopic-toc` to plugins list.
14+
2. In pluginsConfig, configure the plugin so it does fit your needs. A custom setup is not mandatory.
15+
16+
**Sample `book.json` file for gitbook version 2.0.0+**
17+
18+
```json
19+
{
20+
"plugins": [
21+
"intopic-toc"
22+
]
23+
}
24+
```
25+
26+
**Sample `book.json` file for gitbook version 2.0.0+ and custom heading**
27+
28+
```json
29+
{
30+
"plugins": [
31+
"intopic-toc"
32+
],
33+
"pluginsConfig": {
34+
"intopic-toc": {
35+
"label": "Navigation"
36+
}
37+
}
38+
}
39+
```
40+
41+
**Sample `book.json` file for gitbook version 2.0.0+ and multilingual headings**
42+
43+
```json
44+
{
45+
"plugins": [
46+
"intopic-toc"
47+
],
48+
"pluginsConfig": {
49+
"intopic-toc": {
50+
"label": {
51+
"de": "In diesem Artikel",
52+
"en": "In this article"
53+
}
54+
}
55+
}
56+
}
57+
```
58+
59+
Note: Above snippets can be used as complete `book.json` file, if one of these matches your requirements and your book doesn't have one yet.
60+
61+
### Step #2 - gitbook commands
62+
63+
1. Run `gitbook install`. It will automatically install `intopic-toc` gitbook plugin for your book. This is needed only once.
64+
2. Build your book (`gitbook build`) or serve (`gitbook serve`) as usual.
65+
66+
## Usage
67+
68+
For basic usage, the only thing you have to do is install the plugin. For advanced scenarios see following configuration sample.
69+
70+
```json
71+
{
72+
"plugins": [
73+
"intopic-toc"
74+
],
75+
"pluginsConfig": {
76+
"intopic-toc": {
77+
"selector": ".markdown-section h2",
78+
"visible": true,
79+
"label": {
80+
"de": "In diesem Artikel",
81+
"en": "In this article"
82+
},
83+
}
84+
}
85+
}
86+
```
87+
88+
* selector : Selector used to find elements to put anchors on.
89+
* Default: .markdown-section h2
90+
* visible: Defines whether to show the navigation on every page.
91+
* Default: true.
92+
* label: Label which is used as heading for the navigation. Could be a single string or an object for multilingual setups.
93+
* Default: In this article
94+
95+
If `visible` parameter set to true and you want to hide the TOC on a single page, add the front matter item `isTocVisible: false` to the top of the Markdown file like this:
96+
97+
```markdown
98+
---
99+
isTocVisible: false
100+
---
101+
# My awesome documentation
102+
103+
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, ...
104+
```
105+
106+
The specific front matter `isTocVisible` overrides the `visible` parameter from global configuration.
107+
108+
## Troubleshooting
109+
110+
If inline TOC does not look as expected, check if your `book.json` is valid according to this documentation.
111+
112+
## Changelog
113+
01/05/2019 - Initial Release

‎book/anchor.min.js‎

Lines changed: 7 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎book/plugin.js‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
var selector;
2+
var label;
3+
var isVisibleByDefault;
4+
5+
require(["gitbook", "jQuery"], function(gitbook, $) {
6+
anchors.options = {
7+
placement: 'left'
8+
};
9+
10+
gitbook.events.bind('start', function(e, config) {
11+
var configuration = config['intopic-toc'];
12+
selector = configuration.selector;
13+
isVisibleByDefault = configuration.visible;
14+
label = configuration.label;
15+
16+
// Label can be language specific and could be specified via user configuration
17+
if (typeof label === 'object') {
18+
var language = gitbook.state.innerLanguage;
19+
20+
if (language && label.hasOwnProperty(language)) {
21+
label = label[language];
22+
} else {
23+
label = '';
24+
}
25+
}
26+
27+
// Hide navigation if a search is ative
28+
$bookSearchResults = $('#book-search-results');
29+
30+
var observer = new MutationObserver(() => {
31+
if ($bookSearchResults.hasClass('open')) {
32+
$('.intopic-toc').hide();
33+
}
34+
else {
35+
$('.intopic-toc').show();
36+
}
37+
});
38+
39+
observer.observe($bookSearchResults[0], { attributes: true });
40+
});
41+
42+
gitbook.events.bind("page.change", function() {
43+
anchors.removeAll();
44+
anchors.add(selector);
45+
46+
var isVisible = (isVisibleByDefault || gitbook.state.page.isTocVisible) && gitbook.state.page.isTocVisible != false;
47+
48+
if (anchors.elements.length > 1 && isVisible) {
49+
var navigation = buildNavigation(anchors.elements);
50+
51+
var section = document.body.querySelector('.page-wrapper');
52+
section.appendChild(navigation, section.firstChild);
53+
54+
$(".book-body .body-inner").scroll(onScroll);
55+
}
56+
});
57+
});
58+
59+
function buildNavigation(elements) {
60+
var navigation = document.createElement('nav');
61+
navigation.className = 'intopic-toc';
62+
63+
var heading = document.createElement('h3');
64+
heading.innerText = label;
65+
navigation.appendChild(heading);
66+
67+
var container = document.createElement('ol');
68+
navigation.appendChild(container);
69+
70+
for (var i = 0; i < elements.length; i++) {
71+
var text = elements[i].textContent;
72+
var href = elements[i].querySelector('.anchorjs-link').getAttribute('href');
73+
74+
var item = document.createElement('li');
75+
76+
if (i === 0) {
77+
item.classList.add('selected');
78+
}
79+
80+
var anchor = document.createElement('a');
81+
anchor.text = text;
82+
anchor.href = href;
83+
84+
item.appendChild(anchor);
85+
container.appendChild(item);
86+
}
87+
88+
return navigation;
89+
}
90+
91+
function onScroll(e) {
92+
const currentPosition = $(e.target).scrollTop() + $('.book-header').height();
93+
94+
for (var i = 0; i < anchors.elements.length; i++) {
95+
const section = anchors.elements[i];
96+
const isInView = $(section).offset().top < currentPosition;
97+
98+
if (isInView) {
99+
const menuItemID = section.getAttribute('id');
100+
const activeItem = $(`.intopic-toc ol li`).has(`a[href="#${menuItemID}"]`);
101+
102+
if (!activeItem) {
103+
return;
104+
}
105+
106+
$('.intopic-toc ol li').each(function() {
107+
$(this).attr('data-active', 'false');
108+
$(this).removeClass('selected');
109+
});
110+
111+
$(activeItem).attr('data-active', 'true');
112+
$(activeItem).addClass('selected');
113+
}
114+
}
115+
}

‎book/style.css‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
.intopic-toc {
2+
width: 20%;
3+
padding: 20px 15px 40px 15px;
4+
position: -webkit-sticky;
5+
position: sticky;
6+
top: 0;
7+
}
8+
9+
.page-wrapper {
10+
display: flex;
11+
justify-content: center;
12+
align-items: flex-start;
13+
flex-direction: row;
14+
}
15+
16+
.page-inner {
17+
margin: 0 !important;
18+
width: 80% !important;
19+
}
20+
21+
.intopic-toc h3 {
22+
margin-top: 0;
23+
font-size:1.5em;
24+
margin: 10px 0 0;
25+
color: #000;
26+
}
27+
28+
.intopic-toc ol {
29+
margin: 10px 0 0;
30+
list-style: none;
31+
padding: 0!important;
32+
list-style-type: none;
33+
}
34+
35+
.intopic-toc ol {
36+
list-style: none;
37+
}
38+
39+
.intopic-toc li {
40+
line-height: 1.3;
41+
border: solid transparent;
42+
border-width: 0 0 0 3px;
43+
padding: 2px 0 2px 4px;
44+
margin: 4px 0;
45+
}
46+
47+
.intopic-toc li.selected {
48+
font-weight: 600;
49+
border-color: hsla(206, 100%, 35%, 1);
50+
}
51+
52+
.intopic-toc li a {
53+
color: hsla(206, 100%, 35%, 1);
54+
}
55+
56+
@media (max-width: 1240px) {
57+
.intopic-toc {
58+
width: 100%;
59+
padding-bottom: 0;
60+
}
61+
62+
.intopic-toc li {
63+
border-width: 0;
64+
}
65+
66+
.intopic-toc li.selected {
67+
border-color: transparent;
68+
font-weight: normal;
69+
}
70+
71+
.page-wrapper {
72+
flex-direction: column-reverse;
73+
}
74+
}

‎index.js‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
module.exports = {
2+
book: {
3+
assets: "./book",
4+
js: [
5+
"anchor.min.js",
6+
"plugin.js"
7+
],
8+
css: [
9+
"style.css"
10+
]
11+
}
12+
};

‎package-lock.json‎

Lines changed: 5 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)