Open to website redesign?

[jcbhmr]

The current webite...

...decouples the documentation about https://github.com/fontist/fontist and puts it in a completely different repository (this fontist.github.io repo). this means that prs that modify or add behaviour to fontist cli must open another pr to change the docs. it'd be better to co-locate these together in one place

...puts the navigation on the RIGHT side instead of the traditional LEFT side. remember the F reading pattern! https://uxplanet.org/f-shaped-pattern-for-reading-content-80af79cd3394 left side imo is better for navigation panels.

...separates things into different pages that could be a single page. for example: https://www.fontist.org/docs/usage/proxy/ and https://www.fontist.org/docs/usage/directory/ could be combined. also maybe https://www.fontist.org/docs/usage/ruby/ might be better split into a proper API doc.

...does NOT have syntax highlighting. self explanatory. syntax highlighting is essential for reading code in the modern age. ex: https://www.fontist.org/docs/usage/ruby/

i thought "can i do better?" lol and tried my hand at a redesign.

TL;DR: are you open to a website redesign or upgrade? i notice that there seems to be some kind of riboseopen template that you're using and idk if you're allowed(?) to break out of that cookie-cutter same-y template and form your own "style" for fontist.

🛑 YOU DONT HAVE TO ACCEPT OR MERGE ANY OF THIS; ITS OK THE WAY IT IS. this is just me proposing an idea. if you dont like it it's perfectly OK. ❤️ my feelings wont be hurt if you say no. this was as much for me to see "can i do it" as to improve the site lol

(pretend the cross-site links work lol)
https://jcbhmr.me/fontist.github.io/
https://jcbhmr.me/fontist/

actually this comes in two parts:

1. are you open to a re-working of the base https://fontist.org website to make it more org-focused on @fontist and delegate to https://fontist.org/fontist/ which is hosted by https://github.com/fontist/fontist via github pages
2. and 2: are you open to moving the https://github.com/fontist/fontist -related docs to the https://github.com/fontist/fontist repository?

screenshots:

fontist.org

fontist.org/fontist/ hosted by https://github.com/fontist/fontist

---

more info:

• using vitepress for the pretty docs and homepages https://vitepress.dev/
• using rdoc to generate ruby documentation about the library API https://github.com/ruby/rdoc
• should be simpler (fewer files; more focused on markdown files instead of layouts) than the existing jekyll site
• should work with https://pr.new/ to do in-browser edits
• should keep all old links working from https://fontist.org such as https://fontist.org/docs/ => redirects to [wherever-you-want]

ref fontist/formulas#174

[alexeymorozov]

Thank you @jcbhmr! Took a look, though need more time to fully understand the change.

I see good things like:

1. It looks more pleasant
2. Navigation is more intuitive
3. Readme and website docs are in one place now
4. Syntax highlighting is a good idea

Some concerns:

1. AsciiDoc is an organizational choice as far as I understood (Markdown is used here afaik)
2. The initial website was designed for humans, but this separation has more of a technical intention. For example, for me it's unusual not to have a link to formulas search when reading how to use fontist
3. Different pages are intentionally made separate to address questions users may have, like "how to use different fonts install path" or "use proxy"

Seems okay:

1. It's a switch from Ruby to Javascript, but code looks readable, it's fine with me

👍

[jcbhmr]

Tangent: here's someone's guide to writing good docs: https://diataxis.fr/

To address some of the concerns 😉

AsciiDoc is an organizational choice as far as I understood (Markdown is used here afaik)

Yep! VitePress (my go-to zero-config docs recommendation) uses Markdown, Vite, and Vue. Most users never need to touch anything beyond Markdown and some JS JSON-like config objects; that's why it's so great imo!

Here's some AsciiDoc-supporting static site generators: https://writetheasciidocs.netlify.app/asciidoc-static-site-generators
Highlights:

• https://gohugo.io/ -- Popular. Supply your own theme.
• https://jekyllrb.com/ -- What's being used. Default GitHub docs preprocessor. Supply your own layouts.
• https://antora.org/ -- Almost "official" AsciiDoc SSG. Uses custom routing scheme (not simple file-based).

I'm sure that any of these other AsciiDoc-based would work great! I have no experience with any of these other AsciiDoc options (all the projects I contribute to use Markdown). I don't know how comparable they are to the built-in zero-config batteries-included approach that VitePress has.

The initial website was designed for humans, but this separation has more of a technical intention.

If you're referring to how I'm proposing to move the main https://github.com/fontist/fontist docs from https://fontist.org/ to https://fontist.org/fontist/ and how that's odd, you're kinda right. Consider though that the @fontist "brand" or "name" or "project" is both a comprehensive project as well as a specific CLI app. Similar to Google (the company) and Google (the search). Or Firefox (the collection) and Firefox (the browser only). I think that this separation between "the fontist project" and "the fontist cli" is a good one. But yes the primary motivator is technical.

If you reallllly want https://github.com/fontist/fontist to be the site and to not have a super-project index site (no root org-wide site) you can just add a redirect from https://fontist.org/ to https://fontist.org/fontist/ and host the site in https://github.com/fontist/fontist 🤷‍♀️ (then you'd still have https://fontist.org/formulas for https://github.com/fontist/formulas)

For example, for me it's unusual not to have a link to formulas search when reading how to use fontist

Of course you can link to https://fontist.org/formulas/ (currently https://jcbhmr.me/formulas/)! You can put whatever content you want in there! 😊

Different pages are intentionally made separate to address questions users may have, like "how to use different fonts install path" or "use proxy"

Here's an example of what I think a good "How do I $X?" page looks like. https://rollupjs.org/faqs/ Notice how the FAQ page is one page of shorter-ish answers that link to other Reference-style pages. That's kinda what I meant. Don't get rid of "How do I $X?" information, just put it one larger page instead of 5 tiny 1-paragraph pages.