Middleware Docs Style Guide and Guidelines

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:

  1npm install @middleware.io/node-apm --save

  1const 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:

  1## Prerequisites
  21. **Node.js version 18.17.1+**: Verify with `node --version`
  32. **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

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:

1tracker.track({
2    serviceName: "your-service-name",
3    accountKey:"<MW_API_KEY>",
4    target:"https://<MW_UID>.middleware.io:443",
5});

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

1MW_API_KEY="<MW_API_KEY>" 
2MW_TARGET=https://<MW_UID>.middleware.io:443

1MW_API_KEY="<MW_API_KEY>" MW_TARGET=https://<MW_UID>.middleware.io:443 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:

Metrics Collected

Use a simple table with Metric name and Description columns:

Object Reference

Adding images

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

1{% 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

1{% 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

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

Accordions

Dark & Light Theme Images

Code Snippet

1const express = require("express");
2const app = express();
3const tracker = require("@middleware.io/node-apm");

Language Dropdown

index.js

JavaScript

1const golange = require("express");
2const app = express();
3const 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

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

Listings

1*   Wikis should be made up of plain-text files, without requiring a running
2    instance of MySQL or even an SQLite database.
3
4*   There should only be one simple-to-write plain-text configuration file.

Table components

Callouts

Step-by-step

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

Tabs

Widgets

Middleware agent

Data Ingestion APIs

OpenTelemetry

OpenTelemetry

Numbered Widget