Skip to content

The document site need upgrade #23

Closed
dtvn opened this issue Oct 11, 2019 · 4 comments · Fixed by stylus/stylus#2695
Closed

The document site need upgrade #23

dtvn opened this issue Oct 11, 2019 · 4 comments · Fixed by stylus/stylus#2695

Comments

@dtvn
Copy link

dtvn commented Oct 11, 2019

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
Copy link
Member

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

@groenroos
Copy link
Collaborator

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
Copy link
Member

iChenLei commented Sep 10, 2021

@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
Copy link
Collaborator

@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?

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants