Add Docusaurus #67

ybiquitous · 2019-07-07T02:53:00Z

Demo: https://stylelint-docusaurus.netlify.com/
(this demo site is updated automatically when commits are pushed)

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

Closes #58

Is there anything in the PR that needs further explanation?

This PR aims to add Docusaurus v1 as a new doc generator engine.

If you want to try the new website on your computer, please run the following commands (Node 8 required):

Commands

git clone https://github.com/stylelint/stylelint.io.git

cd stylelint.io

git fetch origin pull/67/head:docusaurus

git checkout docusaurus

npm install

npm run gendoc

cd website

npm install

npm start

Finally, we should remove the current engine Phenomic. But I don't want to do so in this PR, because removing it will make it hard for us to review this PR due to too many diffs.
After the migration from Phenomic to Docusaurus in the PR will work, I think it good to remove the old engine (further, update Nodejs and dependencies).

I hope any feedback! 😄

About the changes

Add a new script to generate .md files for the website from node_modules/stylelint directory: scripts/generate-stylelint-docs.js
- Run npm run gendoc command if you want to run the script.
- The command outputs the doc/ directory which Docusaurus recognizes.
- The script does the followings:
  - Restructure files and directories. E.g., lib/rules/{rule-name}/README.md -> user-guide/rules/{rule-name}.md
  - Rewrite internal links.
  - Insert frontmatter metadata for Docusaurus.
  - Via remark.
Add a new website directory which Docusaurus requires. The directory is a core of the website.
Don't add Docker-related files and yarn.lock generated by the npx docusaurus-init command. Because I think such files may cause new confusions. Let's add them when we will need.

Close stylelint#58

hudochenkov · 2019-07-07T12:41:13Z

It looks awesome! Keep going, @ybiquitous!

ybiquitous · 2019-07-07T15:01:05Z

Thanks @hudochenkov I'm ready to receive reviews! Welcome feedback!

hudochenkov

Wow! It's super nice! Awesome work, @ybiquitous!

Finally, we should remove the current engine Phenomic. But I don't want to do so in this PR, because removing it will make it hard for us to review this PR due to too many diffs.
After the migration from Phenomic to Docusaurus in the PR will work, I think it good to remove the old engine (further, update Nodejs and dependencies).

Good plan!

Few things I would like to see fixed if possible:

Add html { overflow-y: auto; } to always have scrollbar visible and avoid header jump, when page is loading.
Remove “Preprocessors” from the header. We want to deprecate them, so it's good to not emphasize them in the main navigation.
Make “Demo” in the header looks like other links.
There is no hover state for header links.
On Demo page header is much narrow and links are different (they have hover).
Is it possible to improve changelog sidebar. Currently all links looks like “[10.1.0][]”.
<meta name="description"> and <meta property="og:description"> has weird content. On current website they are also incorrect.
Is it possible to make different title for a home page? <title> and <meta property="og:title"> is “stylelint · stylelint”. Can we do only one ”stylelint” instead? Or like Prettier does: “stylelint · A mighty, modern style linter”?
Neatpick: Is it possible to configure Autoprefixer (if there any)? I see very old flexbox prefixes in CSS. It would be nice to remove them, if Docusaurus allows it.
Make footer shorter. It take too much space on Demo page.

scripts/generate-stylelint-docs.js

website/sidebars.json

ybiquitous · 2019-07-08T02:49:24Z

Make “Demo” in the header looks like other links.

There is no hover state for header links.

I agree to fix the strange style. But this is due to the siteNavGroupActive class name by Docusaurus internal logic, it doesn't seem that we can disable this class name… 😕

See core/nav/HeaderNav.js in Docusaurus code:

ybiquitous · 2019-07-09T01:42:12Z

Current progress report:

Add html { overflow-y: auto; } to always have scrollbar visible and avoid header jump, when page is loading.

Done ✅

Remove “Preprocessors” from the header. We want to deprecate them, so it's good to not emphasize them in the main navigation.

Done ✅

5. On Demo page header is much narrow and links are different (they have hover).

Done ✅

website/static/css/custom.css

hudochenkov · 2019-07-09T08:15:35Z

I think we need to revert this change 6261253. It's very hacky. Let's find solution for header for Demo (both width and links styles) in separate PR, when this one is merged.

Co-Authored-By: Aleks Hudochenkov <aleks@hudochenkov.com>

This reverts commit 6261253.

ybiquitous · 2019-07-09T15:18:35Z

Yes I agree, it's hacky. 😅 Reverted.

- Narrow scope of variables. - Inline variables which are used only once.

ybiquitous · 2019-07-09T16:03:42Z

6. Is it possible to improve changelog sidebar. Currently all links looks like “[10.1.0][]”.

Yes, it's strange. When I research it, I find that the behavior is due to the internal code of docusaurus and markdown-toc. See below:

Currently, I can't find a solution yet. 😖

ybiquitous · 2019-07-09T16:20:55Z

7. <meta name="description"> and <meta property="og:description"> has weird content. On current website they are also incorrect.

It seems to be a Docusaurus's bug. A description of doc pages is generated from the first line of the markdown content. See below:

website/siteConfig.js

This reverts commit 0c9226a.

ybiquitous · 2019-07-09T17:10:36Z

10. Make footer shorter. It take too much space on Demo page.

Done ✅

hudochenkov · 2019-07-09T19:19:34Z

I think the following would be good enough for browserslist. Our audience is developers, and developers always have latest versions of browsers :)

> 0.5%, last 1 major versions, Firefox ESR, not dead

https://browserl.ist/?q=%3E+0.5%25%2C+last+1+major+versions%2C+Firefox+ESR%2C+not+dead

hudochenkov · 2019-07-09T19:37:30Z

I've created issues for unsolved problems, which we could tackle after this PR is merged.

@stylelint/contributors what do you think about new website?

alexander-akait · 2019-07-09T19:42:15Z

👍

ybiquitous · 2019-07-10T00:40:53Z

Neatpick: Is it possible to configure Autoprefixer (if there any)? I see very old flexbox prefixes in CSS. It would be nice to remove them, if Docusaurus allows it.

Done ✅

See #67 (comment)

ybiquitous · 2019-07-10T00:59:18Z

NOTE: I left some notices below.

Netlify, which is used for this PR demo site, supports auto-redirect. But the current hosting GitHub Pages does NOT support. For example:
- 🆗 https://stylelint-docusaurus.netlify.com/CHANGELOG -> https://stylelint-docusaurus.netlify.com/changelog
- 🆖 https://stylelint.io/CHANGELOG -> https://stylelint.io/changelog
- So I think good if the stylelint new website would be deployed on Netlify. For about this, a discussion seems to be needed.
I predict the unsolved problems (which have been reported as issues by @hudochenkov, thanks) will NOT be resolved on Docusaurus v1. Because the Docusaurus team is working for v2 release now:
- The alpha version has been released, current: v2.0.0-alpha.19
- Related issue: Docusaurus 2 facebook/docusaurus#789
- The new website has been published: https://v2.docusaurus.io/
In Docusaurus v2 has some breaking changes, for example, a new config file docusaurus.config.js. So I think we will have to rewrite some parts of the PR changes.
- Sorry, I can't check all breaking changes of Docusaurus v2. 💦

hudochenkov · 2019-07-10T10:21:02Z

Is it possible for Docusaurus to keep file name case? I would like to move to Netlify as well, but migrating engine, hosting, and DNS at the same time is a little bit risky.

ybiquitous · 2019-07-10T10:34:16Z

Sure, Docusaurus outputs CHANGELOG.html. When this file is deployed to GitHub Pages, the /CHANGELOG access returns 200 status instead of 400, doesn't it?

$ cd website

$ npm run build

$ ls build/stylelint/*.html
build/stylelint/CHANGELOG.html       build/stylelint/VISION.html          build/stylelint/developer-guide.html build/stylelint/user-guide.html
build/stylelint/CONTRIBUTING.html    build/stylelint/demo.html            build/stylelint/index.html

hudochenkov · 2019-07-10T10:39:51Z

I think I see the problem. Docusaurus generates CHANGELOG.html, while Phenomic CHANGELOG/index.html so for Github Pages all three links are working:

/CHANGELOG
/CHANGELOG/

But non of this will be working with Github Pages and Docusaurus :(

What we can do is migrate to Netlify with current setup and use https://github.com/stylelint/stylelint.github.io as source for deployment. Then migrate this to Docusaurus completely (with removing Phenomic) and then change Netlify to run on this repository.

ybiquitous · 2019-07-10T10:55:13Z

It looks a good idea to me! 👍

ntwb · 2019-07-11T02:01:45Z

Awesome progress here, thanks a whole bunch @ybiquitous and @hudochenkov for jumping in

hudochenkov

Great work, @ybiquitous! Now let's remove Phenomic :)

ybiquitous · 2019-07-11T23:49:47Z

Thank you for the review!

ntwb · 2019-07-12T03:06:19Z

The migration to Docusaurus has worked (see stylelint#67), so this deletes Phenomic code as the old engine. - Delete unused directories and files. - Update dependencies. - Use Node 12 (latest) in Travis CI.

* Delete Phenomic and update dependencies The migration to Docusaurus has worked (see #67), so this deletes Phenomic code as the old engine. - Delete unused directories and files. - Update dependencies. - Use Node 12 (latest) in Travis CI. * Set Node version via `.nvmrc` Travis CI and Netlify recognize a `.nvmrc` file to detect needed Node version. * Update README for new npm-run scripts * Use Node v10 LTS instead of v12 * Arrange npm scripts * Fix warning of `eslint-plugin-react` > Warning: React version not specified in eslint-plugin-react settings. See https://github.com/yannickcr/eslint-plugin-react#configuration . * Set `NODE_ENV=production` to prevent PostCSS warning > Without `from` option PostCSS could generate wrong source map and will not find Browserslist config. Set it to CSS file path or to `undefined` to prevent this warning.

jeddy3 · 2019-07-24T06:37:53Z

Fantastic work!

hudochenkov · 2019-07-24T06:42:43Z

@jeddy3 you're back! Happy to see you :) Even if we don't see each other actually :)

jeddy3 · 2019-07-24T06:50:00Z

Thanks! It's nice to be back. It's brilliant to see all this good work on the stylelint website. It's looking great!

ybiquitous added 4 commits July 7, 2019 11:50

Add Docusaurus

68634f3

Close stylelint#58

Update Docusaurus ignore files and delete website/i18n

3e4b4a8

Ignore ESLint issues via comments

070a598

Avoid CI failures by disabling tests

05602ff

ybiquitous added 2 commits July 7, 2019 22:47

Add demo page

7b39d63

Add search bar

dc9d06d

ybiquitous marked this pull request as ready for review July 7, 2019 14:59

hudochenkov reviewed Jul 7, 2019

View reviewed changes

scripts/generate-stylelint-docs.js Outdated Show resolved Hide resolved

website/sidebars.json Outdated Show resolved Hide resolved

ybiquitous added 3 commits July 8, 2019 11:40

Remove "Processors" (deprecated) from the header

c2ac509

Add comments to custom CSS

7c82ef5

Add custom CSS html {overflow-y: auto;}

fe6205c

Remove useless .replace() call from the generator script

259b630

ybiquitous added the status: wip is being worked on by someone label Jul 8, 2019

ybiquitous added 2 commits July 9, 2019 10:16

Auto-generate sidebars.json (especially, for rules list)

7cf1e1c

Customize default CSS in demo page via JS

6261253

hudochenkov reviewed Jul 9, 2019

View reviewed changes

website/static/css/custom.css Outdated Show resolved Hide resolved

ybiquitous and others added 2 commits July 10, 2019 00:14

Fix overflow-y: auto -> scroll

06b5808

Co-Authored-By: Aleks Hudochenkov <aleks@hudochenkov.com>

Revert "Customize default CSS in demo page via JS"

57c5320

This reverts commit 6261253.

ybiquitous added 2 commits July 10, 2019 00:40

Refactor generate-stylelint-docs.js

35a3fd4

- Narrow scope of variables. - Inline variables which are used only once.

Add gaTrackingId to siteConfig.js

0c9226a

hudochenkov reviewed Jul 9, 2019

View reviewed changes

website/siteConfig.js Outdated Show resolved Hide resolved

Revert "Add gaTrackingId to siteConfig.js"

f233a76

This reverts commit 0c9226a.

Make footer shorter

a4d880e

This was referenced Jul 9, 2019

Header improvements #68

Closed

Improve changelog Table of Content #69

Closed

Improve meta description #70

Closed

Improve title for a home page #71

Closed

Configure browserslist in package.json

a19b22f

hudochenkov mentioned this pull request Jul 10, 2019

Migrate to Netlify #72

Closed

hudochenkov approved these changes Jul 11, 2019

View reviewed changes

hudochenkov merged commit b05a27c into stylelint:master Jul 11, 2019

ybiquitous removed the status: wip is being worked on by someone label Jul 11, 2019

ybiquitous deleted the docusaurus branch July 11, 2019 23:49

ybiquitous mentioned this pull request Jul 13, 2019

Delete Phenomic and update dependencies #74

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Docusaurus #67

Add Docusaurus #67

ybiquitous commented Jul 7, 2019 •

edited

hudochenkov commented Jul 7, 2019

ybiquitous commented Jul 7, 2019

hudochenkov left a comment

ybiquitous commented Jul 8, 2019

ybiquitous commented Jul 9, 2019

hudochenkov commented Jul 9, 2019

ybiquitous commented Jul 9, 2019

ybiquitous commented Jul 9, 2019

ybiquitous commented Jul 9, 2019

ybiquitous commented Jul 9, 2019

hudochenkov commented Jul 9, 2019

hudochenkov commented Jul 9, 2019

alexander-akait commented Jul 9, 2019

ybiquitous commented Jul 10, 2019

ybiquitous commented Jul 10, 2019

hudochenkov commented Jul 10, 2019

ybiquitous commented Jul 10, 2019

hudochenkov commented Jul 10, 2019

ybiquitous commented Jul 10, 2019

ntwb commented Jul 11, 2019

hudochenkov left a comment

ybiquitous commented Jul 11, 2019

ntwb commented Jul 12, 2019

jeddy3 commented Jul 24, 2019

hudochenkov commented Jul 24, 2019

jeddy3 commented Jul 24, 2019

Add Docusaurus #67

Add Docusaurus #67

Conversation

ybiquitous commented Jul 7, 2019 • edited

About the changes

hudochenkov commented Jul 7, 2019

ybiquitous commented Jul 7, 2019

hudochenkov left a comment

Choose a reason for hiding this comment

ybiquitous commented Jul 8, 2019

ybiquitous commented Jul 9, 2019

hudochenkov commented Jul 9, 2019

ybiquitous commented Jul 9, 2019

ybiquitous commented Jul 9, 2019

ybiquitous commented Jul 9, 2019

ybiquitous commented Jul 9, 2019

hudochenkov commented Jul 9, 2019

hudochenkov commented Jul 9, 2019

alexander-akait commented Jul 9, 2019

ybiquitous commented Jul 10, 2019

ybiquitous commented Jul 10, 2019

hudochenkov commented Jul 10, 2019

ybiquitous commented Jul 10, 2019

hudochenkov commented Jul 10, 2019

ybiquitous commented Jul 10, 2019

ntwb commented Jul 11, 2019

hudochenkov left a comment

Choose a reason for hiding this comment

ybiquitous commented Jul 11, 2019

ntwb commented Jul 12, 2019

jeddy3 commented Jul 24, 2019

hudochenkov commented Jul 24, 2019

jeddy3 commented Jul 24, 2019

ybiquitous commented Jul 7, 2019 •

edited