feat(v2): highlight items in the table of content (#1896)

* feat(v2): highlight items in the table of content * refactor: move string to const * refactor(v2): Convert sitemap plugin to TypeScript (#1894) * Convert sitemap plugin to TypeScript Test - enabled the sitemap plugin in the v2 website and verified that the sitemap is created after running `docusaurus build`. * Addressing review comments * perf(v2): significantly reduce bundle size & initial html payload (#1898) * perf(v2): reduce bundle size significantly with super short chunk name and registry * changelog * use hash:8 as id for better long term caching * even shorter filename. slice contenthash * fix(v2): align search icon on small width device (#1893) * fix(v2): align search icon on small width device * nits * nits * refactor(v2): refactor dark toggle into a hook (#1899) * change(v2): refactor dark toggle into a theme * follow how themes resolve files * let theme hook to pick up default theme by itself * perf(v2): reduce memory usage consumption (#1900) * misc(v1): use primary color for hovered items in table of contents (#1871) * fix issue#1752 when element in side nav is hovered over the color changes. * Update main.css * fix(v1): mobile safari search input misalignment in header (#1895) * misc(v2): v1 backward compatibility for USE_SSH env var (#1880) * misc(v2): address comments * misc(v2): update CHANGELOG * feat(v2): allow line highlighting (#1860) * feat(v2): allow line highlighting * Refactor: use parse-numeric-range for parsing * Add line highlighting for live code blocks * feat(v2): add sticky footer (#1855) * feat(v2): add sticky footer * Update CHANGELOG-2.x.md * Update CHANGELOG-2.x.md * fix(v2): remove empty doc sidebar container (#1870) * docs: showcase user Amphora (#1873) * Add Amphora Data link to users Adds Amphora Data to the list of users * Add Amphora Data logo * fix case of image path * Move Image into users directory * use black amphora image * fix(v2): fix search input blur on desktop (#1874) * docs(v2): showcase user mbt-bundle (#1875) * feat(v2): postcss should only use stage 3 features instead of stage 2 (#1872) * feat(v2): add ability expand all items in doc sidebar (#1876) * feat(v2): add ability expand all items in doc sidebar * Fix tests * Refactor: use themeConfig * Improve docs * Revert unnecessary changes * Refactor: better consistency * Revert extra change * Refactor: use useDocusaurusContext to get config value * chore(v2): update changelog * chore(v2): update showcase and broken link * perf(v2): disable hash for css modules localident in dev (#1882) * perf(v2): disable hash for css modules localident in dev * changelog * feat(v2): display footer in docs page for consistency (#1883) * feat(v2): display footer in docs page * nits * address review * nits * docs(v2): fix format inline code (#1888) * docs(v2): add docs on useful client api (#1890) * docs(v2): add docs on useful client api * Update docusaurus-core.md * Update website/docs/docusaurus-core.md * Update website/docs/docusaurus-core.md * Update website/docs/docusaurus-core.md * Update website/docs/docusaurus-core.md * docs(v2): update config docs (#1885) * fix(v2): do not show categories with empty items (#1891) * styles(v2): update infima and fix styles (#1892) * fix(v2): wrong css class * v2.0.0-alpha.31 * chore(v2): update docs and changelog * docs(v2): update plugins, presets and themes docs (#1889) * docs(v2): update plugins, presets and themes docs * ideal image plugin * proof reading * Merge master * refactor(v2): Convert sitemap plugin to TypeScript (#1894) * Convert sitemap plugin to TypeScript Test - enabled the sitemap plugin in the v2 website and verified that the sitemap is created after running `docusaurus build`. * Addressing review comments * perf(v2): significantly reduce bundle size & initial html payload (#1898) * perf(v2): reduce bundle size significantly with super short chunk name and registry * changelog * use hash:8 as id for better long term caching * even shorter filename. slice contenthash * fix(v2): align search icon on small width device (#1893) * fix(v2): align search icon on small width device * nits * nits * refactor(v2): refactor dark toggle into a hook (#1899) * change(v2): refactor dark toggle into a theme * follow how themes resolve files * let theme hook to pick up default theme by itself * perf(v2): reduce memory usage consumption (#1900) * misc(v1): use primary color for hovered items in table of contents (#1871) * fix issue#1752 when element in side nav is hovered over the color changes. * Update main.css * fix(v1): mobile safari search input misalignment in header (#1895) * misc(v2): v1 backward compatibility for USE_SSH env var (#1880) * misc(v2): address comments * misc(v2): update CHANGELOG * docs(v1): remove user Vasern (#1901) * misc: update URLs to non-HTML versions (#1902) * Update README.md - Fix Broken Link * misc: update URLs to non-HTML versions * misc(v2): improve index page SEO score * fix(v2): accessing /docs or /docs/xxxx should not be empty (#1903) * fix(v2): nested routes should have wildcard/ not found page too * better fix * nits * space * docs(v2): code block line highlighting (#1904) * docs(v2): code block line highlighting * misc: update CHANGELOG * misc: respond to review * docs: add line highlighting to the template * fix(v2): webpack modules resolve should prioritize @docusaurus/core own deps (#1907) * fix(v2): webpack modules resolve should prioritize own deps * nits * feat(v2): simplify blog metadata to minimize number of request (#1908) * feat(v2): simplify blog metadata to minimize number of request * remove async * feat(v2): add ability to set custom HTML in footer items (#1905) * docs: update configcat user link (#1911) * fix(v2): docs plugin stability improvement (100% test coverage) (#1912) * update jest config * add more tests on docs plugin * fix(v2): docs plugin should not add routes if there are no docs * fix * rm -rf coverage * nits * update * docs(v2): add windows batch instructions for publishing to gh pages (#1914) * docs: add windows batch instructions for publishing to gh pages * docs: add windows batch instructions on the v2 website * fix(v2): custom searchbar should appear even if themeconfig.algolia is undefined (#1909) * fix(v2): custom searchbar should appear even if themeconfig.algolia is undefined * nits * Docs docs * inaccuracy * changelog * nits * fix(v2): missing/hidden algolia search suggestion result (#1915) * docs(v2): Redirect component for easy redirect (#1913) * docs(v2): Redirect component for easy redirect * typo * docs * Update website/docs/docusaurus-core.md Co-Authored-By: Alexey Pyltsyn <lex61rus@gmail.com> * Update docusaurus-core.md * refactor: changes after comments (use custom hooks, code changes, fix bugs) * fix(v2): regression from prioritizing core node_modules logic (#1917) * fix(v2): regression from prioritizing core node_modules logic * nits * chore: changelog * docs(v1): showcase user Reactive Interaction Gateway (#1918) * chore: bump dependencies * docs(v2): fix typo in advanced plugins (#1926) * docs(v2): fix typos (#1930) * docs(v1): fix links in CHANGELOG (#1931) * fix(v2): @theme/heading should not create anchor if id is not defined (#1925) * docs(v2): theme, plugin, and preset config (#1929) * docs(v2): theme, plugin, and preset config * change tabs to spaces * change theme example * misc: use /usr/bin/env bash to increase portability (#1923) * misc(v1): use Node.js lts version (#1920) This is much stable and more performant * chore: downgrade imagemin (#1933) * fix(v2): add missing key prop in footer items with HTML (#1935) * fix(v2): fix browser window background (#1936) * fix(v2): allows to create tabs with only one item (#1934) * fix(v2): allow to create tabs with only one item It was not possible to have tabs containing only one tab item, so the code below crashed ``` <Tabs defaultValue="SomeFile.js" values={[ { label: "SomeFile.js", value: "SomeFile.js" } ]} > <TabItem value="SomeFile.js"> Tab content </TabItem> </Tabs> ``` * Update index.js * fix(v2): remove redundant npm script in classic template (#1937) * v2.0.0-alpha.32 * chore(v2): changelog * misc(v2): update TOC highlight * misc(v2): update CHANGELOG
2025-05-09 15:17:23 +02:00 · 2019-11-04 19:26:07 -06:00 · 2019-11-04 19:26:07 -06:00 · 3e58062b91
commit 3e58062b91
parent 5909b49915
5 changed files with 100 additions and 10 deletions
--- a/CHANGELOG-2.x.md
+++ b/CHANGELOG-2.x.md
@ -2,11 +2,14 @@

 ## Unreleased

+- Add table of contents highlighting on scroll.
+
 ## 2.0.0-alpha.32

 ### Features
- Add `<Redirect>` component for easy client side redirect.
-Example Usage:
+
+- Add `<Redirect>` component for easy client side redirect. Example Usage:
+
 ```js
 import React from 'react';
 import {Redirect} from '@docusaurus/router';
@ -15,19 +18,21 @@ function Home() {
  return <Redirect to="/docs/test" />;
 }
 ```
+
 - Allow user to add custom HTML to footer items. [#1905](https://github.com/facebook/docusaurus/pull/1905)
- Added code block line highlighting feature (thanks @lex111)! If you have previously swizzled the `CodeBlock` theme component, it is recommended to update your source code to have this feature.
-([#1860](https://github.com/facebook/Docusaurus/issues/1860))
+- Added code block line highlighting feature (thanks @lex111)! If you have previously swizzled the `CodeBlock` theme component, it is recommended to update your source code to have this feature. ([#1860](https://github.com/facebook/Docusaurus/issues/1860))

 ### Bug Fixes
+
 - Fix `@theme/Tabs` component to be able to create tabs with only one item.
 - Fix MDX `@theme/Heading` component. If there is no id, it should not create anchor link.
- Fixed a bug in which if `themeConfig.algolia` is not defined, the custom searchbar won't appear.
-If you've swizzled Algolia `SearchBar` component before, please update your source code otherwise CSS might break. See [#1909](https://github.com/facebook/docusaurus/pull/1909/files) for reference.
+- Fixed a bug in which if `themeConfig.algolia` is not defined, the custom searchbar won't appear. If you've swizzled Algolia `SearchBar` component before, please update your source code otherwise CSS might break. See [#1909](https://github.com/facebook/docusaurus/pull/1909/files) for reference.
+
 ```js
 - <Fragment>
 + <div className="navbar__search" key="search-box">
 ```
+
 - Slightly adjust search icon position to be more aligned on small width device. ([#1893](https://github.com/facebook/Docusaurus/issues/1893))
 - Fix algolia styling bug, previously search suggestion result is sometimes hidden. ([#1915](https://github.com/facebook/Docusaurus/issues/1915))
 - Changed the way we read the `USE_SSH` env variable during deployment to be the same as in v1.
@ -36,12 +41,13 @@ If you've swizzled Algolia `SearchBar` component before, please update your sour
 - Fix a bug where docs plugin add `/docs` route even if docs folder is empty. We also improved docs plugin test coverage to 100% for stability before working on docs versioning. ([#1912](https://github.com/facebook/Docusaurus/issues/1912))

 ### Performance Improvement
+
 - Reduce memory usage consumption. ([#1900](https://github.com/facebook/Docusaurus/issues/1900))
 - Significantly reduce main bundle size and initial HTML payload on production build. Generated files from webpack is also shorter in name. ([#1898](https://github.com/facebook/Docusaurus/issues/1898))
- Simplify blog metadata. Previously, accessing `/blog/post-xxx` will request for next and prev blog post metadata too aside from target post metadata. We should only request target post metadata. 
-([#1908](https://github.com/facebook/Docusaurus/issues/1908))
+- Simplify blog metadata. Previously, accessing `/blog/post-xxx` will request for next and prev blog post metadata too aside from target post metadata. We should only request target post metadata. ([#1908](https://github.com/facebook/Docusaurus/issues/1908))

 ### Others
+
 - Convert sitemap plugin to TypeScript. ([#1894](https://github.com/facebook/Docusaurus/issues/1894))
 - Refactor dark mode toggle into a hook. ([#1899](https://github.com/facebook/Docusaurus/issues/1899))

--- a/packages/docusaurus-theme-classic/src/theme/DocItem/index.js
+++ b/packages/docusaurus-theme-classic/src/theme/DocItem/index.js
@ -11,16 +11,23 @@ import Head from '@docusaurus/Head';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import DocPaginator from '@theme/DocPaginator';
+import useTOCHighlight from '@theme/hooks/useTOCHighlight';

 import styles from './styles.module.css';

+const LINK_CLASS_NAME = 'contents__link';
+const ACTIVE_LINK_CLASS_NAME = 'contents__link--active';
+const TOP_OFFSET = 100;
+
 function Headings({headings, isChild}) {
+  useTOCHighlight(LINK_CLASS_NAME, ACTIVE_LINK_CLASS_NAME, TOP_OFFSET);
+
  if (!headings.length) return null;
  return (
    <ul className={isChild ? '' : 'contents contents__left-border'}>
      {headings.map(heading => (
        <li key={heading.id}>
-          <a href={`#${heading.id}`} className="contents__link">
+          <a href={`#${heading.id}`} className={LINK_CLASS_NAME}>
            {heading.value}
          </a>
          <Headings isChild headings={heading.children} />
--- a/packages/docusaurus-theme-classic/src/theme/Navbar/index.js
+++ b/packages/docusaurus-theme-classic/src/theme/Navbar/index.js
@ -17,7 +17,7 @@ import SearchBar from '@theme/SearchBar';

 import classnames from 'classnames';

-import useTheme from '@theme/hooks/theme';
+import useTheme from '@theme/hooks/useTheme';

 import styles from './styles.module.css';

--- a/packages/docusaurus-theme-classic/src/theme/hooks/useTOCHighlight.js
+++ b/packages/docusaurus-theme-classic/src/theme/hooks/useTOCHighlight.js
@ -0,0 +1,77 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {useEffect, useState} from 'react';
+
+function useTOCHighlight(linkClassName, linkActiveClassName, topOffset) {
+  const [lastActiveLink, setLastActiveLink] = useState(undefined);
+
+  useEffect(() => {
+    let headersAnchors = [];
+    let links = [];
+
+    function setActiveLink() {
+      function getActiveHeaderAnchor() {
+        let index = 0;
+        let activeHeaderAnchor = null;
+
+        headersAnchors = document.getElementsByClassName('anchor');
+        while (index < headersAnchors.length && !activeHeaderAnchor) {
+          const headerAnchor = headersAnchors[index];
+          const {top} = headerAnchor.getBoundingClientRect();
+
+          if (top >= 0 && top <= topOffset) {
+            activeHeaderAnchor = headerAnchor;
+          }
+
+          index += 1;
+        }
+
+        return activeHeaderAnchor;
+      }
+
+      const activeHeaderAnchor = getActiveHeaderAnchor();
+
+      if (activeHeaderAnchor) {
+        let index = 0;
+        let itemHighlighted = false;
+
+        links = document.getElementsByClassName(linkClassName);
+        while (index < links.length && !itemHighlighted) {
+          const link = links[index];
+          const {href} = link;
+          const anchorValue = decodeURIComponent(
+            href.substring(href.indexOf('#') + 1),
+          );
+
+          if (activeHeaderAnchor.id === anchorValue) {
+            if (lastActiveLink) {
+              lastActiveLink.classList.remove(linkActiveClassName);
+            }
+            link.classList.add(linkActiveClassName);
+            setLastActiveLink(link);
+            itemHighlighted = true;
+          }
+
+          index += 1;
+        }
+      }
+    }
+
+    document.addEventListener('scroll', setActiveLink);
+    document.addEventListener('resize', setActiveLink);
+
+    setActiveLink();
+
+    return () => {
+      document.removeEventListener('scroll', setActiveLink);
+      document.removeEventListener('resize', setActiveLink);
+    };
+  });
+}
+
+export default useTOCHighlight;
--- a/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.js
+++ b/packages/docusaurus-theme-classic/src/theme/hooks/useTheme.js