Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.
Version: v1.21

Writing guide

Front matter​

The front matter represents the metadata for each page. It is written at the top of each page and must be enclosed by --- on both sides.

Example:

---
sidebar_position: 1
description: How to write documentation
---

Learn more about front matter in Docusaurus.

Names and URLs​

Use kebab-case-with-dashes instead of snake_case_with_underscores or spaces for file names, directory names, and slugs because URL paths typically use dashes.

Ensure that the file name/URL path matches the title of the page. For example, if the title of your page is "Getting Started", then the file name/URL path should also be "getting-started" to maintain consistency. The slug field should be the same as the file name. Only use a different slug field in some special cases, such as for backward compatibility with existing links.

Use the sidebar_position in the front matter to set the order of the pages in the sidebar. Please ensure that the sidebar_position is unique for each page in that directory. For example, if there are several pages in the folder "Getting Started", let sidebar_position equal "1", "2", "3", "4", and so on to avoid duplication.

Headers​

Use sentence case for headers: ### Some header with URL, not ### Some Header With URL.

Please use relative .md file paths for links. It is required for documentation versioning.

Examples:

To link to a file in the same directory, use the file name.

  • [file in the same directory](/contributing/writing-guide)

To link to file in a different directory, specify the relative file path.

  • [file in a different directory](/basic-operations/read).

Images​

Please store all images under blog or docs in the static/img folder.

Also, you can collate images for a specific blog post inside a single folder. For partner blog posts, store related images in the same folder, as /img/blog/partner-name/image.png.

Otherwise, name the folder appropriately using the YYYY-MM-DD format, for example, a typical path for an image will be /img/blog/2023-01-01/ferretdb-image.jpg.

Alt text​

Please remember to add an alternate text for images. The alt text should provide a description of the image for the user. When you add a banner image, please use the title of the article as the alt text.

Image names​

Use of two or three descriptive words written in kebab-case-with-dashes as the names for the images. For example, ferretdb-queries.jpg.

Use Markdown syntax for images with descriptive alt texts and the path. All assets (images, gifs, videos, etc.) relating to FerretDB documentation and blog are in the static/img/ folder. Rather than use relative paths, we strongly suggest the following approach, since our content engine renders all images directly from the img folder.

![FerretDB logo](/img/logo-dark.png).

Code blocks​

Always specify the language in Markdown code blocks.

For MongoDB shell commands, use js language. Our tooling will automatically reformat those blocks.

db.league.find({ club: 'PSG' })

For MongoDB shell results, use json5 language and copy&paste the output as-is, with unquoted field names, single quotes for strings, without trailing commas, etc. Our tooling will not reformat those blocks.

[
  {
    _id: ObjectId("63109e9251bcc5e0155db0c2"),
    club: 'PSG',
    points: 30,
    average_age: 30,
    discipline: { red: 5, yellow: 30 },
    qualified: false
  }
]

Use sql for SQL queries. Use text for the psql output and in other cases.

SELECT _jsonb FROM "test"."_ferretdb_database_metadata" WHERE ((_jsonb->'_id')::jsonb = '"customers"');
 _jsonb ----------------------------------------------------------------------------------------------------------------------------------------------
 {"$s": {"p": {"_id": {"t": "string"}, "table": {"t": "string"}}, "$k": ["_id", "table"]}, "_id": "customers", "table": "customers_c09344de"}
ferretdb=# \d test._ferretdb_settings
          Table "test._ferretdb_settings"
  Column  | Type  | Collation | Nullable | Default
----------+-------+-----------+----------+---------
 settings | jsonb |           |          |

ferretdb=# SELECT settings FROM test._ferretdb_settings;
                                             settings
--------------------------------------------------------------------------------------------------
 {"$k": ["collections"], "collections": {"$k": ["groceries"], "groceries": "groceries_6a5f9564"}}
(1 row)

Terminologies​

To be sure that you're using the right descriptive term, please check our glossary page for relevant terms and terminologies about FerretDB. If the word is not present in the glossary page, please feel free to ask on Slack or in the blog post issue.