search

asdf-vm / asdf

Extendable version manager with support for Ruby, Node.js, Elixir, Erlang & more
https://asdf-vm.com/
MIT License
21.84k stars 775 forks source link

Website Improvements #862

Closed Stratus3D closed 3 years ago

Stratus3D commented 3 years ago

I want to prefix this by saying that having a website for asdf is wonderful and I'm thankful to everyone who has dedicated time to making it what it is today. The website is a great resource and a good place for our asdf documentation to grow and evolve.

Since the website was started I've kept notes on the things I came across that caused by trouble, or that others complained about. Below are the things I believe we should change to make the website more helpful and accessible.

Content Improvements

Template Improvements

Websites I like:

Adding these here so we can have a few concrete examples to compare asdf-vm.com with:

Stratus3D commented 3 years ago

https://news.ycombinator.com/item?id=26019010

jthegedus commented 3 years ago

I have been thinking on this topic for quite some time too and agree we should have a completely JS-free static site for the reasons you mention and link, amongst others.

Docsify has served us well to go from nothing to something, but perhaps not something to all-inclusive.

The next question I guess is, are we looking to write our own raw HTML or use a tool? Both could be hard to maintain for differing reasons.

If we're going down the tool route, I would recommend we try https://www.11ty.dev/ (what do others suggest?) https://docusaurus.io/ and the like seem like a bit much.

Features we currently use but would lose without JS:

I think losing the dropdowns is a bit of a bummer as it solves a real content issue. The next best alternative is generating every permutation of the page at build time. we could of course load everything and then if/when JS loads it filters and provides the dropdownds. What are others thoughts on this?

As for default styling which Docsify gives us, I would suggest we use something simple like water.css (single rel stylesheet in head)

As an asider, we can remove the coverpage with Docsify and rejig the place they would land - https://github.com/asdf-vm/asdf/blob/64a1d6ba44c621ef922ab752fc3cf5e6f91cec02/docs/index.html#L33 . I too dislike scrolling being the first action on a site, I had lofty plans of a gifs on the landing page showing asdf usage in various Shells (similar to the nix landing page) but that never eventuated.

I don't want to gatekeep the website, but have been thinking about this a lot and happy to build out a POC of this.

jthegedus commented 3 years ago

We could also leverage a product like https://docs.gitbook.com/integrations/github which usually have free tiers for OSS projects.

Stratus3D commented 3 years ago

The next question I guess is, are we looking to write our own raw HTML or use a tool? Both could be hard to maintain for differing reasons.

I think a tool would be best. https://www.11ty.dev/ seems good. I also think Jekyll might be a good option as well. Jekyll is one of the most widely used static site generators on Github pages, so it integrates well. And it isn't terribly complicated. We have to pair it with a theme like https://jekyllthemes.io/theme/just-the-docs to make it look like a docs site instead of a blog.

I think losing the dropdowns is a bit of a bummer as it solves a real content issue. The next best alternative is generating every permutation of the page at build time. we could of course load everything and then if/when JS loads it filters and provides the dropdownds. What are others thoughts on this?

I agree, the dropdowns are pretty sweet and make things a lot more user friendly. I'm probably not the best person to discuss this with, but I bet it would be possible to port this to other static sites without too much difficulty.

I too dislike scrolling being the first action on a site, I had lofty plans of a gifs on the landing page showing asdf usage in various Shells (similar to the nix landing page) but that never eventuated.

I had forgotten about that. I still like that idea, if you want to write a script (sequence of events) I can try my hand at recording a demo. It would definitely improve the user experience for first time users.

Stratus3D commented 3 years ago

I don't want to gatekeep the website, but have been thinking about this a lot and happy to build out a POC of this.

I haven't been involved at all. So I'll defer to you and the other maintainers.

jthegedus commented 3 years ago

Jekyll is a good suggestion, I always forget it exists coming from the JS and not Ruby world. I will play around with Jekyll and 11ty as I like that each support some version of Liquid tags / Shortcodes which may make rendering of content a bit more portable and easier to handle.

Re the dropdowns, an HTML only replacement could be just a list of expandable blocks

macos & homebrew macos homebrew instructions
macos & git macos git instructions
*nix & git *nix instructions

And then fallback to dropdowns if JS is available. I'll look into this, but I thinkn the expandable sections is a decent html only soln

augustobmoura commented 3 years ago

How about Hugo? I find it easier than Jekyll, and heard it's a lot faster

jthegedus commented 3 years ago

@augustobmoura Since this will be a small number of pages the build tool itself shouldn't matter too much, especially around speed as it will be performed during CI.

Stratus3D commented 3 years ago

Hugo might be fine. I suggested Jekyll because I know it well, and that will make things easier for me. I'll defer to other maintainers on this, I think ease of use for our whole group is more important than feature set or performance.

jthegedus commented 3 years ago

ease of use for our whole group is more important than feature set or performance

I concur. With Jekyll being by far the most used SSG tool for GitHub Pages hosted sites it should improve the volume of contributors to the doc site improvements.

augustobmoura commented 3 years ago

I agree that speed shouldn't drive the decision, I only cited Hugo because is almost 100% compatible with Jekyll but with more features, and actually simpler to setup. It is highly regarded as a sucessor to Jekyll, just looking at the github insights you can see the diferences.

I'm just asking the person who will work on the website to give it a try instead of blindingly choosing a another option.

I concur. With Jekyll being by far the most used SSG tool for GitHub Pages hosted sites it should improve the volume of contributors to the doc site improvements.

I don't think the SSR engine would matter much in writing documentation, in the end the contributors will only need to edit Markdown files anyway. Setting up the development environment will be important though, in that regard I would prefer Hugo or Hexo because I'm not used to a Ruby environment, Hexo being a npm package is the easiest because most of web developers (if not all) should be familiar with it, Hugo is just a single compiled binary.

This are just tips to lookout though, no need to pick one of them (or other options for that matter), there are plenty of SSR in the market to chose from

Stratus3D commented 3 years ago

Another issue pointed out on https://github.com/asdf-vm/asdf/pull/917 is that H6's are way too small to be comfortably read. We should update the CSS so that all headings are at least as big as paragraph text.

jthegedus commented 3 years ago

During the migration our CSS will change completely. Definitely a point to keep track of when we do so.

Lewiscowles1986 commented 3 years ago

Hey @jthegedus thanks for redirecting me to this. So it seems like efforts to improve the website are on the radar.

Do you mind if I attempt to spike something a lot simpler than what you seem to be discussing as an interim?

I sort of already did today. I made a Jekyll version of the site, used the themes and DOM from the rendered Vue component, got darkMode working, removed cover banner scrolling mentioned here, and added some a11y fixes for skip to content and tab navigating the top drop-down menu's. As well as this I had to change some of the markdown to make the blocks of code work with jekyll, and to go with an explicit linking (although I hacked together a way for you to maintain markdown sidebar and top-nav). I also set about having it retaining prismJS as highlighter. The one area I think will have to be manual is the auto-magic downloading of remote files. It has a search which... IDK, it works but is awful... Maybe a jumping in point for someone else as it's presently a single-jekyll template for all search. It's for-sure a rough-cut, there might be regressions I've not noticed.

LMK if you're interested. Link

jthegedus commented 3 years ago

@Lewiscowles1986 I will take a look, thanks. Definitely a good point of exploration.

jthegedus commented 3 years ago

Check #1000 for links to the demo of proposed solutions with explanation for tooling choice.

jthegedus commented 3 years ago

New site is live :smile: