Skip to main content
EmergentEMERGENT
Emergent SolutionsKnowledge Base

Markdown Style Guide

This guide shows how different markdown elements render in the knowledge base.

Text Elements

Paragraphs

Regular paragraph text flows naturally. Keep paragraphs concise and focused on a single idea. Aim for 2-4 sentences per paragraph.

This is a second paragraph demonstrating the spacing between blocks of text.

Emphasis

  • Bold text for important terms
  • Italic text for emphasis or technical terms
  • Bold and italic for strong emphasis
  • ~~Strikethrough~~ for deprecated content
  • inline code for commands, file names, or code snippets

Links

Headings

Use headings to create clear document structure:

  • H1 (#) - Page title only, one per page
  • H2 (##) - Major sections
  • H3 (###) - Subsections
  • H4 (####) - Minor divisions (use sparingly)

Lists

Unordered Lists

  • First item
  • Second item
  • Third item with more text that might wrap to demonstrate how longer items display
    • Nested item
    • Another nested item
      • Deeply nested (avoid if possible)

Ordered Lists

  1. First step
  2. Second step
  3. Third step
    1. Sub-step A
    2. Sub-step B
  4. Fourth step

Task Lists

  • [x] Completed task
  • [ ] Pending task
  • [ ] Another pending task

Code

Inline Code

Use backticks for commands, file_names.txt, variableNames, and function() calls.

Code Blocks

JavaScript example:

// GA4 event tracking
dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'T12345',
    value: 99.99,
    currency: 'USD'
  }
});

HTML example:

<script>
  window.dataLayer = window.dataLayer || [];
</script>

JSON example:

{
  "event": "page_view",
  "page": {
    "type": "product",
    "category": "electronics"
  }
}

Bash/Terminal example:

npm install @next/mdx
npm run build

Tables

Simple Table

| Feature | Free | Pro | Enterprise | |---------|------|-----|------------| | Events/month | 10K | 100K | Unlimited | | Data retention | 2 months | 14 months | Custom | | Support | Docs | Email | Dedicated |

Complex Table

| Tool | Best For | Pricing | Our Rating | |------|----------|---------|------------| | GA4 | Marketing analytics, Google Ads integration | Free / Enterprise | Recommended | | Amplitude | Product analytics, user behavior | Usage-based | Good for SaaS | | Mixpanel | Event tracking, funnels | Per-user pricing | Good alternative |

Blockquotes

This is a blockquote. Use it for important callouts, notes, or quotations.

Note: You can include formatting inside blockquotes.

Including multiple paragraphs.

Horizontal Rules

Use sparingly to separate major sections:

Content after the divider continues here.

Checklists (for Procedures)

When documenting step-by-step procedures:

Pre-Launch Checklist

  • [ ] All tags have descriptive names
  • [ ] All triggers are correctly configured
  • [ ] Variables return expected values
  • [ ] Preview mode testing complete
  • [ ] No console errors
  • [ ] Tags fire on correct pages only

Best Practices

Do

  • Use clear, descriptive headings
  • Keep paragraphs short and focused
  • Include code examples where relevant
  • Link to related pages
  • Use tables for comparing options
  • Add context before code blocks

Don't

  • Don't skip heading levels (H2 → H4)
  • Don't use bold for entire paragraphs
  • Don't create walls of text
  • Don't leave links without context
  • Don't use images when text suffices

Template for New Pages

# Page Title

Brief introduction paragraph explaining what this page covers.

## Main Section

Content organized with clear headings and subheadings.

### Subsection

More detailed content, examples, or procedures.

## Related Resources

- [Link to related page](/knowledge-base/section/page)
- [Another related page](/knowledge-base/section/other-page)

---

**Previous:** [Previous Page](/knowledge-base/section/previous)
**Next:** [Next Page](/knowledge-base/section/next)

Previous: Contributing Guide