Writing styles and Markdown

The following sections provide simple formats for content. For additional formats, see markdown guides like Markdown Guide.

For an example of documentation using multiple Markdown formats, see the following: Managing Sources in HTML and source code.

Front matter

Every file begins with front matter or metadata for your content. This information includes:

---
group: Table of Contents file name
title: Title of the page
functional_areas: 
---

Parameter	Description
group:	The table of contents this file belongs to, which points to files located in _data/toc/. Only add the name of the file without the extension. For example, group: inventory points to the table of contents defined in _data/toc/inventory.yml.
title:	The title of the page.
functional_areas:	Optional. Adds facets for search results. Available facets include: Sales, Products, Carts, Customers, Marketing, Account, Content, Reports, Stores, System, Catalog, Orders, Frontend, Theme, Staging, Search, Configurations, Integration, Services, Tools, Setup, Testing, test, Standards, Install, Upgrade, B2B, Cloud, and Bundled extensions. These facets are case sensitive and support multiple facets separated by commas. For example: functional_areas: Install.
redirect_from	Optional. Add a list of other pages in DevDocs that should redirect to this page. The link should start with the /guides directory. For an example, see the source code for this template page.
contributor_name: Name contributor_link: URL	If a contributor submits a new topic, add this information to announce the contributor.
ee_only:	Optional. If set to true, graphics/cues display on the page indicating it applies to {{site.data.var.ee}}.

Paragraphs

As you start writing content, it automatically generates along the left side (or margin). To create a paragraph, leave an empty line between sentences.

If you need to indent content, use the tab key. Each tab moves content to the right, indenting the page content.

Text effects

To format for bolding and italics, see the following:

Example	Output
*emphasis*	emphasis
**bold**	bold

Bulleted lists

We recommend using a dash (-) for each line in a bulleted list. Lists also support *.

- List Item 1
- List Item 2
- List Item 3

Numbered steps

Numbered lists add numbers to a set of instructions or steps. Start every line with 1.. When building the documentation, the instructions automatically number for you.

1. Run composer update locally.
1. Add and commit these updated files to your Cloud Git repository.
1. Push the changes to your Cloud Integration environment.

Tables

Simple tables can help format content. For example, lists of attributes with descriptions. Adding the style below the table helps with formatting.

| Attribute | Description |
|--|--|
|name|Description of name|
|id|Description of ID|
{:style="table-layout:auto;"}

Links

Adding links to content outside of documentation: [GitHub](http://github.com)

Adding links to pages within the user guide:

[Topic Name]({{page.baseurl}}/<foldername>/<filename>.html)

For example:

[Managing Inventory]({{ site.baseurl }}{%- link catalog/inventory-management.md -%})

Images

We recommend saving all images in PNG format. Images are typically saved in the following locations:

• devdocs/common/images
• images folder in a documentation folder

Example code for displaying images from devdocs/common/images:

![Alt Text]({{ site.baseurl }}/common/images/<filename.png>)

Example code for images in an images folder in the same folder location:

![Alt Text](images/<filename>.png)

Notes

To highlight content in an info box, use an info note. It adds a blue box and an info icon. Change info to tip or warning for those formats.

{:.bs-callout-info}
Note content

Templates

For additional formats and options, see these templates:

• General topic template - Markdown | HTML: This is a template for writing any topic with example formats and styles.
• Tutorial templates: These templates provide example formats and styles for step-by-step instructions (like how-tos). Each file adds navigation buttons when content is generated. Templates include:
  • First introduction topic - Markdown | HTML: Introduction to a tutorial for prerequisites and listing steps
  • Middle topic - Markdown | HTML: Use for each step in a tutorial.
  • Final step topic - Markdown | HTML: Use for the last step of the tutorial.