Text Formatting

You should add formatting to words, phrases, or blocks that require emphasis. You can use one of the formatting options to convey emphasis: weight (bold), variant (italics), or pitch (monospace).

When formatting text, use the following guidelines:

To apply a font treatment, use the appropriate markup in your authoring tool. In reStructuredText, use a role or directive if one is available.
Don't apply emphasis to text in titles and headings. An exception would be if a title of a page or a heading of a section covers some code or command.
Don't change the case of the text to emphasize a term. This includes showing a general term in all capitals, small capitals, or initial capitals. If you are representing all-cap text from the user interface, write it as initial cap instead.
Don't use color to distinguish text.
Use quotation marks only as directed in this topic and in Quotation marks.
Use monospace only as directed in this topic. Don't apply monospace to manually format a code example (see also Code Examples).

The following table shows the text formatting to use for different text elements. The following style differences are highlighted:

Content that documents a CLI or API versus a GUI

Application names

Apply no additional formatting.

Tip

Product Names.

Code Example

You must configure MongoDB Compass.

Rendered Example

You must configure MongoDB Compass.

Area (group box) names

Format using :guilabel: role and capitalize the first letter of each word.

Code Example

In the :guilabel:`Edit Signature` area, enter the text that
you want to appear in your signature.

Rendered Example

In the Edit Signature area, enter the text that you want to appear in your signature.

Argument names

Format using monospace text.

Code Example

To list or retrieve files from a node that's running the
OpenCenter agent, use the ``file`` argument with the
``opencentercli`` node command.

Rendered Example

To list or retrieve files from a node that's running the OpenCenter agent, use the file argument with the opencentercli node command.

Attribute names

Format using monospace text.

Code Example

The ``expires`` attribute denotes the time after which
the token automatically becomes invalid.

Rendered Example

The expires attribute denotes the time after which the token automatically becomes invalid.

Box names

This covers check box, combo box, group box, list box, spin box, and text box. Format them using the :guilabel: role.

Code Example

Select the :guilabel:`Manually configure server settings
or additional server types` check box.
Retype the password that you entered in the
:guilabel:`Password` box.

Rendered Example

Select the Manually configure server settings or additional server types check box.

Retype the password that you entered in the Password box.

Button names

This covers command, option, radio. Format using the :guilabel: role.

Code Example

Select :guilabel:`Microsoft Exchange` and then click
:guilabel:`Next`.

Rendered Example

Select Microsoft Exchange and then click Next.

Cascades

Order by menu, then field.
Format using the :guilabel: role.
Separate levels with >.

Code Example

Select :guilabel:`Start > Control Panel`, and then
click the :guilabel:`Mail` icon.

Rendered Example

Select Start > Control Panel, and then click the Mail icon.

Check box names

Format using :guilabel: role.

Code Example

Select the :guilabel:`Manually configure server settings
or additional server types` check box.

Rendered Example

Select the Manually configure server settings or additional server types check box.

Code, Examples

Format using a block-level directive that points directly to a code file (literalinclude or io-code-block).

Note

Avoid Hard-Coded Code Blocks for Code Examples

To support continuously tested code examples in our docs, prefer linking to the generated code file by using literalinclude or io-code-block directives instead of hard-coding a code example on the page by using code-block. See also Code Examples.

Code Example

.. literalinclude:: /path/to/code/file.js
   :language: javascript
   :category: syntax example

Points to a file.js JavaScript file:

file.js

   collection.createIndex(
     <keyAndIndexTypeSpecification>, <options>
   )

Rendered Example

collection.createIndex(
  <keyAndIndexTypeSpecification>, <options>
)

Code, Inline

Format using monospace text for any code-related reference within paragraph text, such as a database name or command flag. See also Code Examples.

Code Example

Use the ``startTransaction()`` method to define and
pass transaction options to your session.

Rendered Example

Use the startTransaction() method to define and pass transaction options to your session.

Column names

Format using :guilabel: role.

Code Example

Sort the backups by server by clicking the
:guilabel:`Server` column label.

Rendered Example

Sort the backups by server by clicking the Server column label.

Combo box names

Format using :guilabel: role.

Code Example

Select a name from the :guilabel:`Send to` list, or type
a new name.

Rendered Example

Select a name from the Send to list, or type a new name.

Command names

Format using monospace text.

Code Example

Check the architecture on Linux by using the
``uname -a`` command.

Rendered Example

Check the architecture on Linux by using the uname -a command.

Command examples

Format using a block-level directive that points directly to a code snippet file (literalinclude or io-code-block).

Note

Avoid Hard-Coded Code Blocks for Code Examples

Code Example

To connect to an Atlas cluster, use a connection string
with the following syntax:
.. literalinclude:: path/to/bash-file.txt
   :category: syntax example
To set your home directory path:
.. literalinclude:: path/to/dos-file.txt
   :category: non-mongodb command

Rendered Example

To connect to an Atlas cluster, use a connection string with the following syntax:

bash-file.txt

mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.net

To set your home directory path:

dos-file.txt

SET HOME=<home-directory>

Configuration file

Format using a block-level directive that points directly to a code file (literalinclude or io-code-block). These are typically .ini, .json, .yaml files.

Note

Avoid Hard-Coded Code Blocks for Code Examples

Code Example

.. literalinclude:: path/to/example.ini
   :category: example configuration object
   :copyable: false
.. literalinclude:: path/to/example.yaml
   :category: example configuration object
   :copyable: false

Rendered Example

 mmsBaseUrl=http://example.com:8080

apiVersion: atlas.mongodb.com/v1
kind: AtlasDeployment
metadata:
name: my-atlas-cluster
spec:
backupRef:
    name: atlas-default-backupschedule
    namespace: mongodb-atlas-system

Cross-references

Tip

Links and Cross-References.

Database names

Format using monospace text.

Code Example

Start by creating a new database called ``mytestdb``.

Rendered Example

Start by creating a new database called mytestdb.

Dialog box names

Format using the :guilabel: role.

Code Example

In the :guilabel:`Microsoft Exchange` dialog box, click
:guilabel:`Apply` and then click :guilabel:`OK`.

Rendered Example

In the Microsoft Exchange dialog box, click Apply and then click OK.

Directory names

Format using monospace text.

Code Example

The following example shows a basic configuration for
the FTP service, in a file in the ``/etc/xinetd.d/``
directory.

Rendered Example

The following example shows a basic configuration for the FTP service, in a file in the /etc/xinetd.d/ directory.

Document titles

Format using italics.

Note

You can't use italic if the title is a hyperlink.

Code Example

For details about code examples, see the "Code examples"
section in the *Microsoft Style for Technical
Publications, 4th Edition*.

Rendered Example

For details about code examples, see the "Code examples" section in the Microsoft Style for Technical Publications, 4th Edition.

Element names

Format using monospace text.

Code Example

The ``message`` element returns a human-readable message
that's appropriate for display to the end user.

Rendered Example

The message element returns a human-readable message that's appropriate for display to the end user.

Email addresses, not clickable

Format using boldface.

Code Example

**your.name@example.com**

Rendered Example

your.name@example.com

Email addresses, clickable

Apply no additional formatting.

Code Example

If you have any questions regarding this agreement or
the backup software, please direct all correspondence
to: legal@mongodb.com.

Rendered Example

if you have any questions regarding this agreement or the backup software, please direct all correspondence to: legal@mongodb.com.

Emphasis

Format using italics.

Code Example

Offset *must* be a multiple of the limit (or zero);
otherwise, a Bad Request exception is generated.

Rendered Example

Offset must be a multiple of the limit (or zero); otherwise, a Bad Request exception is generated.

Environment variables, inline

Format using monospace text when referencing environment variables in paragraph text.

Code Example

Export the tenant ID to the ``$account`` environment
variable and the authentication token to the ``$token``
environment variable.
Copy the binaries into a directory listed in your
``PATH`` variable.

Rendered Example

Export the tenant ID to the $account environment variable and the authentication token to the $token environment variable.

Copy the binaries into a directory listed in your PATH variable.

Error messages, inline

Format using monospace text inline.

Code Example

If your comment to an acknowledgement is too long, the
API returns:
``Acknowledgement comment too long. It must not exceed
<number> characters.``

Rendered Example

If your comment to an acknowledgement is too long, the API returns:

Acknowledgement comment too long. It must not exceed <number> characters.

Error messages, output

Format error messages that are expected output as part of an example as the output portion of an io-code-block directive that points directly to the error message file.

Code Example

.. io-code-block::
    .. input:: /path/to/input/send-acknowledgement.py
      :language: python
      :category: usage example
    .. output:: /path/to/output/error-message.txt
      :language: text
      :visible: true

Rendered Example

    try:
        data = send_acknowledgement(ticket_id, comment, base_url, token)
        print(f"ACK sent: id={data.get('id', '<unknown>')}")
    except ValueError as ve:
        print(str(ve))
        sys.exit(1)

   Acknowledgement comment too long. It must not exceed
125 characters.

Field names, GUI

Format using :guilabel: role.

Code Example

In the :guilabel:`Database Name` field, enter a database
name identifier.

Rendered Example

In the Database Name field, enter a database name identifier.

File names and extensions

Format using monospace text.

Code Example

To remove the ``vs_quantum-api.cfg`` file from the
``haproxy.d`` directory and retain it, you can move it
to another directory.

Rendered Example

To remove the vs_quantum-api.cfg file from the haproxy.d directory and retain it, you can move it to another directory.

Flags

Format using monospace text.

Code Example

Use the ``-t`` flag to add a timestamp to the results.

Rendered Example

Use the -t flag to add a timestamp to the results.

Folder names

Format using monospace text.

Code Example

Container names are sorted based on a binary comparison,
a single built-in collating sequence that compares
string data using the ``memcmp()`` function, regardless
of text encoding.

Rendered Example

Container names are sorted based on a binary comparison, a single built-in collating sequence that compares string data using the memcmp() function, regardless of text encoding.

Glossary terms

Format using :term: role.

Code Example

MongoDB deploys a :term:`replica set` after you click
:guilabel:`Save`.

Rendered Example

MongoDB deploys a replica set after you click Save.

Group box names

Format using :guilabel: role.

Code Example

In the :guilabel:`Edit Signature` area, enter the text
that you want to appear in your signature.

Rendered Example

In the Edit Signature area, enter the text that you want to appear in your signature.

GUI labels

Format using :guilabel: role.

Note

Exception: Show window, dialog box, wizard, page, panel, and screen names in regular text unless they need to be distinguished from the surrounding text. In such cases, use bold.

Code Example

In the :guilabel:`Microsoft Exchange` dialog box, click
:guilabel:`Apply` and then click :guilabel:`OK`.
On the :guilabel:`Choose Service` page, select
:guilabel:`Microsoft Exchange or compatible service`,
and then click :guilabel:`Next`.

Rendered Example

In the Microsoft Exchange dialog box, click Apply and then click OK.

On the Choose Service page, select Microsoft Exchange or compatible service, and then click Next.

Read the preliminary steps in the Configure Your Server wizard, and then click Next.

HTML tags

Format using monospace text.

Code Example

Avoid putting the ``xml:id`` attribute on the ``title``
tag.

Rendered Example

Avoid putting the xml:id attribute on the title tag.

Hyperlinks, clickable

Tip

Links and Cross-References.

Icon names

Format using :guilabel: role.

Code Example

To verify which OS version you're running, click the
:guilabel:`Apple` icon in the top-left corner and then
select :guilabel:`About This Mac`.

Rendered Example

To verify which OS version you're running, click the Apple icon in the top-left corner and then select About This Mac.

Keyboard key combinations, names, and shortcuts

Format using the :kbd: role.

Code Example

Press :kbd:`Shift-G` and then press :kbd:`Enter`.

Rendered Example

Press Shift-G and then press Enter.

Letters as letters

Format using italics.

Code Example

Place *i* before *e* except after *c*.

Rendered Example

Place i before e except after c.

Links, clickable

Tip

Links and Cross-References.

List box names and selections

Format using :guilabel: role.

Code Example

From the :guilabel:`Account Type` list, select
:guilabel:`Exchange 2007`.
To view these settings, select
:guilabel:`Configure Backup` from the
:guilabel:`Backup Actions` list.

Rendered Example

From the Account Type list, select Exchange 2007.

To view these settings, select Configure Backup from the Backup Actions list.

Menu names and commands

Format using :guilabel: role.

Code Example

Right-click the volume and select
:guilabel:`Take Offline`.
From the :guilabel:`Outlook` menu, select
:guilabel:`Preferences`.

Rendered Example

Right-click the volume and select Take Offline.

From the Outlook menu, select Preferences.

Menu sequences

Format as Cascades.

Messages (error, warning)

Format using monospace text.

Code Example

In SQL Server Management Studio, when you right-click a
SQL Server 2012 database and selecting
:guilabel:`Properties`, the following error message
appears:
``The user doesn't have permission to perform this action.``

Rendered Example

In SQL Server Management Studio, when you right-click a SQL Server 2012 database and selecting Properties, the following error message appears:

The user doesn't have permission to perform this action.

Method names, HTTP

Format using monospace with all capital letters.

Code Example

Client authentication is provided through a REST
interface by using the ``GET`` method.

Rendered Example

Client authentication is provided through a REST interface by using the GET method.

Option names, command

Format using :option: role.

Code Example

The size of the oplog is only configurable during the
first run using the ``--oplogSize`` argument to the
:binary:`~bin.mongod` command, or preferably, the
:setting:`~replication.oplogSizeMB` setting in the
MongoDB configuration file. If you do not specify this
on the command line before running with the
:option:`mongod --replSet` option, :binary:`~bin.mongod`
creates a default sized oplog.

Rendered Example

The size of the oplog is only configurable during the first run using the --oplogSize argument to the mongod command, or preferably, the oplogSizeMB setting in the MongoDB configuration file. If you do not specify this on the command line before running with the --replSet option, mongod creates a default sized oplog.

Option button names

Format using :guilabel: role.

Code Example

Select :guilabel:`Microsoft Exchange` and then click
:guilabel:`Next`.

Rendered Example

Select Microsoft Exchange and then click Next.

Package names

Format using monospace text.

Code Example

You must install the ``libvirt`` package.

Rendered Example

You must install the libvirt package.

Page names

Format using :guilabel: role.

Code Example

On the :guilabel:`Preferences` page, you determine how
frequently you receive email about all the activity on
your account: daily, weekly, or both.
On the :guilabel:`Server Settings` page, click
:guilabel:`Check Name`, type your password, and then
click :guilabel:`OK`.

Rendered Example

On the Preferences page, you determine how frequently you receive email about all the activity on your account: daily, weekly, or both.

On the Server Settings page, click Check Name, type your password, and then click OK.

Panes, named and unnamed

Format using :guilabel: role.

Code Example

To verify that your TLS binding works, select your
website in the :guilabel:`Connections` pane (if it's not
already selected) and then click :guilabel:`Browse
ipAddress (https)` in the :guilabel:`Actions` pane.
In the navigation pane, select
:guilabel:`Compose Email`.

Rendered Example

To verify that your TLS binding works, select your website in the Connections pane (if it's not already selected) and then click Browse ipAddress (https) in the Actions pane.

In the navigation pane, select Compose Email.

Paths

Format using monospace text.

Code Example

The path to Perl is ``#!/usr/bin/perl -w``.
In the URI path
``https://cloud.mongodb.com/api/public/v1.0``, the API
version is 1.

Rendered Example

The path to Perl is #!/usr/bin/perl -w.

In the URI path https://cloud.mongodb.com/api/public/v1.0, the API version is 1.

Permissions

Apply no additional formatting. Covers file permissions on any operating system.

Code Example

Log in to a shell as the user who has write permissions
to ``/usr/local/bin`` on your local computer.

Rendered Example

Placeholder text

Tip

Placeholder or Variable Text.

Privileges

Apply no additional formatting unless the privilege is an operating system command like sudo. Otherwise, you can say elevated privileges.

Code Example

The following examples assume that you're making the
firewall changes as a normal user with ``sudo``
privileges.
The user is granted ALL privileges on the database.

Rendered Example

The following examples assume that you're making the firewall changes as a normal user with sudo privileges.

The user is granted ALL privileges on the database.

Qualifiers

Format using italic.

Code Example

1. *(Optional)* Enter a new name for the image.
    You can tell that the Managed Cloud post-build
    automation has successfully completed as follows:
    *(Windows servers)* The following file is created:
    **C:\\windows\\temp\\rs\_managed\_cloud\_automation\_complete.txt**
    *(Linux servers)* The following file is created:
    **/tmp/rs\_managed\_cloud\_automation\_complete**

Rendered Example

(Optional) Enter a new name for the image.
You can tell that the Managed Cloud post-build automation has successfully completed as follows:
(Windows servers) The following file is created: C:\windows\temp\rs_managed_cloud_automation_complete.txt
(Linux servers) The following file is created: /tmp/rs_managed_cloud_automation_complete

Quotations from another source

Format using Quotation marks, or block quote formatting

Code Example

"Scalability is key for our business," explained Nathan
Goff, Inavero Operations Director and Partner. "There's
nothing worse than making our clients look bad to their
customers."

Rendered Example

"Scalability is key for our business," explained Nathan Goff, Inavero Operations Director and Partner. "There's nothing worse than making our clients look bad to their customers."

Radio button names

Format using :guilabel: role.

Code Example

Select :guilabel:`Microsoft Exchange` and then click
:guilabel:`Next`.

Rendered Example

Select Microsoft Exchange and then click Next.

Role names

Format using the :authrole: or :atlasrole: as appropriate for the documented product's roles. Otherwise, format as regular text.

Code Example

The :authrole:`Global Owner` role has the permissions to
create, read, update, and delete resources within
multiple designated products where access is granted.

Rendered Example

The Global Owner role has the permissions to create, read, update, and delete resources within multiple designated products where access is granted.

Sequences

Format as Cascades.

Shell, Terminal, or Command Prompt

Format as Command examples.

Syntax statements

Format using monospace text.

Code Example

The main command used to change a file's owner or group
is ``chown``. The most common syntax used with ``chown``
is as follows:
``chown user:group file1 file2 file3``

Rendered Example

The main command used to change a file's owner or group is chown. The most common syntax used with chown is as follows:

chown user:group file1 file2 file3

Tab names

Format using :guilabel: role.

Code Example

In the :guilabel:`Microsoft Exchange` dialog box, click the
:guilabel:`Connection` tab and then select the
:guilabel:`Connect to Microsoft Exchange using HTTP`
check box.

Rendered Example

In the Microsoft Exchange dialog box, click the Connection tab and then select the Connect to Microsoft Exchange using HTTP check box.

Terms, new

Format using italics.

Code Example

MongoDB instances that are built using the base Linux
images are created without a dedicated swap partition
and with *swappiness* (a measure of how the Linux kernel
tries to use swap memory) set to 0.

Rendered Example

MongoDB instances that are built using the base Linux images are created without a dedicated swap partition and with swappiness (a measure of how the Linux kernel tries to use swap memory) set to 0.

Terms, unique sense

Don't use.

Tip

CMOS 7.57 Scare Quotes.

UI label

Format using :guilabel: role. If the UI uses all capital letters, change to capitalizing the first letter of each word.

Code Example

In the :guilabel:`Microsoft Exchange` dialog box, click
:guilabel:`Apply` and then click :guilabel:`OK`.
On the :guilabel:`Choose Service` page, select
:guilabel:`Microsoft Exchange or compatible service`,
and then click :guilabel:`Next`.
Read the preliminary steps in the
:guilabel:`Configure Your Server` wizard, and then click
:guilabel:`Next`.

Rendered Example

In the Microsoft Exchange dialog box, click Apply and then click OK.

On the Choose Service page, select Microsoft Exchange or compatible service, and then click Next.

Read the preliminary steps in the Configure Your Server wizard, and then click Next.

URL, not clickable

Format using boldface.

Code Example

To access the web interface, open your web browser and
navigate to **http://yourDomain.com/zipit-install.php**.

Rendered Example

To access the web interface, open your web browser and navigate to http://yourDomain.com/zipit-install.php.

URL, clickable

Tip

Links and Cross-References.

User GUI input

Format using boldface.

Code Example

In the :guilabel:`Server` text box, type **outlook**.

Rendered Example

In the Server text box, type outlook.

User CLI input

Format inline text that the user types into an IDE, editor, or prompt using monospace text. This is not the same as a Command Examples or Code, Examples.

Code Example

For the username, enter ``admin`` at the prompt.

Rendered Example

For the username, enter admin at the prompt.

Variable text

Tip

Placeholder or Variable Text.

Window names

Format using the :guilabel: role.

Code Example

In the :guilabel:`Network Connections` window,
right-click the private adapter and select
:guilabel:`Properties`.

Rendered Example

In the Network Connections window, right-click the private adapter and select Properties.

Wizard names, wizard page names

Format using the :guilabel: role.

Code Example

On the :guilabel:`Welcome` page of the :guilabel:`Active
Directory Domain Services Installation` Wizard, clear
the :guilabel:`Use advanced mode installation` check
box, and then click :guilabel:`Next`.

Rendered Example

On the Welcome page of the Active Directory Domain Services Installation Wizard, clear the Use advanced mode installation check box, and then click Next.

Words as words

Format using italics.

Code Example

Don't use *button* and *icon* interchangeably. If you're
referring to a command button or toolbar button (labeled
or unlabeled), use *button*. If you're referring to a
graphic on a screen, window, or other area, use *icon*.

Rendered Example

Don't use button and icon interchangeably. If you're referring to a command button or toolbar button (labeled or unlabeled), use button. If you're referring to a graphic on a screen, window, or other area, use icon.

Back

Telephone Numbers

Time