feat(v2): highlight items in the table of content - #1896
Conversation
|
Deploy preview for docusaurus-preview ready! Built with commit 542b7c9 |
|
Deploy preview for docusaurus-2 ready! Built with commit 542b7c9 |
* 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
There was a problem hiding this comment.
If i go to https://deploy-preview-1896--docusaurus-2.netlify.com/docs/introduction/#gitbook
The Gitbook is not highlighted, i have to scroll around or resize first.
Compare it to https://docusaurus.io/docs/en/installation#running-the-example-website
Update: Clicking the right sidebar directly also doesnt highlight that particular section
|
Strange it works fine for me in Chrome (I'm on Linux), but not in Firefox 🤷♂️ |
…cebook#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 * nits * nits
|
There are many misbehaviors from preview:
The behaviors said above appears in both Firefox and Chrome, the screen record I have here shows Chrome: I think the implementation in #1524 is correct and the comments around it serves as good pseudocode. Suggest that we follow it directly. |
Both things work fine for me (the gitbook highlight works fine, also clicking the sidebar update directly) I am going to play around until I can reproduce it.
OK, I am going to test in firefox and see what's going on.
If you want me too I can see the issues that are happening (some of them also happen in v1). Please tell me if you want me to fix the issues described in the comments or you prefer to delete this PR. I did put time on this but I completely understand if you prefer to go another way. |
|
I think the issues need to be fixed before merging, the behavior doesn't feel correct to me atm. |
|
I wont merge until both of u approve :) Just putting stamp 😃 |
|
Great! I am going to work on the fixes. Thanks |
* change(v2): refactor dark toggle into a theme * follow how themes resolve files * let theme hook to pick up default theme by itself
…acebook#1871) * fix issue#1752 when element in side nav is hovered over the color changes. * Update main.css
yangshun
left a comment
There was a problem hiding this comment.
Nice work. This is one of the features that I'm highly anticipating too, thank you for working on this.
Tested on Chrome, Safari and Firefox, and contrary to what @lex111 experienced, the result on Firefox is the best 😮
Some suggestions I have:
- Create a custom hook so that this is reusable by non-theme classic Docs components. In future if we want to have a Bootstrap theme, we can reuse this hook.
- The hook should take in the corresponding class names as function arguments.
DocItemshould import this hook and invoke it with the classnames specific to this theme.
- You might want to take a look at the implementation of #1524 for inspiration on how this was achieved in v1. v1's behavior is great and battle-tested (no complaints about it so far). cc @tusharf5 if he's interested in helping to review.
* misc(v2): address comments * misc(v2): update CHANGELOG
* feat(v2): allow line highlighting * Refactor: use parse-numeric-range for parsing * Add line highlighting for live code blocks * feat(v2): add sticky footer (facebook#1855) * feat(v2): add sticky footer * Update CHANGELOG-2.x.md * Update CHANGELOG-2.x.md * fix(v2): remove empty doc sidebar container (facebook#1870) * docs: showcase user Amphora (facebook#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 (facebook#1874) * docs(v2): showcase user mbt-bundle (facebook#1875) * feat(v2): postcss should only use stage 3 features instead of stage 2 (facebook#1872) * feat(v2): add ability expand all items in doc sidebar (facebook#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 (facebook#1882) * perf(v2): disable hash for css modules localident in dev * changelog * feat(v2): display footer in docs page for consistency (facebook#1883) * feat(v2): display footer in docs page * nits * address review * nits * docs(v2): fix format inline code (facebook#1888) * docs(v2): add docs on useful client api (facebook#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 (facebook#1885) * fix(v2): do not show categories with empty items (facebook#1891) * styles(v2): update infima and fix styles (facebook#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 (facebook#1889) * docs(v2): update plugins, presets and themes docs * ideal image plugin * proof reading * Merge master * refactor(v2): Convert sitemap plugin to TypeScript (facebook#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 (facebook#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 (facebook#1893) * fix(v2): align search icon on small width device * nits * nits * refactor(v2): refactor dark toggle into a hook (facebook#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 (facebook#1900) * misc(v1): use primary color for hovered items in table of contents (facebook#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 (facebook#1895) * misc(v2): v1 backward compatibility for USE_SSH env var (facebook#1880) * misc(v2): address comments * misc(v2): update CHANGELOG
* Update README.md - Fix Broken Link * misc: update URLs to non-HTML versions
lex111
left a comment
There was a problem hiding this comment.
@SantiagoGdaR don't do anything until you get approval from Docusaurus devs, this is just my 2 cents.
| let tableOfContentLinks = []; | ||
|
|
||
| function getActiveHeaderAnchor() { | ||
| const TOP_OFFSET = topOffset; |
There was a problem hiding this comment.
Do you really need to create a constant for this when it is used once? I mean, the code is not so big, and there is no point in duplicating the same value in such a way.
In my opinion it is better to do without it:
- if (top >= 0 && top <= TOP_OFFSET) {}
+ if (top> = 0 && top <= topOffset) {}| ] = useState(undefined); | ||
|
|
||
| useEffect(() => { | ||
| let headersAnchor = []; |
There was a problem hiding this comment.
Is not it more correct to call this var that?
headersAnchor -> headerAnchors
| import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; | ||
| import useBaseUrl from '@docusaurus/useBaseUrl'; | ||
| import DocPaginator from '@theme/DocPaginator'; | ||
| import useTableOfContentHighlight from '@theme/hooks/useTableOfContentHighlight'; |
There was a problem hiding this comment.
Maybe it makes sense TableOfContent shorten to simply toc? It will be easier to read and understand.
useTableOfContentHighlight->useTocHighlighttableOfContentLinkClassName->tocLinkClassName- And so on
| setLastActiveTableOfContentLink(tableOfContentLink); | ||
| } | ||
|
|
||
| function getAnchorValue(tableOfContentLink) { |
There was a problem hiding this comment.
I would consider this solution, it will be faster.
function getAnchorValue(tocLink) {
return decodeURIComponent(
tocLink.href.substring(tocLink.href.indexOf('#') + 1)
);
}| function getActiveHeaderAnchor() { | ||
| const TOP_OFFSET = topOffset; | ||
| let index = 0; | ||
| let activeHeaderAnchor; |
There was a problem hiding this comment.
You must probably explicitly set the default value.
let activeHeaderAnchor = null;| if (activeHeaderAnchor) { | ||
| let index = 0; | ||
| let itemHighlighted = false; | ||
| tableOfContentLinks = document.querySelectorAll( |
There was a problem hiding this comment.
Hmm, I would prefer to use the old-school document.getElementsByClassName (sort of like it's even faster), since the selection goes only by class and it is assumed that only the class will be used, otherwise you need to rename the parameter to tableOfContentLinkSelector and continue use querySelectorAll 🤔
| const [ | ||
| lastActiveTableOfContentLink, | ||
| setLastActiveTableOfContentLink, | ||
| ] = useState(undefined); |
There was a problem hiding this comment.
Use null instead of undefined
|
Thanks @lex111, personally I agree on most of the changes you propose. I am going to work on them or respond with a comment in the case I think we should discuss something further. |
* docs(v2): theme, plugin, and preset config * change tabs to spaces * change theme example
This is much stable and more performant
* 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
|
I understand correctly that we will implement all my suggestions, except the last one, about the concatenating of classes? |
yangshun
left a comment
There was a problem hiding this comment.
I've made the changes. Merging it 🎉
* feat(v2): highlight items in the table of content * refactor: move string to const * refactor(v2): Convert sitemap plugin to TypeScript (facebook#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 (facebook#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 (facebook#1893) * fix(v2): align search icon on small width device * nits * nits * refactor(v2): refactor dark toggle into a hook (facebook#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 (facebook#1900) * misc(v1): use primary color for hovered items in table of contents (facebook#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 (facebook#1895) * misc(v2): v1 backward compatibility for USE_SSH env var (facebook#1880) * misc(v2): address comments * misc(v2): update CHANGELOG * feat(v2): allow line highlighting (facebook#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 (facebook#1855) * feat(v2): add sticky footer * Update CHANGELOG-2.x.md * Update CHANGELOG-2.x.md * fix(v2): remove empty doc sidebar container (facebook#1870) * docs: showcase user Amphora (facebook#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 (facebook#1874) * docs(v2): showcase user mbt-bundle (facebook#1875) * feat(v2): postcss should only use stage 3 features instead of stage 2 (facebook#1872) * feat(v2): add ability expand all items in doc sidebar (facebook#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 (facebook#1882) * perf(v2): disable hash for css modules localident in dev * changelog * feat(v2): display footer in docs page for consistency (facebook#1883) * feat(v2): display footer in docs page * nits * address review * nits * docs(v2): fix format inline code (facebook#1888) * docs(v2): add docs on useful client api (facebook#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 (facebook#1885) * fix(v2): do not show categories with empty items (facebook#1891) * styles(v2): update infima and fix styles (facebook#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 (facebook#1889) * docs(v2): update plugins, presets and themes docs * ideal image plugin * proof reading * Merge master * refactor(v2): Convert sitemap plugin to TypeScript (facebook#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 (facebook#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 (facebook#1893) * fix(v2): align search icon on small width device * nits * nits * refactor(v2): refactor dark toggle into a hook (facebook#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 (facebook#1900) * misc(v1): use primary color for hovered items in table of contents (facebook#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 (facebook#1895) * misc(v2): v1 backward compatibility for USE_SSH env var (facebook#1880) * misc(v2): address comments * misc(v2): update CHANGELOG * docs(v1): remove user Vasern (facebook#1901) * misc: update URLs to non-HTML versions (facebook#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 (facebook#1903) * fix(v2): nested routes should have wildcard/ not found page too * better fix * nits * space * docs(v2): code block line highlighting (facebook#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 (facebook#1907) * fix(v2): webpack modules resolve should prioritize own deps * nits * feat(v2): simplify blog metadata to minimize number of request (facebook#1908) * feat(v2): simplify blog metadata to minimize number of request * remove async * feat(v2): add ability to set custom HTML in footer items (facebook#1905) * docs: update configcat user link (facebook#1911) * fix(v2): docs plugin stability improvement (100% test coverage) (facebook#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 (facebook#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 (facebook#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 (facebook#1915) * docs(v2): Redirect component for easy redirect (facebook#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 (facebook#1917) * fix(v2): regression from prioritizing core node_modules logic * nits * chore: changelog * docs(v1): showcase user Reactive Interaction Gateway (facebook#1918) * chore: bump dependencies * docs(v2): fix typo in advanced plugins (facebook#1926) * docs(v2): fix typos (facebook#1930) * docs(v1): fix links in CHANGELOG (facebook#1931) * fix(v2): @theme/heading should not create anchor if id is not defined (facebook#1925) * docs(v2): theme, plugin, and preset config (facebook#1929) * docs(v2): theme, plugin, and preset config * change tabs to spaces * change theme example * misc: use /usr/bin/env bash to increase portability (facebook#1923) * misc(v1): use Node.js lts version (facebook#1920) This is much stable and more performant * chore: downgrade imagemin (facebook#1933) * fix(v2): add missing key prop in footer items with HTML (facebook#1935) * fix(v2): fix browser window background (facebook#1936) * fix(v2): allows to create tabs with only one item (facebook#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 (facebook#1937) * v2.0.0-alpha.32 * chore(v2): changelog * misc(v2): update TOC highlight * misc(v2): update CHANGELOG


Motivation
Implement the highlight functionality for the table of content links on the scroll and on click events.
The implementation is partially based on the solution implemented in v1 but it is drastically changed to make better use of React.
Resolve issue: #1752
Also relates to: #1524
Have you read the Contributing Guidelines on pull requests?
Yes
Test Plan
When clicking on any of the links of a table of content or while you scroll on a section that contains a table of content you are going to notice that the table of content has the link of the section you have on the screen highlighted.
Tested on Safari and Chrome.
Related PRs
(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)