Design/engine #58

hudochenkov · 2018-07-22T10:02:09Z

There are a few issues with our website that I would like to address.

Anchor links don't work if you just go by URL, and not clicking on the page. I. e. https://stylelint.io/user-guide/configuration/#extends doesn't scroll to extends in Chrome and Safari, but scroll in Firefox. And this problem exists for a very long time. This is some kind of a bug with Phenomic and its dependency react-router-scroll.
The design doesn't look good in line with websites of other modern tools.

I'm not sure how to solve the first problem, and it's the most critical, IMHO. I'm afraid it couldn't be solved without a new version of Phenomic. The problem is we use a year old version, and the latest version is in beta for a year. It's almost ready to be stable, though. On the other hand, it's a one-person project, and the author could be limited in time to work on it.

So maybe it worth to migrate to another engine, which more people develop.

Docusaurus is quite popular in open source recently. Babel, Prettier, Jest all use it. One “problem”, that all these websites look similar. But still look good.

Gatsby is also popular. It's used for React website. Problem with this one, that it has v2 in beta, which doesn't have many docs. So it's not clear is it worth to invest time in v1, when v2 on the horizon. While use v2 without docs will be problematic.

The new engine could help us solve design problems as well. But we could update the design and with old engine as well.

What are your thoughts, @stylelint/contributors? How can we solve scrolling and design problems?

The text was updated successfully, but these errors were encountered:

filipekiss · 2018-07-23T11:51:57Z

I've worked with Docusaurus and also VuePress. They're quite similar, except Docusaurus seems to be more featured as it is easier to add related pages instead of only documentation.

Migrating vs. waiting on a proper release of Phenomic both have their problems and advantages.

I would consider migrating if the effort is really low in terms of reformatting files and moving content around. And other thing we need to consider: will upgrading Phenomic solve the problem by itself or it will just be safer for us to try to locate and solve the problem?

If the situation is more like the latter, I'd invest in the migration since work will need to be done anyway and using a tool that's constantly updated is a nice bonus and problems like this tend to live shorter.

jeddy3 · 2018-07-23T14:00:35Z

It'd be great to fix the anchor links.

I suggest we go with whichever approach is the least effort overall, balancing the migration with long-term maintenance.

I think we should try to keep the nice separataion we have between the docs and the website, though. It means contributors to stylelint needn't have to understand how the website works to contribute new features and/or update the documentation. In the main repo:

the markdown files are clean and free of front-matter
rule READMEs live in the relevant rule's folder
links between markdown files work, including between rules
the main README lives in the root

This makes the repo feel complete and whole.

We do some rough and ready stuff behind the scenes to prepare these files for the website, including:

Hopefully such an approach is still viable with Docusaurus, React or the latest version of Phenomic.

Additionally, we add three features to the website:

As long as we can replicate these, then I see no harm migrating to another tool.

Docusaurus might meet our needs best as it's specifically built for documenting open source projects. It:

will free us from having to think about design
works well across different viewport sizes
has ToC side bars which I think will lend themselves well to how we've already written the docs
has integrated docsearch
has previous and next links

We'll need to check if:

those ToC are automatically generated, rather manually maintained
we can add red or green background color to code examples

A proof of concept of that last one feels like a good next step.

hudochenkov · 2018-07-25T07:41:42Z

I tried Docusarus, and then realized, that it produces links like: https://stylelint.io/docs/user-guide. And docs part is always there.

I'll try to make our fork of Phenomic to fix anchor link bug.

jeddy3 · 2018-07-25T07:57:17Z

And docs part is always there.

That's unfortunate, but I don't think it's a deal breaker. It looks like netlify can redirect the current URLs, so we can move to /docs/ without breaking the links in other websites.

It will also parallel the /doc/ structure we use in the repo itself, which I guess we could consider a plus.

I'll try to make our fork of Phenomic to fix anchor link bug.

If it doesn't take too much time, then this will get us to a better place.

hudochenkov · 2018-07-25T18:51:04Z

That's unfortunate, but I don't think it's a deal breaker. It looks like netlify can redirect the current URLs, so we can move to /docs/ without breaking the links in other websites.

It looks weird to me when docs website should have docs in the URLs.

hudochenkov · 2018-07-25T21:10:16Z

No luck with fixing Phenomic. Actually, I did fix it by applying fix inside node_modules. But I couldn't apply the fix to Phenomic source code, because its npm install fails with a weird problem. I give up on Phenomic. Going to look better engine for this website, and do proof of concept.

ntwb · 2018-07-26T06:15:39Z

Thanks @hudochenkov, if the stylelint/phenomic fork is no longer required could you remove it please :)

filipekiss · 2018-07-26T14:40:03Z

It looks weird to me when docs website should have docs in the URLs.

I see the front-page as an introduction to the project and then the documentation under the docs tree. I don't see that as a problematic issue, except for the redirect we'd need to make to ensure current links keep working. Unless we're not aiming for a proper project website and just a "nicer way to read the docs"

hudochenkov · 2018-10-06T21:08:41Z

Anchor links bug was fixed by @Bilie.

The design/engine issue remains open. I might have time to look at it in the second half of October.

ybiquitous · 2018-10-31T13:00:54Z

I agree with moving the current engine. 👍

Docusaurus is very popular, so it looks good to me. 😃

jeddy3 · 2018-10-31T13:09:17Z

Docusaurus is very popular, so it looks good to me. 😃

It could be a fun side-project.

I say we go for Docusaurus as long as we replicate the requirements from #58 (comment):

a ToC on some pages
red or green background color to code examples
next and previous links between rules

And:

keep the nice separation we have between the docs and the website

Which means:

the markdown files are clean and free of front-matter
rule READMEs live in the relevant rule's folder
links between markdown files work, including between rules
the main README lives in the root

ybiquitous · 2018-10-31T13:20:08Z

Gatsby has many features: https://www.gatsbyjs.org/features/

Popularity comparison on GitHub Stars (Oct 31, 2018):

Gatsby: 27.3K https://github.com/gatsbyjs/gatsby
Docusaurus: 9.3K https://github.com/facebook/Docusaurus

jeddy3 · 2018-10-31T13:33:36Z

Gatsby has many features: https://www.gatsbyjs.org/features/

Yep, Gatsby is great. I've been using it in my day job for nearly a year now. Version 2 has been out for a while too.

I wonder if we'll get more out-of-the-box with Docusaurus for our particular use-case, though. For example, we won't need to worry about designs as we can use Docusaurus' default (documentation-friendly) one. However, Gatsby might make it easier to keep the nice separation we have between the docs and the website (by using their sources approach).

I suggest just picking the one you'd like to try and seeing how a PoC goes :)

ybiquitous · 2018-10-31T13:39:47Z

Thanks! I will try Gatsby.

ybiquitous · 2019-02-17T04:23:51Z

Sorry for too late response. I gave up Gatsby, because GraphQL system is too hard to understand to me and too complicated to the stylelint documentation site. 😓

So, I'm trying Docusaurus on my fork repository as PoC and publish to Netlify:

There are some problems yet, but it works at minimum anyway. 😃

hudochenkov · 2019-02-17T09:39:35Z

@ybiquitous amazing! Keep going! :)

hudochenkov · 2019-06-07T21:34:31Z

@ybiquitous do you have any progress? Do you need help?

ybiquitous · 2019-06-08T09:04:35Z

Hi, I apologize for my laziness. Now Docusaurus is in progress toward version 2, so I think better that we wait for rewriting the code base until Docusaurus v2 will be released. Because Docusaurus v2 will have many breaking changes:

ybiquitous · 2019-06-08T09:13:23Z

Do we have a plan to migrate from GitHub Pages to Netlify? I like the Netlify's Deploy Preview so much, so I would be very happy if it would be realized!

hudochenkov · 2019-06-08T09:22:41Z

I apologize for my laziness

Don't apologize, you don't owe anything to anyone :)

Now Docusaurus is in progress toward version 2, so I think better that we wait for rewriting the code base until Docusaurus v2 will be released. Because Docusaurus v2 will have many breaking changes

Yeah, make sense.

Do we have a plan to migrate from GitHub Pages to Netlify?

I would love to. But we probably should wait for the new engine, because current one works only in Node.js 8.

ybiquitous · 2019-06-08T09:33:01Z

Thank you. I will progress the renewal of the engine via Docusaurus v2 alpha version when I have time as much as possible. 💪

Close stylelint#58

* Add Docusaurus Close #58 * Update Docusaurus ignore files and delete `website/i18n` * Ignore ESLint issues via comments * Avoid CI failures by disabling tests * Add demo page * Add search bar * Remove "Processors" (deprecated) from the header * Add comments to custom CSS * Add custom CSS `html {overflow-y: auto;}` * Remove useless `.replace()` call from the generator script * Auto-generate sidebars.json (especially, for rules list) * Customize default CSS in demo page via JS * Fix overflow-y: auto -> scroll Co-Authored-By: Aleks Hudochenkov <aleks@hudochenkov.com> * Revert "Customize default CSS in demo page via JS" This reverts commit 6261253. * Refactor `generate-stylelint-docs.js` - Narrow scope of variables. - Inline variables which are used only once. * Add `gaTrackingId` to `siteConfig.js` * Revert "Add `gaTrackingId` to `siteConfig.js`" This reverts commit 0c9226a. * Make footer shorter * Configure `browserslist` in `package.json`

jeddy3 mentioned this issue Sep 13, 2018

"npm install" fails on Node v10 #59

Closed

Bilie mentioned this issue Sep 29, 2018

Fix scroll to url fragment on initial load in Chrome #61

Merged

hudochenkov changed the title ~~Anchor links and design~~ Design/engine Oct 6, 2018

jeddy3 mentioned this issue Oct 31, 2018

Empty <title> tag on production stylelint/stylelint-demo#129

Closed

ybiquitous added a commit to ybiquitous/stylelint.io that referenced this issue Jul 7, 2019

Add Docusaurus

68634f3

Close stylelint#58

ybiquitous mentioned this issue Jul 7, 2019

Add Docusaurus #67

Merged

hudochenkov closed this as completed in #67 Jul 11, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Design/engine #58

Design/engine #58

hudochenkov commented Jul 22, 2018

filipekiss commented Jul 23, 2018

jeddy3 commented Jul 23, 2018

hudochenkov commented Jul 25, 2018

jeddy3 commented Jul 25, 2018

hudochenkov commented Jul 25, 2018

hudochenkov commented Jul 25, 2018

ntwb commented Jul 26, 2018

filipekiss commented Jul 26, 2018

hudochenkov commented Oct 6, 2018

ybiquitous commented Oct 31, 2018

jeddy3 commented Oct 31, 2018

ybiquitous commented Oct 31, 2018 •

edited

Loading

jeddy3 commented Oct 31, 2018

ybiquitous commented Oct 31, 2018

ybiquitous commented Feb 17, 2019

hudochenkov commented Feb 17, 2019

hudochenkov commented Jun 7, 2019

ybiquitous commented Jun 8, 2019

ybiquitous commented Jun 8, 2019

hudochenkov commented Jun 8, 2019 •

edited by ntwb

Loading

ybiquitous commented Jun 8, 2019

Design/engine #58

Design/engine #58

Comments

hudochenkov commented Jul 22, 2018

filipekiss commented Jul 23, 2018

jeddy3 commented Jul 23, 2018

hudochenkov commented Jul 25, 2018

jeddy3 commented Jul 25, 2018

hudochenkov commented Jul 25, 2018

hudochenkov commented Jul 25, 2018

ntwb commented Jul 26, 2018

filipekiss commented Jul 26, 2018

hudochenkov commented Oct 6, 2018

ybiquitous commented Oct 31, 2018

jeddy3 commented Oct 31, 2018

ybiquitous commented Oct 31, 2018 • edited Loading

jeddy3 commented Oct 31, 2018

ybiquitous commented Oct 31, 2018

ybiquitous commented Feb 17, 2019

hudochenkov commented Feb 17, 2019

hudochenkov commented Jun 7, 2019

ybiquitous commented Jun 8, 2019

ybiquitous commented Jun 8, 2019

hudochenkov commented Jun 8, 2019 • edited by ntwb Loading

ybiquitous commented Jun 8, 2019

ybiquitous commented Oct 31, 2018 •

edited

Loading

hudochenkov commented Jun 8, 2019 •

edited by ntwb

Loading