Find a better solution for linking content between spec/ and docs/

[cason]

The documentation website is build from the docs/ directory of CometBFT's repository, which becomes the root directory (/) of the documentation website.

In order to also include the spec/ directory in the documentation website, this directory is copied into the root directory of the documentation website, thus becoming the /spec/ address.

This has introduced a problem with relative links between the content under docs/ and the content under spec/, as there is no match between relative links in the Github repository and in the documentation website.

For example, considering not necessarily valid files:

• spec/foo/bar.md on Github is rendered as /[version]/spec/foo/bar[.html] on the website
• docs/bar/foo.md on Github is rendered as /[version]/bar/foo[.html] on the website
• assume that the above bar page wants to include a link to the above foo page:
  • if the relative link ../../docs/bar/foo.md is adopted, it works on GitHub but it is broken in the website, as it will be rendered as /[version]/docs/bar/foo[.html] (note the additional /docs/ component)
  • if the relative link ../../bar/foo.md is adopted, it does not works on GitHub (because the docs/ prefix is missing), but it works on the website
• the same applies if the above foo file wants to include a link to the above bar file:
  • if the relative link ../../spec/foo/bar.md is adopted, it works on GitHub but it is broken in the website, as it will be rendered as /spec/foo/bar[.html] (note the missing /[version]/ component)
  • if the relative link ../spec/foo/bar.md is adopted, it does not works on GitHub (because there is no docs/spec), but it works on the website

The current solution for this problem is to adopt full links between parts of the same repository. While this solves the problem of possibly broken links, it introduces the problem of one source of the documentation pointing to the other, namely:

• if a full Github link is adopted, the docs website points to the Github, not to the content hosted by itself
• if a full documentation website link is adopted, the Github points to the website, not to the content there hosted

This issue is probably known by whoever attempted to write or update the documentation website, and there is no necessarily an easy solution for it.

What we could consider is to introduce some mechanism, on the Github repository and/or the documentation website, to render at least one of the combinations of cross-directory links above exemplified operational. An initial list of solutions to consider:

1. Create symbolic links on Github, for instance, spec/docs/ pointing to docs/ or docs/spec pointing to spec/?
2. Create similar links on the documentation website, for instance /[version]/docs/ pointing to /[version]/ or /[version]/spec/docs pointing to /[version]/?
3. Create some rewriting roles on the documentation website to fix this incongruity?