The document site need upgrade

[dtvn]

I think the document need to be re-organized. The current document is lack or organizing. I think we should consider chunk it into many sections. Also, a searchbox would be welcome for a document. We can use google cse, duckduckgo or yandex.

Btw, I would like to suggest the writing style for document. Using this one: https://css-tricks.com/words-avoid-educational-writing

[iChenLei]

Thanks for your advices. Yes, we need upgrade, current documentation is bad fo user.

[groenroos]

Re-organisation of the content may be needed, but what I found myself needing the most is a second-level navigation on some of the more beastly pages like BIFs - finding even the relevant section on that page is difficult - a second-level nav acting as a "table of contents" of sorts would make this way easier.

I guess the current design of the page would make it difficult to implement though.

[iChenLei]

@groenroos Hi. Are you interested in stylus doc website rebuild plan? I am not mean replace current jeklly website immediately. We can create a experimental new doc site (via modern doc-gen framework and free hositing services). Maybe it's stylus.js.org, and then collect stylus user's feedback, and deciding whether to migrate to new doc website finally(redirect stylus-lang.com to new doc website). What's your opioion ?

I maintain zh.mobx.js.org and ko.mobx.js.org actually, and I have a vercel oss free plan account.
alogia-like search services is very good for enhance developer experience, and it's free for open source project

[groenroos]

@iChenLei I'm definitely interested!

For the site generation system, seems like both Docusaurus and VuePress seem to bundle React and Vue respectively, and produce a single-page application as the documentation - which I feel could be overkill for a simple docs website? Do you have in mind any specific features or enhancements either of these libraries bring or make possible, compared to more traditional / less opinionated static site generators like Jekyll or Eleventy?

Should we open a modern branch in this project to begin working out a new frontend? Seems like the frontend/design problems are more clearly defined at the moment (#5, #14, #16, #23), so probably easier to start there. It should be possible to slot in the specific site generation technology later once we find the right solution.

I have far fewer deeply-held opinions about specific CI/deploy technologies!

And yeah, once ready, running the experimental new site in parallel would be a good idea - though do you think we can do something like new.stylus-lang.com so Stylus' online presence doesn't fragment too much?