Markdown formatting guide

This guide covers all Markdown syntax and Docusaurus-specific components used in Midnight documentation. Use this as a reference when writing and formatting content.

Prerequisites

This guide assumes familiarity with basic Markdown. For general Markdown syntax, see the Markdown Guide. This focuses on Docusaurus-specific features and Midnight conventions.

note

For more advanced Docusaurus features, see the official Docusaurus documentation. For general Markdown syntax, refer to the Markdown Guide.

Basic Markdown syntax

Headings

Use ATX-style headings with proper hierarchy:

# Page title (H1) - only one per page
## Major sections (H2)
### Subsections (H3)
#### Details (H4) - use sparingly
##### Rarely used (H5)
###### Almost never used (H6)

• Only one H1 per page (the title)
• Don't skip heading levels
• Use sentence case for all headings
• Keep headings descriptive and scannable

Text formatting

**Bold text** for emphasis and UI elements
*Italic text* for first-time terms or emphasis
`Inline code` for commands, functions, and file names
~~Strikethrough~~ for deprecated content

Examples:

• Click the send button
• Navigate to the settings menu
• Run the npm install command
• This method is deprecated

Links

[Link text](https://example.com)
[Internal link](/develop/tutorial/setup)
[Link with title](https://example.com "Tooltip text")
[Reference link][ref-id]

[ref-id]: https://example.com "Reference definition"

• Use descriptive link text (never "click here")
• Use relative paths for internal links
• Include https:// for external links
• Test all links before publishing

Lists

Unordered lists:

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

Ordered lists:

1. First step
2. Second step
   1. Substep A
   2. Substep B
3. Third step

Task lists:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Code blocks

Inline code:

Use `backticks` for inline code.

Fenced code blocks:

```javascript
const config = {
  network: 'testnet',
  endpoint: 'https://api.midnight.network'
};
```

Code blocks with titles:

```javascript title="config.js"
const midnight = require('@midnight/sdk');
```

Highlighted lines:

```javascript {2,4-6}
const config = {
  network: 'testnet', // highlighted
  endpoint: 'https://api.midnight.network',
  timeout: 5000, // highlighted
  retries: 3, // highlighted
  debug: false // highlighted
};
```

Tables

| Feature | User guide | Builder guide |
|---------|------------|---------------|
| Complexity | Basic | Advanced |
| Time | 10-15 min | 30-45 min |
| Docker | ❌ No | ✅ Yes |

Table formatting tips:

• Use pipes | to separate columns
• Headers are separated by dashes ---
• Align columns for readability
• Use emojis sparingly for visual elements

Blockquotes

> This is a blockquote
> 
> It can span multiple lines
> and include **formatting**.

Use blockquotes for:

• Important quotes from specifications
• Highlighting key concepts
• Callout boxes (though admonitions are preferred)

Components

Admonitions

Docusaurus provides several admonition types:

:::note
General information and context.
:::

:::tip
Helpful hints and best practices.
:::

:::info[]
Additional details and explanations.
:::

:::warning
Important information users must know.
:::

:::caution
Potential issues and common pitfalls.
:::

:::danger
Critical warnings about security or data loss.
:::

Custom titles:

:::tip[Pro tip]
Use custom titles to make admonitions more specific.
:::

:::warning[⚠️ Security alert]
Always verify wallet addresses before sending transactions.
:::

Collapsible admonitions:

:::details Click to expand
This content is hidden by default and can be expanded.
:::

Tabs

Import tabs at the top of your file:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Basic tab usage:

<Tabs>
<TabItem value="user" label="For users">

Content for users goes here.

</TabItem>
<TabItem value="dev" label="For developers">

Content for developers goes here.

</TabItem>
</Tabs>

Advanced tab features:

<Tabs
  defaultValue="mac"
  values={[
    {label: 'macOS', value: 'mac'},
    {label: 'Linux', value: 'linux'},
    {label: 'Windows', value: 'windows'},
  ]}>

<TabItem value="mac">

macOS-specific instructions.

</TabItem>
<TabItem value="linux">

Linux-specific instructions.

</TabItem>
<TabItem value="windows">

Windows-specific instructions.

</TabItem>
</Tabs>

Tab group synchronization:

<Tabs groupId="operating-systems">
<TabItem value="mac" label="macOS">

All tabs with the same groupId will sync across the page.

</TabItem>
</Tabs>

Details and summary

For collapsible content:

Advanced configuration

This content is hidden by default. You can include:

• Lists

• Code blocks

• Any markdown content

  const advancedConfig = {
    // configuration options
  };

Midnight-specific components

Step and Flow components

Import these components for procedural documentation:

import Step from '@site/src/components/Step';
import Flow from '@site/src/components/Flow';

Usage pattern:

<Flow>

<Step>

### Install wallet

**Objective**: Set up your Midnight wallet.

**Actions**:
1. Download Lace wallet
2. Create new wallet
3. Secure your seed phrase

**Verification**: Wallet displays in browser toolbar.

</Step>

<Step>

### Get tokens

**Objective**: Obtain tDUST for testing.

**Actions**:
1. Visit the faucet
2. Enter wallet address  
3. Request tokens

**Verification**: Balance appears in wallet.

</Step>

</Flow>

Code snippets with context

For API documentation and examples:

**Install the SDK:**
```bash
npm install @midnight/sdk

Initialize connection:

import { MidnightSDK } from '@midnight/sdk';

const sdk = new MidnightSDK({
  network: 'testnet',
  proofServerUrl: 'http://localhost:6300'
});

Send transaction:

const result = await sdk.sendTransaction({
  to: 'mn_shield-addr_test1...',
  amount: 10.0,
  privacy: true
});

console.log('Transaction hash:', result.hash);

## Images and media

### Images

```markdown
![Alt text](/img/screenshot.png)
![Alt text with title](/img/diagram.png "Diagram showing network architecture")

Image best practices:

• Store images in /static/img/ directory
• Use descriptive alt text for accessibility
• Optimize images for web (WebP format preferred)
• Include captions for complex diagrams

With captions:

![Lace wallet interface](/img/lace-wallet.png)
*Figure 1: Lace wallet showing transaction history*

Videos

<video controls width="100%">
  <source src="/video/tutorial.mp4" type="video/mp4" />
  Your browser does not support the video tag.
</video>

External embeds

<iframe
  width="560" 
  height="315" 
  src="https://www.youtube.com/embed/VIDEO_ID"
  title="YouTube video player"
  frameBorder="0"
  allowFullScreen>
</iframe>

Advanced formatting

Mermaid diagrams

  ```mermaid
  graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process A]
    B -->|No| D[Process B]
    C --> E[End]
    D --> E

### Custom HTML

When Markdown isn't sufficient:

```html
<div className="custom-container">
  <h3>Custom section</h3>
  <p>Mix HTML with Markdown for special layouts.</p>
</div>

• Use sparingly - prefer Markdown when possible
• Use className instead of class for React compatibility
• Ensure accessibility with proper ARIA labels
• Test across different screen sizes

Metadata and frontmatter

Required frontmatter

---
title: Page title in sentence case
description: Write a description of 120-160 characters
sidebar_label: Navigation label
sidebar_position: 1
tags: [getting-started, development]
slug: /folder-location/file
---

Optional frontmatter

---
# Custom URL (if different from filename)
slug: /custom-url-path

# Hide from sidebar
sidebar_class_name: hidden

# Custom edit URL
custom_edit_url: https://github.com/repo/edit/main/docs/page.md

# Disable edit link
custom_edit_url: null

# Hide table of contents
hide_table_of_contents: true

# Hide title
hide_title: true

---

Import statements

Always place imports after frontmatter:

---
title: Page title
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CustomComponent from '@site/src/components/CustomComponent';

# Page content starts here

Common patterns

API reference entry

## `sendTransaction(options)`

Sends a transaction to the Midnight network with privacy features.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `to` | string | Yes | Recipient wallet address |
| `amount` | number | Yes | Amount in tDUST |
| `privacy` | boolean | No | Enable privacy features (default: true) |

### Returns

Returns a `Promise<TransactionResult>` with the following structure:

```typescript
interface TransactionResult {
  hash: string;
  status: 'pending' | 'confirmed' | 'failed';
  confirmations: number;
}

Example

const result = await sdk.sendTransaction({
  to: 'mn_shield-addr_test1...',
  amount: 25.5,
  privacy: true
});

console.log(`Transaction ${result.hash} is ${result.status}`);

Error handling

try {
  const result = await sdk.sendTransaction(options);
} catch (error) {
  if (error.code === 'INSUFFICIENT_FUNDS') {
    console.error('Not enough tDUST in wallet');
  }
}

Configuration reference

## Configuration options

### Basic configuration

```javascript title="midnight.config.js"
module.exports = {
  network: 'testnet',
  proofServerUrl: 'http://localhost:6300',
  timeout: 30000
};

Advanced configuration

Full configuration options

midnight.config.js

module.exports = {
  // Network settings
  network: 'testnet', // 'testnet' | 'mainnet'
  proofServerUrl: 'http://localhost:6300',
  
  // Connection settings
  timeout: 30000,
  retries: 3,
  retryDelay: 1000,
  
  // Security settings
  validateCertificates: true,
  allowInsecureConnections: false,
  
  // Development settings
  debug: false,
  logLevel: 'info', // 'debug' | 'info' | 'warn' | 'error'
  
  // Custom endpoints
  endpoints: {
    faucet: 'https://faucet.midnight.network',
    explorer: 'https://explorer.midnight.network'
  }
};