Docs Menu

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.

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

See also:

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, Inline

Format using monospace text.

Code Example

``grep "ftp" /etc/xinetd.d/*``

Rendered Example

grep "ftp" /etc/xinetd.d/*

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 syntax

Varies by operating system:

Linux, macOS

Format using the .. code-block:: console directive.

DOS, Windows Command-Line Interpreter

Format using the .. code-block:: doscon directive.

Windows Powershell

Format using the .. code-block:: ps1con directive.

Omit the command prompt if you aren't displaying the response in the same code block.

Code Example

If a service isn't running, use the service command to
start it, as follows:
.. code-block:: console
:copyable: false
sudo service httpd start
To set your home directory path:
.. code-block:: doscon
:copyable: false
SET HOME=<home-directory>
To retrieve your home directory path:
.. code-block:: ps1con
:copyable: false
echo $env:HOMEPATH

Rendered Example

If a service isn't running, use the service command to start it, as follows:

sudo service httpd start

To set your home directory path:

SET HOME=<home-directory>

To retrieve your home directory path:

echo $env:HOMEPATH
Configuration File, INI style

Format using the .. code-block:: ini directive.

Code Example

.. code-block:: ini
:copyable: false
mmsBaseUrl=http://example.com:8080

Rendered Example

mmsBaseUrl=http://example.com:8080
Configuration File, YAML style

Format using the .. code-block:: yaml directive.

Code Example

.. code-block:: yaml
:copyable: false
---
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
name: <myShardedCluster>
spec:
shardCount: 2
mongodsPerShardCount: 3
mongosCount: 2
configServerCount: 3
version: 4.2.2-ent
opsManager:
configMapRef:
name: <configMap.metadata.name>
# Must match metadata.name in ConfigMap file
credentials: <myCredentials>
type: ShardedCluster
persistent: true

Rendered Example

---
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
name: <myShardedCluster>
spec:
shardCount: 2
mongodsPerShardCount: 3
mongosCount: 2
configServerCount: 3
version: 4.2.2-ent
opsManager:
configMapRef:
name: <configMap.metadata.name>
# Must match metadata.name in ConfigMap file
credentials: <myCredentials>
type: ShardedCluster
persistent: true
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

Varies by operating system:

Linux, macOS

Format using monospace text and uppercase letters. Start with $ when getting, omit the $ when assigning.

HOME=<home-directory>
echo $HOME

DOS, Windows Command-Line Interpreter

Format using monospace text and uppercase letters. Start and end with % when getting, omit the % when assigning.

SET HOME=<home-directory>
echo %HOME%

Windows Powershell

Format using monospace text and uppercase letters. Start with $ when getting and assigning.

$env:HOMEPATH='<home-directory>'
echo $env:HOMEPATH

Code Example

Copy the binaries into a directory listed in your
``PATH`` variable, such as ``/usr/local/bin`` (Update
``/path/to/the/mongodb-directory/`` with your
installation directory as appropriate.)

Rendered Example

Copy the binaries into a directory listed in your PATH variable, such as /usr/local/bin (Update /path/to/the/mongodb-directory/ with your installation directory as appropriate.)

Environment variables

Format using monospace text.

Code Example

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

Rendered Example

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

Error messages

Format using monospace text inline. If the format of the error aids in user understanding, use the appropriate .. code-block:: directive.

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.

Examples, code

Format using the .. code-block:: directive with corresponding. Pygment lexer

Code Example

.. code-block:: javascript
:copyable: false
db.collection.create_index(
[
(<keyAndIndexTypeSpecification>
], <options>
)
.. code-block:: java
:copyable: false
collection.createIndex(
<keyAndIndexTypeSpecification>, <options>
)

Rendered Example

db.collection.create_index(
[
(<keyAndIndexTypeSpecification>)
], <options>
)
collection.createIndex(
<keyAndIndexTypeSpecification>, <options>
)
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
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
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

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

Placeholder 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

  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

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 syntax.
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.

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
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. Recommend using a .. code-block:: instead.

Code Example

Create a file by using a text editor. Insert the
following code: ``<?php phpinfo(); ?>``
For the username, enter ``admin``.

Rendered Example

Create a file by using a text editor, and insert the following code: <?php phpinfo(); ?>

For the username, enter admin.

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.