About MariaDB Documentation
The documentation for MariaDB products is
written in standard American English,
using Markdown format,
stored in Git.
It is maintained by a team of technical writers from MariaDB plc and the MariaDB Foundation.
Until June 2025, the documentation used to be in the MariaDB KnowledgeBase (KB). With a few exceptions, mostly concerning outdated modules and functionality, all pages were migrated to a new platform, GitBook.
Contributing Documentation
Instructions on how to contribute to MariaDB documentation
The documentation for MariaDB products is
written in standard American English,
using Markdown format,
stored in Git.
While the documentation is mainly maintained by the documentation team at MariaDB plc, we are happy to get contributions. Being stored in Git, it allows anyone to contribute to the documentation. You need a GitHub account, a basic knowledge of Markdown, and some expertise in what you’re writing about. You also have to agree to our contributor agreement.
Contributing is as simple as this:
Access this repository, log in with your GitHub account.
Find the page in the documentation that you want to edit, correct, or amend.
Make a pull request, edit, and submit.
The MariaDB documentation team will review your edits, smooth out any rough edges (language and style), and incorporate your contribution into the documentation. Don’t be afraid to submit imperfect contributions, as long as they’re factually correct.
Before you start making larger contributions, make yourself familiar with the basics of technical writing (a 1-minute read). This is about using proper tone and content, language and grammar, as well as formatting, punctuation, and organization.
The source format of pages is Markdown. How to format text is on this GitBook page. A Markdown cheat sheet with a 10-minute tutorial and a Markdown "playground" can be found here.
Read our style guide, too. (It's short!)
Also see the About Links page. It has useful information for when you are adding links to other pages.
Documentation Style Guide
Style Guide
We adhere to the Google developer documentation style guide. Here are some links to particularly important resources from that style guide:
Word list – an alphabetically ordered list that allows you to quickly find words to use, or not to use, and recommendations of words and terms to use.
Accessibility – write inclusive documentation for a global audience.
Timeless documentation – avoid words and terms like currently, existing, in the future, now, or soon.
Capitalization – when to use the Shift key, and how to format headings and titles. We use upper case for headings, which is about the only deviation from the Google style guide.
Abbreviations – how to use acronyms and initialisms.
Punctuation – how to properly use colons, commas, dashes, etc.
Formatting and organization – how to write dates and times, headings and titles, when to use lists or rather tables.
Cross-references – how to properly write links.
Code samples – how to write and format code blocks.
Example domain names, IP numbers, and person names – and how to use filenames and trademarks.
Additional Information
Version-specific information: We refer to software versions (like "MariaDB 10.6") only for products (like MariaDB Server or MaxScale) or features (like replication or authentication) that follow the N-1 rule, where N is the last version still under maintenance. (At the time of writing, that's MariaDB 10.6 for the Server.) In other words, we'd mention MariaDB 10.5, but not versions older than that.
This is the principle, from which we will deviate if there's a valid reason to do so.
Reporting Documentation Issues
Bug Reports
If you find issues in the documentation, please report them:
Report only one issue per request. If you find multiple issues, report them one by one. Only report documentation issues, not software issues or software help requests.
Provide the URL of the page that has an issue, for example https://mariadb.com/docs/general-resources/about/readme/reporting-documentation-bugs. ℹ️ When reporting via the rating system, the URL of the page you're on will be automatically be included in your response, so there's no need to include the URL.
Indicate the nature of the issue:
Typo, for example "known bucks should be known bugs".
Wrong information. Provide details of what's wrong. Ideally, point out what the right information should be.
Missing information. Provide details of what's missing.
Unclear information. Provide details of what's unclear. Ideally, provide a clarification.
Reporting Channels
Use one of the following channels to report documentation issues. Please don't report software issues via those channels — instructions for doing that are on this page.
Rating system in the right sidebar
This is a super quick way to provide feedback or report issues in the documentation. However, it's one-way communication — we can't provide feedback to you, since we don't know who you are. 😇 ℹ️ Don't paste the URL of the page you're reporting from, since it will automatically be included.
MariaDB Community Slack
Join the #documentation channel in MariaDB Community Slack. This allows for more detailed feedback or reports, and naturally provides two-way communication.
This page is licensed: CC BY-SA / Gnu FDL
About Links
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 LinkIf 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.
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.
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-mariadbIn this URI, the space name is server and the path, if you were creating a space link, is:
/security/securing-mariadbTo 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/JqgUabdZsoY5EiaJmqgnServer space prefix
https://app.gitbook.com/s/SsmexDFPv2xG2OTyO5yVMaxScale space prefix
https://app.gitbook.com/s/0pSbu5DcMSW4KwAkUcmXColumnStore space prefix
https://app.gitbook.com/s/rBEU9juWLfTDcdwF3Q14Galera Cluster space prefix
https://app.gitbook.com/s/3VYeeVGUV4AMqrA3zwy7Connectors space prefix
https://app.gitbook.com/s/CjGYMsT2MVP4nd3IyW2LTools space prefix
https://app.gitbook.com/s/kuTXWg0NDbRx6XUeYpGDRelease Notes space prefix
https://app.gitbook.com/s/aEnK0ZXmUbJzqQrTjFybGeneral Resources space prefix
https://app.gitbook.com/s/WCInJQ9cmGjq1lsTG91ESpace 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/reference/full-list-of-mariadb-options-system-and-status-variablesMariaDB 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)List of MariaDB Connector/C Releases in the Connectors space
[List of MariaDB Connector/C Releases/](https://app.gitbook.com/s/CjGYMsT2MVP4nd3IyW2L/mariadb-connector-c/list-of-mariadb-connector-c-releases)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.