organizes documentation topics, normalizes docs headings

[stockholmux]

Description

This supersedes PR #87

This PR puts documentation in to categories, alters the top nav to make a single documentation drop down, and normalizes the heading in the documentation pages.

Issues Resolved

n/a

Check List

• Commits are signed per the DCO using --signoff

By submitting this pull request, I confirm that my contribution is made under the terms of the BSD-3-Clause License.

[melroy89]

Still you like to see a 'Getting started' on the /docs page personally.

[zuiderkwast]

Very good!

I'm wondering if we need that first page with just the two links "commands" and "topics". It seem like an extra step to click through, but maybe there's a usability aspect to it that I'm missing.

Can we just make topics/ be the start page of the docs? The first link under "Programming with Valkey" is "Full list of commands". We can make it more clear, like put it first under it's own heading or something.

We can also put "getting started" near the top of that page.

I'm totally open to edit the topics/index.md to whatever you want it to include.

[stockholmux]

@zuiderkwast The /docs/ page has two basic reasons to exist:

1. It is pre-existing and it's very possible that external links or bookmarks exist to it.
2. It unifies what people think of 'docs' - today: reference and topics on one, top-level page. If we have future items, we'll need a place to park that as well: imports topics from valkey-doc, adds docs menu, and taxonomy for tech blog #87, for example, had the concept of tutorials (which I still think will be an eventual 3rd pillar of docs eventually).

And FWIW, there is no extra clicking needed - the third picture illustrates that "Documentation" is both clickable and reveals topics and command reference by mousing over.

[zuiderkwast]

Great, I'm convinced. :)

[stockholmux]

@melroy89 Yeah, possible to add this to the page. The closest thing we have today to Gettting Started is Introduction to Valkey.

[zuiderkwast]

Code looks good and I've tested it locally. Works great!

Just a question: Is the alphabetical list of topics is based by on the title or the linkTitle frontmatter value of each page? I see that about half of them start with "Valkey", for example "Valkey Replication", while the other half doesn't. What's the idea here? Should we update linkTitle on each of them so it doesn't start with "Valkey"?

[melroy89]

@melroy89 Yeah, possible to add this to the page. The closest thing we have today to Gettting Started is Introduction to Valkey.

Uhm maybe for another pr. This is not what I meant. I was looking more into getting-started as in how to install Valkey on different systems and platforms. And maybe some basic setup and unit.d or systemd configurations. To well, get people started. 😊

(ow and including docker of course).

All a single page and linked from the docs main page.

[zuiderkwast]

I believe the getting started page is this one (with URL get-started but title Quickstart), which just links to the other one with URL quickstart and another title...)

• https://valkey.io/topics/get-started/
• https://valkey.io/topics/quickstart/

@melroy89 Can we edit the first section of topics/index.md to contain what you think are the most important links? This page was modeled after how the redis website's start page looked before Salvatore left as a maintainer, but I haven't spent much time structuring it.

[stockholmux]

Thanks @zuiderkwast, I totally overlooked those. Thanks!

@melroy89 It's also possible to add it to the /docs/ page. It's just an item in markdown that's styled to make it into the boxes (see https://github.com/valkey-io/valkey-io.github.io/pull/154/files#diff-6ee90086fd7bb36ad1e5e3e1a9e9a96edecc4da2a9e60bcb70f33f2f2d7e030aR11). Maybe a further pull request after this is merged?

[zuiderkwast]

@stockholmux Yes, please merge.

@melroy89 doc repo help wanted. ;)