Formatting & Display Issues
This page covers problems where content loads but does not display correctly.
Problem: Material Icons Not Displaying
Symptom: Text like :material-arrow-right: appears as literal text instead of rendering as an icon.
Cause: The pymdownx.emoji extension is not configured in mkdocs.yml, or it is configured incorrectly.
Solution: Verify that mkdocs.yml contains the emoji extension with the correct settings:
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
Both emoji_index and emoji_generator must use the exact !!python/name: syntax. Check for typos and ensure the indentation is correct (the sub-properties must be indented under pymdownx.emoji:).
Problem: Octicons Syntax Not Working
Symptom: Text like [:octicons-arrow-right-24: Configure Infrastructure] appears as literal text instead of an icon with a link.
Cause: The :octicons-*: icon set is not supported by the EPMware configuration. Only :material-*: icons are available.
Solution: Replace octicons references with the equivalent Material Design icon:
<!-- WRONG — octicons not supported -->
[:octicons-arrow-right-24: Configure Infrastructure](infrastructure.md)
<!-- CORRECT — use Material icon -->
[:material-arrow-right: Configure Infrastructure](infrastructure.md)
Common replacements:
| Octicons | Material Equivalent |
|---|---|
:octicons-arrow-right-24: |
:material-arrow-right: |
:octicons-link-24: |
:material-link: |
:octicons-file-24: |
:material-file-document: |
:octicons-gear-24: |
:material-cog: |
Problem: Admonition Not Rendering (Shows as Plain Text)
Symptom: A note or warning block displays as plain text instead of a styled box:
!!! note
This is important information.
Cause: The content inside the admonition is not indented with 4 spaces.
Solution: Indent all content lines inside the admonition by exactly 4 spaces:
!!! note
This is important information.
This second line is also part of the note.
Tabs vs Spaces
Admonition content must use spaces for indentation, not tabs. If your editor auto-indents with tabs, the admonition will not render. Configure your editor to use 4 spaces for markdown files.
Problem: Image Caption Displays as Separate Paragraph
Symptom: The italic caption text appears with extra spacing below the image instead of directly under it.
Cause: Missing <br/> tag between the image and the caption, or a blank line separating them.
Solution: Use the <br/> tag and ensure no blank line between the image and caption:
<!-- CORRECT — br tag, no blank line -->
<br/>
*Caption text*
<!-- WRONG — blank line separates image and caption -->
*Caption text*
<!-- WRONG — missing br tag -->
*Caption text*
Problem: Table Not Rendering
Symptom: A table appears as plain text with pipe characters instead of a formatted table.
Cause: Missing separator row (the row of dashes and pipes below the header), or incorrect formatting.
Solution: Ensure the table has a proper header separator row:
<!-- CORRECT -->
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1 | Data 2 | Data 3 |
<!-- WRONG — missing separator row -->
| Column 1 | Column 2 | Column 3 |
| Data 1 | Data 2 | Data 3 |
Also verify that the tables extension is listed in mkdocs.yml under markdown_extensions.
Problem: Code Block Not Displaying Correctly
Symptom: A fenced code block appears as plain text or is not syntax-highlighted.
Cause: The pymdownx.superfences extension is missing from mkdocs.yml, or the code fence uses incorrect syntax.
Solution: Verify the extension is configured:
markdown_extensions:
- pymdownx.superfences
Ensure code fences use triple backticks with an optional language identifier:
```yaml
theme:
name: material
```
Problem: Card Layout Not Displaying Properly
Symptom: HTML card elements (<div class="grid cards">) display as plain text or without styling.
Cause: The md_in_html extension is not enabled, or the attr_list extension is missing.
Solution: Verify both extensions are in mkdocs.yml:
markdown_extensions:
- attr_list
- md_in_html
Also check that the HTML is valid — unclosed tags, missing quotes on attributes, or mismatched <div> tags will break rendering.
Problem: Dark Mode Colors Look Wrong
Symptom: Custom-styled elements are unreadable or invisible when dark mode is activated.
Cause: The CSS uses hard-coded light-mode colors instead of theme-aware CSS variables.
Solution: Use Material theme CSS variables that automatically adapt to the active color scheme:
/* WRONG — hard-coded color that may be invisible in dark mode */
.custom-element {
color: #333333;
background-color: #ffffff;
}
/* CORRECT — uses theme-aware variables */
.custom-element {
color: var(--md-default-fg-color);
background-color: var(--md-default-bg-color);
}
Common Material theme CSS variables:
| Variable | Description |
|---|---|
--md-default-fg-color |
Default text color |
--md-default-bg-color |
Default background color |
--md-default-fg-color--light |
Lighter text (captions, secondary) |
--md-code-bg-color |
Code block background |
--md-primary-fg-color |
Primary theme color |
--md-accent-fg-color |
Accent theme color |
Problem: Mermaid Diagrams Not Rendering
Symptom: A Mermaid diagram code block shows as plain text instead of a rendered diagram.
Cause: The pymdownx.superfences extension is not configured with the Mermaid custom fence.
Solution: Verify the custom_fences configuration:
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_mermaid
Then use the mermaid code fence in your markdown:
```mermaid
graph LR
A[Start] --> B[Process]
B --> C[End]
```
Problem: Search Not Finding New Content
Symptom: New or recently updated pages do not appear in search results.
Cause: The search index is built at deploy time. If you are testing locally, the search index may be stale.
Solution: Stop mkdocs serve (Ctrl+C) and restart it. The search index is rebuilt when the server starts. On the live site, the search index updates automatically when the site is redeployed.