---
title: "Middleware Docs Style Guide and Guidelines"
description: "Follow Middleware documentation guidelines to maintain accuracy, clarity, and consistency across all guides."
section: "Misc"
breadcrumb: "Misc / Uncategorized > Docs Style Guide"
canonical: "https://docs.middleware.io/guidelines"
---
# Middleware Docs Style Guide and Guidelines

This style guide sets the conventions for writing Middleware documentation: how to structure pages, format headings and steps, write UI text and code samples, and use the site's Markdoc components.

## Typography and Formatting

**Title**: See this doc for example of how to display the title properly..
**Sections**: Use H2 headers (`## Section Title`) for sections, and H3 headers (`### Subsection Title`) for subsections.
**Numbering**: Use numbered steps where actions are sequential. Non-sequential points should use bullet points.

## General Text Guides

- **Bold**: Use `**bold**` for key terms, like component names or filenames.
- **Code**: Use inline code formatting (`code`) for commands, filenames, paths, and code elements within sentences.
- **Code Blocks**: Use triple backticks for block-level code snippets and terminal commands. Specify the language where applicable:

  ```bash
  npm install @middleware.io/node-apm --save
  ```

  ```javascript
  const tracker = require('@middleware.io/node-apm');
  ```
- **Links**: Hyperlink external references using the following format:
  `[Link Text](https://example.com)`

## General Document Structure

### Intro

This is one to two sentences introducing what the document is for. Keep this brief and to the point, no fluff.

### Prerequisites

- **List**: prerequisites should be in a **numbered list** under an **H2 header**.
- **Code snippets**: prerequisites should comprise a single command, or set of commands that can be formatted on a single line, and they should be on the same line as the prerequisite.
- **Bold**: bold the prerequisite as a call-out
- **Example**:

  ```plaintext
  ## Prerequisites
  1. **Node.js version 18.17.1+**: Verify with `node --version`
  2. **Python version 3.8+**: Verify with `python3 --version`
  ```

### Installation

#### Numbered Steps

Always use numbered lists for step-by-step instructions.

For smaller **lists of 1-3 steps** use numbered bullets e.g.

1. Step 1
2. Step 2
3. Step 3

For larger steps that require explanations (text) or many operations, use the **Number object** as seen below

#### 1 This is an example

Some text / code / etc.

#### 2 Of using the number object

Some text / code / etc.

#### Code Execution

For terminal commands, specify the shell, and use the correct syntax highlighting:
`bash     node --version     `

**API Key and Target Usage**: Always reference API keys and targets in code blocks using the `{% getproject %}` syntax to enable login based auto-fill:

```javascript
tracker.track({
    serviceName: "your-service-name",
    accountKey:"your-initial-token",
    target:"your-initial-uid",
});
```

#### Tab based organization

Tabs are to be used when providing instructions for the same Section or Subsection across many different environments, languages, frameworks, etc.

For code execution across languages where it is only one command, use the **Language Dropdown** (see Object Reference for example)

Below is an example of showing different steps per OS

#### Windows

To get started with Windows you will need to be on **Windows 64-bit** using **Version 10** or newer, and/or running **Windows Server 2016** or newer.

Download and follow the instructions from our [Windows installer](https://github.com/middleware-labs/mw-agent/releases), using the `MW_API_KEY` and `MW_TARGET` from below.

```bash
MW_API_KEY="your-initial-token"
MW_TARGET=your-initial-uid
```

#### Debian/Ubuntu

To install using Debian/Ubuntu run the below script to install the agent and relevant packages.

```bash
MW_API_KEY="your-initial-token" MW_TARGET=your-initial-uid bash -c "$(curl -L https://install.middleware.io/scripts/deb-install.sh)"
```

### Other Configuration Sections

These sections are going to differ between docs. The guidelines from the installation section apply. See "Object Reference" for other available objects like widgets, call outs, code snippets, etc.

### Troubleshooting and Debugging

All documents should include a Troubleshooting and Debugging section built using accordions:

#### Question 1

Some text

#### Question 2

Some text

### Metrics Collected

Use a simple table with **Metric** name and **Description** columns:

| Metric | Description |
| --- | --- |
| `mongodb.cache.operations` | Number of cache operations |
| `mongodb.collection.count` | Middleware is a full-stack cloud observability platform that collects telemetry data from front-end to back-end. We provide a simple observability solution to an otherwise complicated aspect of software design. |

## Object Reference

### Adding images

All images should be hosted in the /public/images directory, and can be embedded using the below object

```plaintext
{% image src="/images/image-dark.png" alt="Middleware logo" title="image-light" width="100%" height="100%" /%\}
```

### Embedding a video

Embed video using the below snippet example

```plaintext
{% embed src="https://www.loom.com/embed/ed0f136a6dd7436ba951356c936e0ca3?sid=f6086e36-2d46-49d5-9f7d-70ff35f956c5" width="100%" height="100%" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="true" /%\}
```

### All available headers

```plaintext
# Heading -1
## Heading - 2
### Heading -3
#### Heading - 4
#### Heading - 5
```

### Accordions

#### The accordion title 1

This guide walks you through installing the Infrastructure Agent (Infra Agent) on a machine deployed through Docker. These instructions can also be found on the Installation page in the Middleware application.

#### The accordion title 2

This is the content of accordion 2.

#### The accordion title 3

This is the content of accordion 2.

#### The accordion title 4

This is the content of accordion 2.

### Dark & Light Theme Images

![Middlewaere logo](/images/image-light.png)
![Middlewaere logo](/images/image-dark.png)

### Code Snippet

```javascript
const express = require("express");
const app = express();
const tracker = require("@middleware.io/node-apm");
```

### Language Dropdown

> **Warning:** Only use dropdowns when there are 2+ options required for your code snippet, because the dropdown formatting takes up unnecessary space otherwise

```javascript
const golange = require("express");
const app = express();
const tracker = require("@middleware.io/node-apm");
```

```typescript
const typescript = require("express");
const app = express();
const tracker = require("@middleware.io/node-apm");
```

### Lists

- Bulleted List
- Item 2

1. Numbered list
2. Numbered list item2

### Simple Text Options

`**Bold**`

`_Italic_`

`[Links](/docs/nodes)`

`> Quotes`

`Inline code`

#### Block Quotes

```plaintext
> Markdown allows you to write using an easy-to-read, easy-to-write plain text
> format, then convert it to structurally valid XHTML (or HTML).
>
> [...]
>
> The overriding design goal for Markdown’s formatting syntax is to
> make it as readable as possible. The idea is that a Markdown-formatted
> document should be publishable as-is, as plain text, without looking
> like it’s been marked up with tags or formatting instructions.
```

#### Listings

```plaintext
*   Wikis should be made up of plain-text files, without requiring a running
    instance of MySQL or even an SQLite database.

*   There should only be one simple-to-write plain-text configuration file.
```

### Table components

| Traces | Metrics | App Logs | Custom Logs | Profiling |
| --- | --- | --- | --- | --- |
| ✖ | ✅ | ✅ | ✖ | ✅ |
| ✅ | ✅ | ✖ | ✅ | ✅ |

### Callouts

> **Note:** #### Info
>
> Middleware Info components Infrastructure Agent (Infra Agent). To install the Infra Agent, see our Installation Guide. Infrastructure Agent (Infra Agent). To install the Infra Agent.

> **Warning:** #### Warning
>
> Middleware Warning components Infrastructure Agent (Infra Agent). To install the Infra Agent, see our Installation Guide. Infrastructure Agent (Infra Agent). To install the Infra Agent.

> **Tip:** #### Success
>
> Middleware Success components Infrastructure Agent (Infra Agent). To install the Infra Agent, see our Installation Guide. Infrastructure Agent (Infra Agent). To install the Infra Agent.

> **Note:** #### Error
>
> Middleware Error components Infrastructure Agent (Infra Agent). To install the Infra Agent, see our Installation Guide. Infrastructure Agent (Infra Agent). To install the Infra Agent.

> **Note:** #### Contact
>
> Middleware Error components Infrastructure Agent (Infra Agent). To install the Infra Agent, see our Installation Guide. Infrastructure Agent (Infra Agent). To install the Infra Agent.

#### Step-by-step

#### 1 Middleware Steps

Middleware Step 1 installation guide. To install the MW Agent, see our installation guide.

#### 2 Middleware Steps

Middleware Step 2 installation guide.

```javascript
const tracker = require('@middleware.io/node-apm');
tracker.track({
    serviceName: "your-service-name",
    accessToken: "<xxxxxxxxxx>"
});
```

#### Tabs

#### Go

Here content for Golang Tabs

#### Node.js

Here content for Node.js Tabs

#### Widgets

- Middleware agent

- Data Ingestion APIs

- OpenTelemetry

- OpenTelemetry

#### Numbered Widget

- Alerts — Setup alerts on Slack, Jira, Gmail, Pagerduty, and more

- Alerts — Setup alerts on Slack, Jira, Gmail, Pagerduty, and more

- Alerts — Setup alerts on Slack, Jira, Gmail, Pagerduty, and more