Update to docusaurus 2 #193

jeddy3 · 2021-05-30T10:11:20Z

Which issue, if any, is this issue related to?

Closes #125
Supercedes #174

Is there anything in the PR that needs further explanation?

Rebasing the other branch was a PITA as it was a few months old.

This pull requests takes @m-allanson work and layers it on the latest code.

jeddy3 · 2021-05-30T10:27:23Z

Deploy preview is at:
https://deploy-preview-193--stylelint.netlify.app/

I believe the only thing not working is the validity colours for the examples on each rule page. I think we can deploy without it as it's a nice-to-have enhancement. Then, when someone has time, they can look into the proper docusaurus 2 way of achieving that behaviour.

scripts/generate-docs.mjs

patches/stylelint+13.13.1.patch

package.json

netlify.toml

ybiquitous · 2021-05-31T04:31:10Z

I believe the only thing not working is the validity colours for the examples on each rule page. I think we can deploy without it as it's a nice-to-have enhancement. Then, when someone has time, they can look into the proper docusaurus 2 way of achieving that behaviour.

The current script pattern-validity.js depends on DOM manipulation, but it seems difficult to take the same way due to the Docusaurus v2 rendering system change.

stylelint.io/website/static/js/pattern-validity.js

Line 1 in b7ac0bf

document.addEventListener('DOMContentLoaded', () => {

So, I suggest a different way to process Markdown files, instead of DOM manipulation. For example, the following way just adds emojis, not changing the background color via CSS:

diff --git a/scripts/generate-docs.mjs b/scripts/generate-docs.mjs
index c72d134..0114430 100644
--- a/scripts/generate-docs.mjs
+++ b/scripts/generate-docs.mjs
@@ -4,21 +4,46 @@ import * as path from 'path';
 import { default as remark } from 'remark';
 import { visit } from 'unist-util-visit';
 
+function rewriteLink(options) {
+	function visitor(node) {
+		node.url = options.rewriter(node.url);
+	}
+
+	function transform(tree) {
+		visit(tree, ['link'], visitor);
+	}
+
+	return transform;
+}
+
+function addSymbolToViolationExample() {
+	function visitor(node) {
+		const children = node.children;
+
+		if (
+			children[0].value?.startsWith('The following pattern') &&
+			children[children.length - 1].value?.includes('considered violation')
+		) {
+			const isNotViolation = children[1]?.type === 'emphasis';
+
+			children.unshift({
+				type: 'text',
+				value: isNotViolation ? '👍 ' : '👎 ',
+			});
+		}
+	}
+
+	function transform(tree) {
+		visit(tree, ['paragraph'], visitor);
+	}
+
+	return transform;
+}
+
 function processMarkdown(file, { rewriter }) {
-	function rewriteLink(options) {
-		function visitor(node) {
-			node.url = options.rewriter(node.url);
-		}
-
-		function transform(tree) {
-			visit(tree, ['link'], visitor);
-		}
-
-		return transform;
-	}
-
 	const content = remark()
 		.use(rewriteLink, { rewriter })
+		.use(addSymbolToViolationExample)
 		.processSync(fs.readFileSync(file, 'utf8'))
 		.toString();

Result:

jeddy3 · 2021-05-31T08:32:12Z

@ybiquitous Using remark to modify the markdown is a much cleaner solution! Would it be difficult to wrap the code fences that follow one of the trigger paragraphs in a <div> with the appropriate class?

For example:

Given:

    ["opacity"]

The following patterns are considered violations:

<div class="invalid-pattern">

```css
a { opacity: 5ff0% }
```

</div>

<div class="invalid-pattern">

```css
a { color: rgb(0 0 0 / 0.5) }
```

</div>

The following patterns are *not* considered violations:

<div class="valid-pattern">

```css
a { opacity: 0.5 }
```

</div>

<div class="valid-pattern">

```css
a { color: rgb(0 0 0 / 50%) }
```

</div>

A similar transform is used here.

The logic would be:

for each trigger paragraph
wrap the the following code fences in a div (with the appropriate class)
until a heading or another trigger paragraph is reached

I think that'll cover all cases we have in our rule READMEs.

We'd then be able to do:

Which is less noisy and easier to scan than emojis, especially when a rule has many options.

ybiquitous · 2021-05-31T09:04:59Z

@jeddy3 Looks good! I will look into the way. 💪🏼

jeddy3 · 2021-05-31T09:11:53Z

FYI, the styling in the screenshot above was achieved by updating custom.css to:

.valid-pattern .prism-code {
  box-shadow: 0 -2px 0 0 green;
}

.invalid-pattern .prism-code {
  box-shadow: 0 -2px 0 0 crimson;
}

ybiquitous · 2021-05-31T13:26:47Z

@jeddy3 Thank you for the advice. Perhaps, the following code should produce what you expect:

diff --git a/scripts/generate-docs.mjs b/scripts/generate-docs.mjs
index c72d134..322e66e 100644
--- a/scripts/generate-docs.mjs
+++ b/scripts/generate-docs.mjs
@@ -4,21 +4,75 @@ import * as path from 'path';
 import { default as remark } from 'remark';
 import { visit } from 'unist-util-visit';
 
+function rewriteLink(options) {
+	function visitor(node) {
+		node.url = options.rewriter(node.url);
+	}
+
+	function transform(tree) {
+		visit(tree, ['link'], visitor);
+	}
+
+	return transform;
+}
+
+function wrapViolationExample() {
+	function visitor(node, index, parent) {
+		const isInvalid = node.children[1]?.children[0]?.value === 'not';
+		const className = isInvalid ? 'invalid-pattern' : 'valid-pattern';
+		const wrapperStart = { type: 'html', value: `<div class="${className}">` };
+		const wrapperEnd = { type: 'html', value: '</div>' };
+
+		// Insert to the next position of the paragraph
+		parent.children.splice(index + 1, 0, wrapperStart);
+
+		const childrenLength = parent.children.length;
+
+		// Find the end position
+		let endIndex = index + 1;
+
+		while (endIndex < childrenLength) {
+			const child = parent.children[endIndex];
+
+			if (child.type === 'paragraph' || child.type === 'heading') {
+				break;
+			}
+
+			endIndex++;
+		}
+
+		// Insert to the end position
+		if (endIndex === childrenLength) {
+			parent.children.push(wrapperEnd);
+		} else {
+			parent.children.splice(endIndex, 0, wrapperEnd);
+		}
+	}
+
+	function test(node) {
+		if (!node.children) return false;
+
+		// There can be an `emphasis` node with "not" between the `first` and `last` nodes
+		const [first, , last] = node.children;
+		const text = (first?.value ?? '').trimEnd() + (last?.value ?? '');
+
+		return [
+			'The following patterns are considered violations:',
+			'The following pattern is considered a violation:',
+		].includes(text);
+	}
+
+	function transform(tree) {
+		visit(tree, test, visitor);
+	}
+
+	return transform;
+}
+
 function processMarkdown(file, { rewriter }) {
-	function rewriteLink(options) {
-		function visitor(node) {
-			node.url = options.rewriter(node.url);
-		}
-
-		function transform(tree) {
-			visit(tree, ['link'], visitor);
-		}
-
-		return transform;
-	}
-
 	const content = remark()
 		.use(rewriteLink, { rewriter })
+		.use(wrapViolationExample)
 		.processSync(fs.readFileSync(file, 'utf8'))
 		.toString();

package.json

src/pages/demo.js

package.json

jeddy3 · 2021-06-01T11:23:56Z

Perhaps, the following code should produce what you expect:

Many thanks! Looks great. I tweaked it a little to close on either a heading or a trigger paragraph, rather than any paragraph, as sometimes we have paragraphs within validity blocks, e.g. old color-no-hex page & new color-no-hex page

Funnily enough, we used to use remark to do the validity stuff 4 years ago when the website was built using Phenomic. Kinda odd that we're back to using React again all these year later.

jeddy3 · 2021-06-01T11:24:22Z

I think that's everything done now. Whatcha think, shall we push it live?

ybiquitous

@jeddy3 This is great work! Especially, I like the dark mode! ❤️

hudochenkov · 2021-06-01T19:36:51Z

Great job!

Is it right that Docusaurus is no longer a static website generator? Or it could be configured as such?

jeddy3 · 2021-06-01T20:35:26Z

Is it right that Docusaurus is not longer a static website generator?

It's an SSG with client-side routing kicking in once the requested page has downloaded. Best of both worlds, e.g. works without JavaScript and good SEO, and then fast client-side routing if JavaScript is available.

The Netlify tab here shows it building 246 HTML pages.

hudochenkov · 2021-06-01T20:42:47Z

It's an SSG with client-side routing kicking in once the requested page has downloaded. Best of both worlds, e.g. works without JavaScript and good SEO, and then fast client-side routing if JavaScript is available.

I had line wrapping disabled in View Source, and didn't notice full HTML, that I was expecting 🤦

m-allanson

Nice stuff 🎉

jeddy3 · 2021-06-01T21:08:06Z

@m-allanson Thanks for doing the bulk of the migration in the previous pull request!

@ybiquitous & @hudochenkov thanks for the contributions and reviews.

The site is now live.

(The Algolia search will reindex within 24 hours, which will fix the 404 when searching for rules. You have to refresh the page after a search to see them at the moment.)

slorber · 2021-06-02T09:14:37Z

Great!

Please add your site to our showcase ;)
https://docusaurus.io/showcase

For Algolia Search, I forgot to document this and will add it right now, but you should also ask the DocSearch team to update your config so that it works for Docusaurus v2, and they can trigger a re-index manually if needed. cc @shortcuts

This config may work but is not ideal for Docusaurus v2:
https://github.com/algolia/docsearch-configs/blob/master/configs/stylelint.json

shortcuts · 2021-06-02T11:18:40Z

Thanks for the heads up @slorber

I've made the update and the new results are now live!

slorber · 2021-06-02T16:32:41Z

Thanks 🥇

Update to docusaurus 2

359ceae

jeddy3 force-pushed the doc-2 branch from 4700398 to 359ceae Compare May 30, 2021 10:20

ybiquitous reviewed May 31, 2021

View reviewed changes

scripts/generate-docs.mjs Show resolved Hide resolved

ybiquitous reviewed May 31, 2021

View reviewed changes

patches/stylelint+13.13.1.patch Outdated Show resolved Hide resolved

package.json Show resolved Hide resolved

netlify.toml Show resolved Hide resolved

Readd prepare script

c2f507f

This was referenced May 31, 2021

Prepare README for Docusaurus 2 stylelint/stylelint#5332

Merged

Add CHANGELOG to files stylelint/stylelint#5333

Merged

Use master

4744739

ybiquitous reviewed May 31, 2021

View reviewed changes

package.json Outdated Show resolved Hide resolved

ybiquitous reviewed May 31, 2021

View reviewed changes

src/pages/demo.js Outdated Show resolved Hide resolved

ybiquitous reviewed Jun 1, 2021

View reviewed changes

package.json Outdated Show resolved Hide resolved

jeddy3 added 3 commits June 1, 2021 12:01

Add validity patterns

daf1407

Remove clsx

0e8a3ab

Use ESM ESLint branch

6f3ea6f

ybiquitous approved these changes Jun 1, 2021

View reviewed changes

hudochenkov approved these changes Jun 1, 2021

View reviewed changes

jeddy3 mentioned this pull request Jun 1, 2021

Bump prettier from 2.2.1 to 2.3.0 #198

Closed

jeddy3 merged commit f8d3ff1 into master Jun 1, 2021

jeddy3 deleted the doc-2 branch June 1, 2021 20:51

mattxwang mentioned this pull request Jun 1, 2021

Bump jest from 26.6.3 to 27.0.3 #197

Closed

m-allanson reviewed Jun 1, 2021

View reviewed changes

shortcuts mentioned this pull request Jun 2, 2021

fix(stylelint): update config to Docusaurus 2 algolia/docsearch-configs#4149

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update to docusaurus 2 #193

Update to docusaurus 2 #193

jeddy3 commented May 30, 2021 •

edited

jeddy3 commented May 30, 2021 •

edited

ybiquitous commented May 31, 2021

jeddy3 commented May 31, 2021 •

edited

ybiquitous commented May 31, 2021

jeddy3 commented May 31, 2021

ybiquitous commented May 31, 2021

jeddy3 commented Jun 1, 2021 •

edited

jeddy3 commented Jun 1, 2021

ybiquitous left a comment

hudochenkov commented Jun 1, 2021 •

edited

jeddy3 commented Jun 1, 2021 •

edited

hudochenkov commented Jun 1, 2021

m-allanson left a comment

jeddy3 commented Jun 1, 2021

slorber commented Jun 2, 2021

shortcuts commented Jun 2, 2021

slorber commented Jun 2, 2021

Update to docusaurus 2 #193

Update to docusaurus 2 #193

Conversation

jeddy3 commented May 30, 2021 • edited

jeddy3 commented May 30, 2021 • edited

ybiquitous commented May 31, 2021

jeddy3 commented May 31, 2021 • edited

ybiquitous commented May 31, 2021

jeddy3 commented May 31, 2021

ybiquitous commented May 31, 2021

jeddy3 commented Jun 1, 2021 • edited

jeddy3 commented Jun 1, 2021

ybiquitous left a comment

Choose a reason for hiding this comment

hudochenkov commented Jun 1, 2021 • edited

jeddy3 commented Jun 1, 2021 • edited

hudochenkov commented Jun 1, 2021

m-allanson left a comment

Choose a reason for hiding this comment

jeddy3 commented Jun 1, 2021

slorber commented Jun 2, 2021

shortcuts commented Jun 2, 2021

slorber commented Jun 2, 2021

jeddy3 commented May 30, 2021 •

edited

jeddy3 commented May 30, 2021 •

edited

jeddy3 commented May 31, 2021 •

edited

jeddy3 commented Jun 1, 2021 •

edited

hudochenkov commented Jun 1, 2021 •

edited

jeddy3 commented Jun 1, 2021 •

edited