search

stylelint / stylelint.io

The source of the Stylelint website
https://stylelint.io
MIT License
29 stars 16 forks source link

Design/engine #58

Closed hudochenkov closed 5 years ago

hudochenkov commented 6 years ago

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

  1. 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.

  2. 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?

filipekiss commented 6 years ago

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 commented 6 years ago

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:

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:

We'll need to check if:

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

hudochenkov commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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 commented 6 years ago

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

filipekiss commented 6 years ago

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 commented 6 years ago

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 commented 5 years ago

I agree with moving the current engine. 👍

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

jeddy3 commented 5 years ago

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 https://github.com/stylelint/stylelint.io/issues/58#issuecomment-407067987:

And:

Which means:

ybiquitous commented 5 years ago

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

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

jeddy3 commented 5 years ago

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 commented 5 years ago

Thanks! I will try Gatsby.

ybiquitous commented 5 years ago

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 commented 5 years ago

@ybiquitous amazing! Keep going! :)

hudochenkov commented 5 years ago

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

ybiquitous commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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