How to Write Documentation

Learn how to create beautiful, well-structured documentation with Markdown syntax, special callouts, and file organization.

File Naming Conventions

File names are automatically transformed for display:

Transformation Rules:

Underscores (_) → Spaces
PascalCase → Separated words
File extensions are removed

Examples:

Getting_Started.md→Getting Started

API_Reference.md→API Reference

Widget_Components.md→Widget Components

MyAwesomeFeature.md→My Awesome Feature

Best Practice

Use underscores or PascalCase for multi-word file names. Avoid spaces in actual file names.

Markdown Syntax

Learn how to use Markdown syntax to create beautiful documentation:

Headings

# Heading 1
## Heading 2
### Heading 3

Text Formatting

**Bold text**
*Italic text*
~~Strikethrough~~
`Inline code`

Lists

Unordered:

- Item 1
- Item 2
  - Nested item
- Item 3

Ordered:

1. First item
2. Second item
3. Third item

Code Blocks

Use triple backticks with language specification:

```javascript
function hello() {
  console.log("Hello World!");
}
```

Links & Images

[Link text](./Other_File.md)
[External link](https://example.com)
![Image alt text](./images/photo.png)

Special Callouts

Use styled callout boxes to highlight important information:

Callout Syntax

/// TYPE | Optional Title
Your content here. You can use **markdown** inside!
///

Tip / Success

Pro Tip

Use this for helpful tips, best practices, or success messages.

/// tip | Pro Tip
Content here...
///

Aliases: tip, success, best practice

Info / Note

Good to Know

Use this for general information, notes, or additional context.

/// info | Good to Know
Content here...
///

Aliases: info, note

Warning

Be Careful

Use this to warn users about potential issues or important considerations.

/// warning | Be Careful
Content here...
///

Aliases: warning

Danger / Error

Critical

Use this for critical errors, bugs, or dangerous operations.

/// danger | Critical
Content here...
///

Aliases: danger, error, bug

Uploading Documentation

Single File Upload

For simple documentation without images

Single Markdown File

For simple documentation without images:

Click "Upload Documentation"
Select Type: Markdown
Upload a single .md file
Fill in metadata (title, description, tags, etc.)
Click "Upload"

ZIP Archive Upload

For documentation with multiple files and images

Example Structure:

documentation.zip
├── Introduction.md          ← Entry point
├── Getting_Started.md
├── Advanced_Topics.md
├── images/
│   ├── screenshot1.png
│   ├── diagram.jpg
│   └── logo.svg
└── examples/
    ├── Example_1.md
    └── Example_2.md

Entry Point

The first .md file alphabetically will be the entry point. Name it Introduction.md or Index.md to control which file is shown first.

Creating a ZIP:

Windows: Select files → Right-click → Send to → Compressed (zipped) folder

macOS: Select files → Right-click → Compress Items

Linux: zip -r documentation.zip .

Important

Make sure to include all referenced images in the ZIP. Relative paths in Markdown must match the folder structure in the ZIP.

Pull Requests

Propose changes to documentation you don't own

Open the documentation you want to improve
Click "Propose Changes" (visible to VERIFIED_DEV and ADMIN users)
Choose Single File or ZIP Archive
For single file: select which existing file to modify or create a new one
Fill in the PR title and description
Submit for review

PR Review

The documentation owner will review your changes and can approve or reject them. Once approved, your changes are automatically merged.

Best Practices

Follow these guidelines to create beautiful documentation

Structure

Start with an introduction or overview
Use clear, descriptive headings
Keep paragraphs concise
Use lists for step-by-step instructions

Writing Style

Use active voice
Be clear and concise
Provide examples for complex concepts
Use callouts to highlight important information
Include code samples when relevant

Images

Optimize images for web (compress large files)
Use descriptive file names: login-screen.png not img001.png
Always include alt text for accessibility
Store all images in an images/ folder

You're Ready!

You now have everything you need to create beautiful, well-structured documentation.Start uploading now