feat(v2): allow line highlighting #1860

lex111 · 2019-10-19T19:27:05Z

Motivation

In the documentation, it is sometimes useful to highlight individual lines in blocks of code (see the example from React).

This PR adds this feature, see the usage example below.

```js {1,3-5}
function foo() {
  return bar()
    .then(res => {
      return res.doSomething()
    })
}

Lines 1 and between 1 and 2 will be highlighted.

Note: This {n,n-m} format de facto used for such purposes.

The only unresolved question is the default style, i.e. where (what is the path? theme-classic/../Layout/styles.css?) we need to set CSS styles for the highlight-line class so that the user can then override it in own custom.css file.

Have you read the Contributing Guidelines on pull requests?

Yes

docusaurus-bot · 2019-10-19T19:30:51Z

Deploy preview for docusaurus-2 ready!

Built with commit e509311

https://deploy-preview-1860--docusaurus-2.netlify.com

docusaurus-bot · 2019-10-19T19:34:03Z

Deploy preview for docusaurus-preview ready!

Built with commit e509311

https://deploy-preview-1860--docusaurus-preview.netlify.com

yangshun

Thank you for adding this feature! Highly anticipated.

Do you think it makes sense to add this feature to the Live Codeblock as well? I'm leaning towards no but would just like to bring this up. cc @endiliey

packages/docusaurus-theme-classic/src/theme/CodeBlock/index.js

endiliey · 2019-10-20T09:41:24Z

The only unresolved question is the default style, i.e. where (what is the path? theme-classic/../Layout/styles.css?) we need to set CSS styles for the highlight-line class so that the user can then override it in own custom.css file.

Regarding the css, we can do it like gatsby https://www.gatsbyjs.org/packages/gatsby-remark-prismjs/#optional-add-line-highlighting-styles. They have to create their own css there

Do you think it makes sense to add this feature to the Live Codeblock as well? I'm leaning towards no but would just like to bring this up.

Technically yes because we'll want to demo it on our docs as well. >.<

endiliey · 2019-10-20T09:42:09Z

P.S: Documentation needed

lex111 · 2019-10-22T12:28:01Z

Regarding the css, we can do it like gatsby...

There is the .highlight-line class, I need to set default CSS rules for it, in which CSS file to do this?

P.S: Documentation needed

Can you help with this?

yangshun · 2019-10-22T14:18:51Z

@lex111 thanks for this PR, highly appreciated. As for docs, you could mention this new syntax in this section - https://v2.docusaurus.io/docs/markdown-features#syntax-highlighting

Please also rebase

lex111 · 2019-10-22T14:27:55Z

@yangshun I thought it would be faster if you document this feature, especially since I am not familiar with the guidelines that have been adopted, and we will only lose time (review-changes-review).
...And I still have sites that are not finished for migration, and I have a headache with redirects (sorry to mention this again!).

yangshun · 2019-10-22T14:34:41Z

No problem, I can take over that. As for redirects, I think we should handle it in Docusaurus side as a first-class feature since many sites will need it. @endiliey let's find time to work on that?

lex111 · 2019-10-22T14:43:08Z

Conflicts resolved.

I thought to look into the source code v1, there seems to be a file generated with the Redirect component. I don’t know how to do it in the second version... but time is running out! I still wanted to complete migration of requested sites.

endiliey · 2019-10-22T15:01:06Z

There is no way to redirect in v1. That redirect component is only used to redirect docs/id to docs/en/id if language is enabled. Actually there’s a way to do it right now in v2 that I think is a very good solution to redirect. The key is using `postBuild` plugin hook to create a HTML redirect. User can define `fromPath` and `toPath`. Maybe something like ```json { "redirects": [ { "from": "oldpage.html", "to": "newpage.html" }, { "from": "olddir/oldpage.html", "to": "newdir/newpage.html" }, ] } ``` The HTML redirect can look like this ```html <!DOCTYPE HTML> <html lang="en-US"> <head> <meta charset="UTF-8"> <meta http-equiv="refresh" content="0; url=docs/id-of-doc-to-land-on.html"> <script type="text/javascript"> window.location.href = 'docs/id-of-doc-to-land-on.html'; </script> <title>Your Site Title Here</title> </head> <body> If you are not redirected automatically, follow this <a href="docs/id-of-doc-to-land-on.html">link</a>. </body> </html> ``` We shouldn’t do client side redirect because not every static hosting service support 404 page or fallback to index.html. Some host like netlify is able to do server side redirect, but not all can do it. Sent from Mail for Windows 10

lex111 · 2019-10-22T15:13:17Z

There is no way to redirect in v1. That redirect component is only used to redirect docs/id to docs/en/id if language is enabled.

That was an assumption, I'm not familiar with the internals Docusaurus. I thought you could do something similar in v2...

There is no way to redirect in v1. That redirect component is only used to redirect docs/id to docs/en/id if language is enabled.

Wow, although I don’t like the need to manually set urls.. but OK, how do I programmatically get a list of all pages?

We shouldn’t do client side redirect because not every static hosting service support 404 page or fallback to index.html. Some host like netlify is able to do server side redirect, but not all can do it.

I completely agree, so I did not consider such an option.

endiliey · 2019-10-22T15:17:59Z

Can do it like sitemap https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-plugin-sitemap/src/index.js Sent from Mail for Windows 10 From: Alexey Pyltsyn Sent: Tuesday, 22 October 2019 10:13 PM To: facebook/docusaurus Cc: Endi; Mention Subject: Re: [facebook/docusaurus] feat(v2): allow line highlighting (#1860) There is no way to redirect in v1. That redirect component is only used to redirect docs/id to docs/en/id if language is enabled. That was an assumption, I'm not familiar with the internals Docusaurus. I thought you could do something similar in v2... There is no way to redirect in v1. That redirect component is only used to redirect docs/id to docs/en/id if language is enabled. Wow, although I don’t like the need to manually set urls.. but OK, how do I programmatically get a list of all pages? We shouldn’t do client side redirect because not every static hosting service support 404 page or fallback to index.html. Some host like netlify is able to do server side redirect, but not all can do it. I completely agree, so I did not consider such an option. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

* feat(v2): add sticky footer * Update CHANGELOG-2.x.md * Update CHANGELOG-2.x.md

endiliey · 2019-10-23T04:20:52Z

There is the .highlight-line class, I need to set default CSS rules for it, in which CSS file to do this?

On each co-located styles.css. Let's just convert this css module to traditional css for easy override

eg: https://github.com/facebook/docusaurus/blob/2b0cc9bc32711a02d38255160a1fffdcc31bdceb/packages/docusaurus-theme-classic/src/theme/CodeBlock/styles.module.css

wdyt @yangshun

lex111 · 2019-10-23T08:09:08Z

This is the CSS Module file, I meant the regular one. I was only thinking about overriding styles to highlight the line.

endiliey · 2019-10-24T03:00:51Z

Hmm i was thinking to rename the css modules file to just a normal css file. There is no global css file in v2 like v1 (except the infima css).

* 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

yangshun · 2019-10-24T05:04:30Z

I will patch this PR and make the changes when I get the time (probably this weekend or early next week).

yangshun · 2019-10-24T05:05:27Z

Btw @lex111 we would like to send you a Docusaurus plushie for your great contributions. If you're interested would you PM me your mailing address on Discord? Thanks!

…facebook#1872)

* perf(v2): disable hash for css modules localident in dev * changelog

* feat(v2): display footer in docs page * nits * address review * nits

* 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 plugins, presets and themes docs * ideal image plugin * proof reading * Merge master

* 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

…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

* 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

…1895)

* misc(v2): address comments * misc(v2): update CHANGELOG

# Conflicts: # CHANGELOG-2.x.md # packages/docusaurus-theme-classic/package.json

yangshun · 2019-10-27T22:19:04Z

I've resolved the conflicts. I want to add the docs for this feature but I can only do so after using this feature in our docs and adding some highlight classes (so I know what docs to write).

Hence I will merge this PR first and make another PR to make the docs and CSS updates.

lex111 · 2019-10-27T22:20:39Z

@yangshun thank you!

yangshun · 2019-10-27T22:24:06Z

@lex111 I should thank you for being such a rockstar 🎸

* 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

bravo-kernel · 2019-11-10T09:13:36Z

👏

feat(v2): allow line highlighting

8657816

facebook-github-bot added the CLA Signed Signed Facebook CLA label Oct 19, 2019

yangshun suggested changes Oct 20, 2019

View reviewed changes

packages/docusaurus-theme-classic/src/theme/CodeBlock/index.js Outdated Show resolved Hide resolved

lex111 added 2 commits October 22, 2019 15:19

Refactor: use parse-numeric-range for parsing

a200e47

Add line highlighting for live code blocks

a2947a4

lex111 force-pushed the lh branch from 8536f42 to a2947a4 Compare October 22, 2019 12:23

Merge branch 'master' into lh

2b0cc9b

lex111 added 2 commits October 22, 2019 17:16

feat(v2): add sticky footer (facebook#1855)

68d5adf

* feat(v2): add sticky footer * Update CHANGELOG-2.x.md * Update CHANGELOG-2.x.md

fix(v2): remove empty doc sidebar container (facebook#1870)

11f9977

xtellurian and others added 3 commits October 23, 2019 21:17

docs: showcase user Amphora (facebook#1873)

262dca3

* 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)

0e66c90

docs(v2): showcase user mbt-bundle (facebook#1875)

91703eb

feat(v2): postcss should only use stage 3 features instead of stage 2 (…

22fb869

…facebook#1872)

endiliey and others added 20 commits October 25, 2019 00:01

perf(v2): disable hash for css modules localident in dev (facebook#1882)

8bcb5dc

* perf(v2): disable hash for css modules localident in dev * changelog

feat(v2): display footer in docs page for consistency (facebook#1883)

b347968

* feat(v2): display footer in docs page * nits * address review * nits

docs(v2): fix format inline code (facebook#1888)

11548da

docs(v2): update config docs (facebook#1885)

a9f752c

fix(v2): do not show categories with empty items (facebook#1891)

60a4d1d

styles(v2): update infima and fix styles (facebook#1892)

9fdda55

fix(v2): wrong css class

3cc1330

v2.0.0-alpha.31

d4342dc

chore(v2): update docs and changelog

242c9e0

docs(v2): update plugins, presets and themes docs (facebook#1889)

2bbfbf8

* docs(v2): update plugins, presets and themes docs * ideal image plugin * proof reading * Merge master

refactor(v2): Convert sitemap plugin to TypeScript (facebook#1894)

c23f981

* 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 (fa…

fabaf77

…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 (facebook#1893)

84462e2

* fix(v2): align search icon on small width device * nits * nits

refactor(v2): refactor dark toggle into a hook (facebook#1899)

01f4d9a

* 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)

98679b5

misc(v1): use primary color for hovered items in table of contents (f…

f14b6ee

…acebook#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#…

421598e

…1895)

misc(v2): v1 backward compatibility for USE_SSH env var (facebook#1880)

812a30b

* misc(v2): address comments * misc(v2): update CHANGELOG

Merge branch 'lh' of https://github.com/lex111/docusaurus into lex111-lh

e509311

# Conflicts: # CHANGELOG-2.x.md # packages/docusaurus-theme-classic/package.json

lex111 requested a review from endiliey as a code owner October 27, 2019 22:17

yangshun approved these changes Oct 27, 2019

View reviewed changes

yangshun merged commit 9c69dfd into facebook:master Oct 27, 2019

lex111 deleted the lh branch October 27, 2019 22:20

yangshun mentioned this pull request Oct 28, 2019

docs(v2): code block line highlighting #1904

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): allow line highlighting #1860

feat(v2): allow line highlighting #1860

lex111 commented Oct 19, 2019

docusaurus-bot commented Oct 19, 2019 •

edited

Loading

docusaurus-bot commented Oct 19, 2019 •

edited

Loading

yangshun left a comment

endiliey commented Oct 20, 2019 •

edited

Loading

endiliey commented Oct 20, 2019

lex111 commented Oct 22, 2019

yangshun commented Oct 22, 2019 •

edited

Loading

lex111 commented Oct 22, 2019

yangshun commented Oct 22, 2019

lex111 commented Oct 22, 2019

endiliey commented Oct 22, 2019 via email

lex111 commented Oct 22, 2019

endiliey commented Oct 22, 2019 via email

endiliey commented Oct 23, 2019 •

edited

Loading

lex111 commented Oct 23, 2019 •

edited

Loading

endiliey commented Oct 24, 2019

yangshun commented Oct 24, 2019 •

edited

Loading

yangshun commented Oct 24, 2019

yangshun commented Oct 27, 2019

lex111 commented Oct 27, 2019

yangshun commented Oct 27, 2019

bravo-kernel commented Nov 10, 2019

feat(v2): allow line highlighting #1860

feat(v2): allow line highlighting #1860

Conversation

lex111 commented Oct 19, 2019

Motivation

Have you read the Contributing Guidelines on pull requests?

docusaurus-bot commented Oct 19, 2019 • edited Loading

docusaurus-bot commented Oct 19, 2019 • edited Loading

yangshun left a comment

Choose a reason for hiding this comment

endiliey commented Oct 20, 2019 • edited Loading

endiliey commented Oct 20, 2019

lex111 commented Oct 22, 2019

yangshun commented Oct 22, 2019 • edited Loading

lex111 commented Oct 22, 2019

yangshun commented Oct 22, 2019

lex111 commented Oct 22, 2019

endiliey commented Oct 22, 2019 via email

lex111 commented Oct 22, 2019

endiliey commented Oct 22, 2019 via email

endiliey commented Oct 23, 2019 • edited Loading

lex111 commented Oct 23, 2019 • edited Loading

endiliey commented Oct 24, 2019

yangshun commented Oct 24, 2019 • edited Loading

yangshun commented Oct 24, 2019

yangshun commented Oct 27, 2019

lex111 commented Oct 27, 2019

yangshun commented Oct 27, 2019

bravo-kernel commented Nov 10, 2019

docusaurus-bot commented Oct 19, 2019 •

edited

Loading

docusaurus-bot commented Oct 19, 2019 •

edited

Loading

endiliey commented Oct 20, 2019 •

edited

Loading

yangshun commented Oct 22, 2019 •

edited

Loading

endiliey commented Oct 23, 2019 •

edited

Loading

lex111 commented Oct 23, 2019 •

edited

Loading

yangshun commented Oct 24, 2019 •

edited

Loading