Replace non-markdown markup

[zuiderkwast]

There is various marks like {{< highlight bash >}} and {{< clients-example hash_tutorial set_get_all >}} in the doc markdown files. They require some special rendering code on the website side.

We would like to be able to use the documentation markdown files for other things, like

• interactive documention in the cli [NEW] Extended Help for Commands. valkey#348
• man pages
• PDF or any other format of documentation

Thus, the idea is to replace this special markers with simple (github style) markdown.

• {{< highlight bash >}} can be replaced by regular github style markdown with syntax highlighting: ```bash
• {{< clients-example hash_tutorial set_get_all >}}, interactive example with commands in valkey-cli ==> ```valkey-cli -- this syntax highlighting will obviously not work out of the box, but we can handle it in the website rendering. For any other uses, it will just look like a code block.
• {{% alert title="Note" color="info" %}} ==> **Note:**
• {{% alert title="Note" color="warning" %}} ==> **Note:**

[zuiderkwast]

@stockholmux would this be OK with you for website rendering?

[stockholmux]

I'm of two minds here.

On one hand, we're going to need to remove the old Hugo cruft, so we need to make changes anyway. And the more we add foreign markup into these files the less portable they are.

On the other hand, some things are hard to do in straight markdown. Markdown is inherently linear, so any time you need to create something that surrounds something else there isn't a great way ({{% alert title="Note" color="info" %}} is an example as it has a pairing closing template tag). Additionally, diagrams and images are super tricky to position/size and a small amount of markup can make these much more useable. Finally, things like external file includes and description/title interpolation makes docs much more maintainable. I'd love to see a future where the examples are extracted from the markdown and included into the files, then we can actually test the examples with a script - that would be hard/difficult to do as-is.

All that being said, I am in favour of not going nuts with non-markdown markup, but light use can be super helpful.

I don't expect that users will directly use this repo as docs, in fact, I hope they don't: it won't be a great experience. If we want to provide man pages, pdfs, or in-cli docs, I think we can use this repo as a source and build out tools that produce artifacts specifically suited to the use case that does provide that great experience whatever the destination.

[zuiderkwast]

Markdown is limited for a good reasons i believe: Simplicity. There are lots of things you can't do.

If we'd want more kinds of syntax, there's asciidoc and lots of languages, but we have markdown now. Until Salvatore left, it was plain markdown without these non-markdown elements. They were added in the last years and IMAO they're completely unnecessary. The more complex elements you have in a format, the harder it is to convert it and render it to other formats.

The {{< ... >}} map to code blocks and these are delimited. We can keep the language annotation and (as suggested above) we can tag valkey-cli sessions with valkey-cli after the backticks and this can be used by tools to automatically validate them. It's an unobstructive way to include something in markdown.

The occurrences of {{% alert %}} just enclose a single small paragraph, in one case two. I don't think they're adding any usefulness to the pages, but they do add pain in the tool chain.

Well, you know I want to delete them. :) We can discuss in the core team if necessary.

I think we can use this repo as a source and build out tools that produce artifacts

I think this is adding way too much complexity. I want to remove complexity.

Slightly different topic: I'm open to using metadata sections at the top of markdown files. It's unobstructive too, since it's part of markdown.

[stockholmux]

I think this is adding way too much complexity. I want to remove complexity.

I get the desire for simplicity and complexity reduction, but there is more than one vector here.

Maintaining docs is hard and complex over time and moving everything to static markdown means that we have to manually maintain everything. I would much rather Valkey to take an approach doesn't ban everything that isn't markdown and balances easy of contribution with maintenance.

Long term, simple things like includes and use-specific documentation artifact will make the project more sustainable.

[stockholmux]

re: metadata at the top of files (aka frontmatter)

It's not directly usable today the way everything is split up. Functionally, it just includes the file as-is. This was done more for speed in the initial build of the Jekyll website. I'm not sure anyone is particularly in love with Jekyll, so we may be able to use it later when/if we move to a different SSG.

Although these are pretty closely tied to the SSG used there.

[zuiderkwast]

moving everything to static markdown means that we have to manually maintain everything.

This may be true for other things, I'm not talking about everything here. Just removing these alert boxes isn't something well have to maintain in any way.

re: metadata at the top of files (aka frontmatter)

It's not directly usable today the way everything is split up.

We can delete the current frontmatter and replace it with other fields.

If we can't use it from Jekyll, then we can preprocess the files with some other script that e.g. inserts actual markdown text in the files instead of the metadata.

If we store some data in frontmatter to make it easier for users to edit it, instead of editing separate JSON files (which often ends up in syntax errors), then this is already a gain IMO.