Skip to content

Editing Markdown Content

This section covers how to update page content in the EPMware documentation while following established conventions.

EPMware Content Conventions

All documentation pages follow these formatting standards:

Text Formatting

  • Use bold for UI elements, field names, button labels, and menu items (e.g., "Select Save to apply changes")
  • Use italics for emphasis and image captions
  • Use code formatting for filenames, paths, code snippets, and technical values
  • Use consistent header hierarchy: # for the page title (one per page), ## for main sections, ### for subsections

Procedures and Steps

Numbered procedures should follow this pattern:

### Add a Server

1. Select the **+** icon to display the **Add Server** popup.

2. Input a **Name** (label) for the server.

3. Select **Save** to save the configuration.

Spacing in Numbered Lists

Leave a blank line between each numbered step. This improves readability both in the markdown source and in the rendered output. MkDocs renders the steps with better spacing when blank lines separate them.

Admonitions (Notes, Warnings, Tips)

Use admonitions to highlight important information:

!!! note
    This is important information that users should be aware of.

!!! warning
    This indicates a caution or potential issue.

!!! tip
    This provides helpful advice or best practices.

!!! important
    Critical information that must not be overlooked.

The text inside an admonition must be indented with 4 spaces (not a tab). If the indentation is wrong, the admonition will not render correctly.

You can also create collapsible admonitions using ??? instead of !!!:

??? note "Click to expand"
    This content is hidden until the user clicks to expand it.

Tables

Convert tables to standard markdown format:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

Align the pipes (|) for readability in the source, though MkDocs does not require it.

Images with Captions

Images follow this pattern:

![Descriptive alt text](../assets/images/section/image-name.png)<br/>
*Caption text in italics*

The <br/> tag ensures the caption appears directly below the image. The caption uses italics (*text*).

See Managing Images for full details on image handling.

Making Content Changes

Editing Existing Text

  1. Open the .md file in your text editor.
  2. Make your changes, following the conventions above.
  3. Save the file.
  4. Run mkdocs serve and preview the page in your browser.
  5. Verify formatting renders correctly, links work, and images display.

Adding a New Section to an Existing Page

  1. Add a new heading at the appropriate level (## or ###).
  2. Write the content below the heading.
  3. If the section is significant, consider adding a link to it from the page's overview area or table of contents.
  4. If you reference this section from other pages, use the anchor format: page.md#section-heading (the anchor is the heading text in lowercase with hyphens replacing spaces).

Adding Content from the Word Document Source

When converting content from the EPMware Word document source:

Faithfulness to Source

Keep the markdown content accurate to the Word document source. Do not expand simple procedures, add explanatory content not in the original, or restructure information beyond what is needed for markdown formatting. When merging content into existing files, preserve all existing markdown content even if it does not appear in the Word source.

The general conversion process is:

  1. Identify the section in the Word document to convert.
  2. Create or open the target .md file.
  3. Convert headings, procedures, tables, and notes to markdown format.
  4. Replace Word document images with image placeholders using descriptive filenames.
  5. Extract the actual images from the Word document (see Managing Images).
  6. Preview locally with mkdocs serve to verify formatting.

Common Markdown Patterns Used in EPMware Docs

Several index pages use HTML card layouts for navigation:

<div class="grid cards">
  <div class="card">
    <h3>⚙️ Configuration</h3>
    <p>Set up dimension attributes and enable features</p>
    <a href="dimensions.md" class="md-button">Learn More →</a>
  </div>
</div>

HTML Links in Cards

Links inside HTML <a href> tags are not rewritten by MkDocs the same way markdown links are. See Managing Links for critical details about how these links must be formatted.

Material Design Icons

Icons use the :material-icon-name: syntax:

:material-arrow-right:        → (right arrow)
:material-check-circle:       ✓ (checkmark)
:material-alert:              ⚠ (alert)
:material-information:        ℹ (info)
:material-cog:                ⚙ (settings)
:material-shield-account:     🛡 (security)

Octicons Are Not Supported

The :octicons-*: icon syntax does not work with our configuration. Always use :material-*: icons. If you find any :octicons-*: references in the documentation, replace them with the equivalent :material-*: icon.

[:material-arrow-right: Configure Infrastructure](infrastructure.md)

This creates a clickable link with an arrow icon prefix.