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

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.

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

Tip

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

Text Formatting

Tip

See also:

Tip

See also:

Note

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

Note

Tip

See also:

Tip

See also:

Tip

See also:

Tip

See also:

Tip

See also: