Standardize on one markdown link style

[stockholmux]

Most links in valkey-doc use paren style links:

A [foo](example.md) bar

Occasionally, some markdown files uses reference markdown style links.

A [foo][example] bar

Lorem ipsum ...

[example]: example.md

I'd like to standardize on one links style in the docs. Reference style links are (in general) far less common in the docs and in general.

[madolson]

I personally like paren style, but don't have a strong opinion. I see that @zuiderkwast used references in his history, so maybe he would like to chime in.

[zuiderkwast]

I don't mind changing, but why is it necessary to change? Both are valid markdown and should be understood by all tools.

We have headings in two styles too (underlined with dashes and with #).

[stockholmux]

IMHO, It's frankly abused in our docs currently and hurts code readability. The way it's used in our here is usually a few random, non-semantic characters with the definition randomly throughout the document. You really have to hunt to find where the original author used things like (foo)[sdfds]. I've seen this style used nicely in the past, but the style used occasionally in the docs seems to maybe not violate the letter of the spec, but may be the spirit of it.

It also kind of violates the one-sentence per line style followed here. Trying to read a commit with the URL split from the link is much less straight forward and either the link or the URL may not be visible in the diff.

Right now, it's no so widespread that it would be hard to change today. I'd rather just have writing standard include the inline version which is more common and easier to review.

Here is an example from command.md:

Line 76

* **random**: the command returns random results, which is a concern with verbatim script replication. This flag is a [command tip][tb].

Line 170

This is an array of simple strings that are the ACL categories to which the command belongs.
Please refer to the [Access Control List][ta] page for more information.

...

Which are defined randomly under Subcommands heading in a block like this:

Line 186

[ta]: ../topics/acl.md
[tb]: ../topics/command-tips.md
[td]: ../topics/key-specs.md
[tr]: ../topics/key-specs.md

If I changed the link text on 76, the diff may not show where tb goes to on 186, so it's hard to know if that would still be a valid URL for the new text.

[zuiderkwast]

Yeah, feel free to change to inline links. I agree they are more readable. But I hope there is no hard requirement to be 100% complaint to this, for Zola or anything.

[zuiderkwast]

We should add this to the README or CONTRIBUTING files where we should have some more guidelines about the structure of the pages, etc.