There are three types of links in the MariaDB docs: external, relative, and space. The general rules for when to use each are:
If the link is outside of https://mariadb.com/docs/ → Use an External Link
If the link is to a page in the same space → Use a Relative Link
If the link is to a page in another space → Use a
See for information on what Spaces are.
In GitBook (our documentation system), Spaces are the main sections of the site you see along the top of every docs page:
What space you are in is very important in determining whether you need to use a or link. Gitbook identifies Spaces via a unique space identifier. See the section for more details. We also have a handy for use when creating space links in Markdown.
In the on GitHub, the spaces are the top-level folders.
External links are the easiest, they are to external pages outside the site. Some examples in Markdown syntax of external links are:
Technically, you can use external links for links to docs content, you just put in the full URI to the page you want to link to. However, if you do that we lose the ability to automatically update the link if the page you're linking to is moved or renamed. So for links to docs content we prefer to use or .
Relative links are links to a page in the same space, relative to the page you are editing. For example a relative link to the page, from this page, looks like this in Markdown:
One big limitation of relative links is that they cannot cross boundaries.
This page you are currently reading is under the space, so we can use internal links to link to other pages under https://mariadb.com/docs/general-resources/. If we want to link to a page in another space, we need to use .
To link to pages in other we need to use special Space Links which use an internal identifier so that GitBook knows exactly what page you are pointing to.
A space link begins with https://app.gitbook.com/s/ , followed by a unique alphanumeric space identifier (in this doc we'll call both of these together the space prefix), and finally the path to the page without the final .md extension that exists in the source code.
The path is everything after the space name in a full page URI. For example, take the following full URI for the page:
In this URI, the space name is server and the path, if you were creating a space link, is:
To convert that into a space link we need to get the Server space identifier and combine it with the path. Rather than list out just the identifiers for our spaces, we have a that you can copy from when creating space links.
Space link prefixes are hard to memorize. To make it easier for contributors, a GitHub Action is available that runs automatically on commit. That functionality allows to use space aliases instead of prefixes. For instance, to place a link to a page in the server space from, say, the release-notes space, you can write this:
On commit, this will be expanded to this:
These space link aliases are available:
Instead of using space link aliases, you can use "regular" GitBook link prefixes. That's harder than using link aliases, because they're hard to memorize. Therefore, using link aliases is recommended.
Continuing with our example, a full space link in Markdown for the page is: space prefix (for the Server space) + path:
See the section for a list of all of our space prefixes.
A handy list of all space prefixes for the MariaDB Docs:
Here are some examples of Markdown links to various pages using space links:
When Space Links are rendered to the public site, GitBook handles translating Space Links into a link to the correct page. And if a page is moved or renamed then the link will be automatically updated on every page it appears on.
