About Links

This page is for contributors to the MariaDB Documentation and goes into detail on the internals of links. This page is not about MariaDB. If you're interested in contributing to the MariaDB Docs, please also see the Contributing Documentation and Documentation Style Guide pages.

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 Space Link

See About Spaces for information on what Spaces are.

About Spaces

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 Relative or Space link. Gitbook identifies Spaces via a unique space identifier. See the Space Links section for more details. We also have a handy list of Space prefixes for use when creating space links in Markdown.

In the documentation source repository on GitHub, the spaces are the top-level folders.

External Links

External links are the easiest, they are to external pages outside the https://mariadb.com/docs site. Some examples in Markdown syntax of external links are:

* [Example Website](https://example.com)
* [MariaDB Corp Blog](https://mariadb.com/blog)
* [MariaDB JIRA](https://jira.mariadb.org)

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 Relative Links or Space Links.

Relative Links

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 Joining the Community page, from this page, looks like this in Markdown:

[Joining the Community](../../community/joining-the-community.md)

One big limitation of relative links is that they cannot cross Space boundaries.

This page you are currently reading is under the General Resources 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 Space Links.

Space Links

To link to pages in other Spaces 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 Securing MariaDB page:

https://mariadb.com/docs/server/security/securing-mariadb

In this URI, the space name is server and the path, if you were creating a space link, is:

/security/securing-mariadb

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 List of Space Prefixes that you can copy from when creating space links.

Continuing with our example, a full space link in Markdown for the Securing MariaDB page is: space prefix (for the Server space) + path:

[Securing MariaDB](https://app.gitbook.com/s/SsmexDFPv2xG2OTyO5yV/security/securing-mariadb)

See the List of Space Prefixes section for a list of all of our space prefixes.

List of Space Prefixes

A handy list of all space prefixes for the MariaDB Docs:

MariaDB Platform space prefix

https://app.gitbook.com/s/JqgUabdZsoY5EiaJmqgn

Server space prefix

https://app.gitbook.com/s/SsmexDFPv2xG2OTyO5yV

MaxScale space prefix

https://app.gitbook.com/s/0pSbu5DcMSW4KwAkUcmX

Analytics space prefix

https://app.gitbook.com/s/rBEU9juWLfTDcdwF3Q14

Galera Cluster space prefix

https://app.gitbook.com/s/3VYeeVGUV4AMqrA3zwy7

Connectors space prefix

https://app.gitbook.com/s/CjGYMsT2MVP4nd3IyW2L

Tools space prefix

https://app.gitbook.com/s/kuTXWg0NDbRx6XUeYpGD

MariaDB Cloud space prefix

https://app.gitbook.com/s/vPz15Lz0Iw3P3yKR3Prd

Release Notes space prefix

https://app.gitbook.com/s/aEnK0ZXmUbJzqQrTjFyb

General Resources space prefix

https://app.gitbook.com/s/WCInJQ9cmGjq1lsTG91E

Space Link Examples

Here are some examples of Markdown links to various pages using space links:

Options, System & Status Variables in the Server space

[Options, System & Status Variables](https://app.gitbook.com/s/SsmexDFPv2xG2OTyO5yV/server-management/variables-and-modes/full-list-of-mariadb-options-system-and-status-variables)

MariaDB 12.1 Changes & Improvements in the Release Notes space

[MariaDB 12.1 Changes & Improvements](https://app.gitbook.com/s/aEnK0ZXmUbJzqQrTjFyb/community-server/release-notes-mariadb-12.1-rolling-releases/changes-and-improvements-in-mariadb-12.1)

MariaDB Connector/C Guide in the Connectors space

[MariaDB Connector/C Guide](https://app.gitbook.com/s/CjGYMsT2MVP4nd3IyW2L/connectors-quickstart-guides/mariadb-connector-c-guide)

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.