// Populate the sidebar
//
// This is a script, and not included directly in the page, to control the total size of the book.
// The TOC contains an entry for each page, so if each page includes a copy of the TOC,
// the total size of the page becomes O(n**2).
class MDBookSidebarScrollbox extends HTMLElement {
constructor() {
super();
}
connectedCallback() {
this.innerHTML = '
- Introduction
- Getting Started
- 1. Installation
- 2. Shell Completion
- 3. Usage
- Guide
- 4. Why?
- 5. Packaging
- 6. Packages
- 7. Configuration
- 8. Server
- 9. Design
- 10. Comparisons
- Reference
- 11. API
❱
- 11.1. /api/directory/{hash}
- 11.2. /api/file/{hash}
- 11.3. /api/gc
- 11.4. /api/head/{revision}
- 11.5. /api/missing
- 11.6. /api/number/{number}
- 11.7. /api/numbers
- 11.8. /api/package/{fingerprint}
- 11.9. /api/packages
- 11.10. /api/revision/{revision}
- 12. Commands
❱
- 12.1. filepack
- 12.2. filepack archive
- 12.3. filepack completions
- 12.4. filepack contains
- 12.5. filepack create
- 12.6. filepack delete
- 12.7. filepack download
- 12.8. filepack files
- 12.9. filepack fingerprint
- 12.10. filepack gc
- 12.11. filepack hash
- 12.12. filepack info
- 12.13. filepack key
- 12.14. filepack keygen
- 12.15. filepack languages
- 12.16. filepack lints
- 12.17. filepack man
- 12.18. filepack manifest
- 12.19. filepack metadata
- 12.20. filepack reference
- 12.21. filepack serve
- 12.22. filepack sign
- 12.23. filepack signatures
- 12.24. filepack size
- 12.25. filepack upload
- 12.26. filepack verify
- 13. Content Types
- 14. Deco
❱
- 14.1. Application
- 14.2. Archive
- 14.3. Audio
- 14.4. AudioCodec
- 14.5. AudioFormat
- 14.6. Boolean
- 14.7. CheckedUrl
- 14.8. ChromaSubsampling
- 14.9. Claims
- 14.10. ColorType
- 14.11. ComponentBuf
- 14.12. Context
- 14.13. Dimensions
- 14.14. Directory
- 14.15. DisplayPrivateKey
- 14.16. Ed25519Signature
- 14.17. Entry
- 14.18. EntryInfo
- 14.19. Envelope<Claims>
- 14.20. Envelope<Statement>
- 14.21. Fingerprint
- 14.22. Hash
- 14.23. Image
- 14.24. ImageFormat
- 14.25. Item<Audio>
- 14.26. Item<Image>
- 14.27. Item<Video>
- 14.28. Language
- 14.29. Media
- 14.30. Metadata
- 14.31. Mode
- 14.32. Orientation
- 14.33. PackageMetadata
- 14.34. PublicKey
- 14.35. RelativePath
- 14.36. Revision
- 14.37. RevisionObject
- 14.38. Rotation
- 14.39. Signature<Claims>
- 14.40. Signature<Statement>
- 14.41. SignedInteger
- 14.42. Statement
- 14.43. String
- 14.44. Text
- 14.45. Time
- 14.46. Totals
- 14.47. Track
- 14.48. TrackCodec
- 14.49. TrackInfo
- 14.50. UnsignedInteger
- 14.51. Video
- 14.52. VideoFormat
- 15. JSON
❱
- 15.1. Audio
- 15.2. AudioCodec
- 15.3. AudioFormat
- 15.4. Boolean
- 15.5. Bytes
- 15.6. CheckedUrl
- 15.7. ChromaSubsampling
- 15.8. ColorType
- 15.9. ComponentBuf
- 15.10. Dimensions
- 15.11. DirectoryTree
- 15.12. DirectoryTreeEntry
- 15.13. File
- 15.14. Hash
- 15.15. Image
- 15.16. ImageFormat
- 15.17. Info
- 15.18. Item<Audio>
- 15.19. Item<Image>
- 15.20. Item<Video>
- 15.21. KeyName
- 15.22. Language
- 15.23. Lint
- 15.24. LintGroup
- 15.25. Manifest
- 15.26. Media
- 15.27. Metadata
- 15.28. Orientation
- 15.29. PackageMetadata
- 15.30. PublicKey
- 15.31. RelativePath
- 15.32. Rotation
- 15.33. Signature<Statement>
- 15.34. SignatureEntry
- 15.35. String
- 15.36. Text
- 15.37. Time
- 15.38. Totals
- 15.39. Track
- 15.40. TrackCodec
- 15.41. TrackInfo
- 15.42. UnsignedInteger
- 15.43. Utf8PathBuf
- 15.44. Video
- 15.45. VideoFormat
- 16. Languages
- 17. Lints
- 18. Media
- 19. Metadata
- 20. Tagged Hex
❱
- 20.1. hash
- 20.2. package
- 20.3. private
- 20.4. public
- 20.5. revision
- 20.6. signature
- 20.7. token
- 21. Unstable Features
- 22. Web
❱
- 22.1. /
- 22.2. /artwork/{fingerprint}
- 22.3. /artwork/{fingerprint}/thumbnail
- 22.4. /directory/{hash}
- 22.5. /favicon.ico
- 22.6. /file/{hash}
- 22.7. /file/{hash}/{*path}
- 22.8. /files
- 22.9. /install.sh
- 22.10. /media/audio/{fingerprint}/item/{item}
- 22.11. /media/image/{fingerprint}/item/{item}
- 22.12. /media/image/{fingerprint}/item/{item}/thumbnail
- 22.13. /media/video/{fingerprint}/item/{item}
- 22.14. /media/video/{fingerprint}/item/{item}/placeholder
- 22.15. /media/video/{fingerprint}/item/{item}/placeholder/thumbnail
- 22.16. /mount/{package}
- 22.17. /mount/{package}/
- 22.18. /mount/{package}/{*path}
- 22.19. /package/{package}
- 22.20. /package/{package}/history
- 22.21. /package/{package}/item/{item}
- 22.22. /package/{package}/media
- 22.23. /packages
- 22.24. /static/{*path}
- 23. YAML
❱
- 23.1. Audio
- 23.2. CheckedUrl
- 23.3. Image
- 23.4. Language
- 23.5. Media
- 23.6. Metadata
- 23.7. PackageMetadata
- 23.8. RelativePath
- 23.9. String
- 23.10. Text
- 23.11. Time
- 23.12. Video
';
// Set the current, active page, and reveal it if it's hidden
let current_page = document.location.href.toString().split('#')[0].split('?')[0];
if (current_page.endsWith('/')) {
current_page += 'index.html';
}
const links = Array.prototype.slice.call(this.querySelectorAll('a'));
const l = links.length;
for (let i = 0; i < l; ++i) {
const link = links[i];
const href = link.getAttribute('href');
if (href && !href.startsWith('#') && !/^(?:[a-z+]+:)?\/\//.test(href)) {
link.href = path_to_root + href;
}
// The 'index' page is supposed to alias the first chapter in the book.
// Check both with and without the '.html' suffix to be robust against pretty URLs
if (link.href.replace(/\.html$/, '') === current_page.replace(/\.html$/, '')
|| i === 0
&& path_to_root === ''
&& current_page.endsWith('/index.html')) {
link.classList.add('active');
let parent = link.parentElement;
while (parent) {
if (parent.tagName === 'LI' && parent.classList.contains('chapter-item')) {
parent.classList.add('expanded');
}
parent = parent.parentElement;
}
}
}
// Track and set sidebar scroll position
this.addEventListener('click', e => {
if (e.target.tagName === 'A') {
const clientRect = e.target.getBoundingClientRect();
const sidebarRect = this.getBoundingClientRect();
sessionStorage.setItem('sidebar-scroll-offset', clientRect.top - sidebarRect.top);
}
}, { passive: true });
const sidebarScrollOffset = sessionStorage.getItem('sidebar-scroll-offset');
sessionStorage.removeItem('sidebar-scroll-offset');
if (sidebarScrollOffset !== null) {
// preserve sidebar scroll position when navigating via links within sidebar
const activeSection = this.querySelector('.active');
if (activeSection) {
const clientRect = activeSection.getBoundingClientRect();
const sidebarRect = this.getBoundingClientRect();
const currentOffset = clientRect.top - sidebarRect.top;
this.scrollTop += currentOffset - parseFloat(sidebarScrollOffset);
}
} else {
// scroll sidebar to current active section when navigating via
// 'next/previous chapter' buttons
const activeSection = document.querySelector('#mdbook-sidebar .active');
if (activeSection) {
activeSection.scrollIntoView({ block: 'center' });
}
}
// Toggle buttons
const sidebarAnchorToggles = document.querySelectorAll('.chapter-fold-toggle');
function toggleSection(ev) {
ev.currentTarget.parentElement.parentElement.classList.toggle('expanded');
}
Array.from(sidebarAnchorToggles).forEach(el => {
el.addEventListener('click', toggleSection);
});
}
}
window.customElements.define('mdbook-sidebar-scrollbox', MDBookSidebarScrollbox);
// ---------------------------------------------------------------------------
// Support for dynamically adding headers to the sidebar.
(function() {
// This is used to detect which direction the page has scrolled since the
// last scroll event.
let lastKnownScrollPosition = 0;
// This is the threshold in px from the top of the screen where it will
// consider a header the "current" header when scrolling down.
const defaultDownThreshold = 150;
// Same as defaultDownThreshold, except when scrolling up.
const defaultUpThreshold = 300;
// The threshold is a virtual horizontal line on the screen where it
// considers the "current" header to be above the line. The threshold is
// modified dynamically to handle headers that are near the bottom of the
// screen, and to slightly offset the behavior when scrolling up vs down.
let threshold = defaultDownThreshold;
// This is used to disable updates while scrolling. This is needed when
// clicking the header in the sidebar, which triggers a scroll event. It
// is somewhat finicky to detect when the scroll has finished, so this
// uses a relatively dumb system of disabling scroll updates for a short
// time after the click.
let disableScroll = false;
// Array of header elements on the page.
let headers;
// Array of li elements that are initially collapsed headers in the sidebar.
// I'm not sure why eslint seems to have a false positive here.
// eslint-disable-next-line prefer-const
let headerToggles = [];
// This is a debugging tool for the threshold which you can enable in the console.
let thresholdDebug = false;
// Updates the threshold based on the scroll position.
function updateThreshold() {
const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
const windowHeight = window.innerHeight;
const documentHeight = document.documentElement.scrollHeight;
// The number of pixels below the viewport, at most documentHeight.
// This is used to push the threshold down to the bottom of the page
// as the user scrolls towards the bottom.
const pixelsBelow = Math.max(0, documentHeight - (scrollTop + windowHeight));
// The number of pixels above the viewport, at least defaultDownThreshold.
// Similar to pixelsBelow, this is used to push the threshold back towards
// the top when reaching the top of the page.
const pixelsAbove = Math.max(0, defaultDownThreshold - scrollTop);
// How much the threshold should be offset once it gets close to the
// bottom of the page.
const bottomAdd = Math.max(0, windowHeight - pixelsBelow - defaultDownThreshold);
let adjustedBottomAdd = bottomAdd;
// Adjusts bottomAdd for a small document. The calculation above
// assumes the document is at least twice the windowheight in size. If
// it is less than that, then bottomAdd needs to be shrunk
// proportional to the difference in size.
if (documentHeight < windowHeight * 2) {
const maxPixelsBelow = documentHeight - windowHeight;
const t = 1 - pixelsBelow / Math.max(1, maxPixelsBelow);
const clamp = Math.max(0, Math.min(1, t));
adjustedBottomAdd *= clamp;
}
let scrollingDown = true;
if (scrollTop < lastKnownScrollPosition) {
scrollingDown = false;
}
if (scrollingDown) {
// When scrolling down, move the threshold up towards the default
// downwards threshold position. If near the bottom of the page,
// adjustedBottomAdd will offset the threshold towards the bottom
// of the page.
const amountScrolledDown = scrollTop - lastKnownScrollPosition;
const adjustedDefault = defaultDownThreshold + adjustedBottomAdd;
threshold = Math.max(adjustedDefault, threshold - amountScrolledDown);
} else {
// When scrolling up, move the threshold down towards the default
// upwards threshold position. If near the bottom of the page,
// quickly transition the threshold back up where it normally
// belongs.
const amountScrolledUp = lastKnownScrollPosition - scrollTop;
const adjustedDefault = defaultUpThreshold - pixelsAbove
+ Math.max(0, adjustedBottomAdd - defaultDownThreshold);
threshold = Math.min(adjustedDefault, threshold + amountScrolledUp);
}
if (documentHeight <= windowHeight) {
threshold = 0;
}
if (thresholdDebug) {
const id = 'mdbook-threshold-debug-data';
let data = document.getElementById(id);
if (data === null) {
data = document.createElement('div');
data.id = id;
data.style.cssText = `
position: fixed;
top: 50px;
right: 10px;
background-color: 0xeeeeee;
z-index: 9999;
pointer-events: none;
`;
document.body.appendChild(data);
}
data.innerHTML = `
| documentHeight | ${documentHeight.toFixed(1)} |
| windowHeight | ${windowHeight.toFixed(1)} |
| scrollTop | ${scrollTop.toFixed(1)} |
| pixelsAbove | ${pixelsAbove.toFixed(1)} |
| pixelsBelow | ${pixelsBelow.toFixed(1)} |
| bottomAdd | ${bottomAdd.toFixed(1)} |
| adjustedBottomAdd | ${adjustedBottomAdd.toFixed(1)} |
| scrollingDown | ${scrollingDown} |
| threshold | ${threshold.toFixed(1)} |
`;
drawDebugLine();
}
lastKnownScrollPosition = scrollTop;
}
function drawDebugLine() {
if (!document.body) {
return;
}
const id = 'mdbook-threshold-debug-line';
const existingLine = document.getElementById(id);
if (existingLine) {
existingLine.remove();
}
const line = document.createElement('div');
line.id = id;
line.style.cssText = `
position: fixed;
top: ${threshold}px;
left: 0;
width: 100vw;
height: 2px;
background-color: red;
z-index: 9999;
pointer-events: none;
`;
document.body.appendChild(line);
}
function mdbookEnableThresholdDebug() {
thresholdDebug = true;
updateThreshold();
drawDebugLine();
}
window.mdbookEnableThresholdDebug = mdbookEnableThresholdDebug;
// Updates which headers in the sidebar should be expanded. If the current
// header is inside a collapsed group, then it, and all its parents should
// be expanded.
function updateHeaderExpanded(currentA) {
// Add expanded to all header-item li ancestors.
let current = currentA.parentElement;
while (current) {
if (current.tagName === 'LI' && current.classList.contains('header-item')) {
current.classList.add('expanded');
}
current = current.parentElement;
}
}
// Updates which header is marked as the "current" header in the sidebar.
// This is done with a virtual Y threshold, where headers at or below
// that line will be considered the current one.
function updateCurrentHeader() {
if (!headers || !headers.length) {
return;
}
// Reset the classes, which will be rebuilt below.
const els = document.getElementsByClassName('current-header');
for (const el of els) {
el.classList.remove('current-header');
}
for (const toggle of headerToggles) {
toggle.classList.remove('expanded');
}
// Find the last header that is above the threshold.
let lastHeader = null;
for (const header of headers) {
const rect = header.getBoundingClientRect();
if (rect.top <= threshold) {
lastHeader = header;
} else {
break;
}
}
if (lastHeader === null) {
lastHeader = headers[0];
const rect = lastHeader.getBoundingClientRect();
const windowHeight = window.innerHeight;
if (rect.top >= windowHeight) {
return;
}
}
// Get the anchor in the summary.
const href = '#' + lastHeader.id;
const a = [...document.querySelectorAll('.header-in-summary')]
.find(element => element.getAttribute('href') === href);
if (!a) {
return;
}
a.classList.add('current-header');
updateHeaderExpanded(a);
}
// Updates which header is "current" based on the threshold line.
function reloadCurrentHeader() {
if (disableScroll) {
return;
}
updateThreshold();
updateCurrentHeader();
}
// When clicking on a header in the sidebar, this adjusts the threshold so
// that it is located next to the header. This is so that header becomes
// "current".
function headerThresholdClick(event) {
// See disableScroll description why this is done.
disableScroll = true;
setTimeout(() => {
disableScroll = false;
}, 100);
// requestAnimationFrame is used to delay the update of the "current"
// header until after the scroll is done, and the header is in the new
// position.
requestAnimationFrame(() => {
requestAnimationFrame(() => {
// Closest is needed because if it has child elements like .
const a = event.target.closest('a');
const href = a.getAttribute('href');
const targetId = href.substring(1);
const targetElement = document.getElementById(targetId);
if (targetElement) {
threshold = targetElement.getBoundingClientRect().bottom;
updateCurrentHeader();
}
});
});
}
// Takes the nodes from the given head and copies them over to the
// destination, along with some filtering.
function filterHeader(source, dest) {
const clone = source.cloneNode(true);
clone.querySelectorAll('mark').forEach(mark => {
mark.replaceWith(...mark.childNodes);
});
dest.append(...clone.childNodes);
}
// Scans page for headers and adds them to the sidebar.
document.addEventListener('DOMContentLoaded', function() {
const activeSection = document.querySelector('#mdbook-sidebar .active');
if (activeSection === null) {
return;
}
const main = document.getElementsByTagName('main')[0];
headers = Array.from(main.querySelectorAll('h2, h3, h4, h5, h6'))
.filter(h => h.id !== '' && h.children.length && h.children[0].tagName === 'A');
if (headers.length === 0) {
return;
}
// Build a tree of headers in the sidebar.
const stack = [];
const firstLevel = parseInt(headers[0].tagName.charAt(1));
for (let i = 1; i < firstLevel; i++) {
const ol = document.createElement('ol');
ol.classList.add('section');
if (stack.length > 0) {
stack[stack.length - 1].ol.appendChild(ol);
}
stack.push({level: i + 1, ol: ol});
}
// The level where it will start folding deeply nested headers.
const foldLevel = 3;
for (let i = 0; i < headers.length; i++) {
const header = headers[i];
const level = parseInt(header.tagName.charAt(1));
const currentLevel = stack[stack.length - 1].level;
if (level > currentLevel) {
// Begin nesting to this level.
for (let nextLevel = currentLevel + 1; nextLevel <= level; nextLevel++) {
const ol = document.createElement('ol');
ol.classList.add('section');
const last = stack[stack.length - 1];
const lastChild = last.ol.lastChild;
// Handle the case where jumping more than one nesting
// level, which doesn't have a list item to place this new
// list inside of.
if (lastChild) {
lastChild.appendChild(ol);
} else {
last.ol.appendChild(ol);
}
stack.push({level: nextLevel, ol: ol});
}
} else if (level < currentLevel) {
while (stack.length > 1 && stack[stack.length - 1].level > level) {
stack.pop();
}
}
const li = document.createElement('li');
li.classList.add('header-item');
li.classList.add('expanded');
if (level < foldLevel) {
li.classList.add('expanded');
}
const span = document.createElement('span');
span.classList.add('chapter-link-wrapper');
const a = document.createElement('a');
span.appendChild(a);
a.href = '#' + header.id;
a.classList.add('header-in-summary');
filterHeader(header.children[0], a);
a.addEventListener('click', headerThresholdClick);
const nextHeader = headers[i + 1];
if (nextHeader !== undefined) {
const nextLevel = parseInt(nextHeader.tagName.charAt(1));
if (nextLevel > level && level >= foldLevel) {
const toggle = document.createElement('a');
toggle.classList.add('chapter-fold-toggle');
toggle.classList.add('header-toggle');
toggle.addEventListener('click', () => {
li.classList.toggle('expanded');
});
const toggleDiv = document.createElement('div');
toggleDiv.textContent = '❱';
toggle.appendChild(toggleDiv);
span.appendChild(toggle);
headerToggles.push(li);
}
}
li.appendChild(span);
const currentParent = stack[stack.length - 1];
currentParent.ol.appendChild(li);
}
const onThisPage = document.createElement('div');
onThisPage.classList.add('on-this-page');
onThisPage.append(stack[0].ol);
const activeItemSpan = activeSection.parentElement;
activeItemSpan.after(onThisPage);
});
document.addEventListener('DOMContentLoaded', reloadCurrentHeader);
document.addEventListener('scroll', reloadCurrentHeader, { passive: true });
})();