In-app Documentation

ExpressionEngine will render beautiful documentation for your add-on directly in the control panel if you follow a few simple guidelines. By including a README.md file in your add-on folder (like you probably already do on GitHub/BitBucket/etc.), and using the following Markdown as a template, your documentation will render nicely, and give your users a consistent experience throughout the control panel. And on its own outside of ExpressionEngine, it is still easy to read, and easy to write.

Tip: If you use GitHub, you can include a symlink at the top level of your repository to display your in-app documentation on your repo’s home page without having to duplicate any files. e.g.

Your Repo
├── your_addon
│   ├── addon.setup.php
│   ├── pi.your_addon.php
│   └── README.md (your in-app documentation readme)
└── README.md (symlink to the real README file)

To create a symlink, use the following command in your root folder: ln -s ./<your_addon>/README.md ./README.md

Add-on Name
├── Requirements (optional)
├── Installation (optional)
├── Usage
│   └── {exp:tag}
│       ├── Example Usage
│       ├── Parameters
│       │   ├── param_name
│       │   └── another_param
│       └── Variables
│           ├── variable_name
│           └── another_var
├── Changelog
│   └── X.Y.Z
├── Disclaimer (optional)
└── License (optional)

# Add-on Name

A description of the add-on. Might include what it's purpose is, sample output, or use-case. The level 1 header is ignored in ExpressionEngine since we already output the Add-on name in the header. This full description however is rendered.

Any level 2 and 3 headers will appear in the side navigation as links. Thus, the structure below should be used. Your `README.md` will be easy to write and consume for GitHub, and look beautiful in ExpressionEngine and meet your users' expectations of a consistent experience throughout the control panel.

## Requirements

Optional, but put here if they exist.

## Installation

Optional, but put here if steps are required beyond copying the files and clicking install in ExpressionEngine

## Usage

Required ## heading, but does not have its own content, it is for the side menu only.

### `{exp:addon:method}`

Tags are level 3 headers under the **Usage** section. Here, describe what the general purpose of the tag is.

#### Example Usage

```
{exp:addon:method}
  Put a typical code example here.
  You can use code fencing or indented code blocks.
  It will be converted to a textarea in ExpressionEngine for each copying and pasting.
{/exp:addon:method}
```

#### Parameters

Describe any parameters this tag has. You should use either a bullet list like:

- `param_name` (required) - This is what this parameter does
- `another_param` - And this one is for such and such

or use level 5 headers like below. The latter should be used if you need more than a brief sentence to describe how to use the parameters. Choose one or the other, do not mix the two styles.

##### param_name (*required*)

Full description of `param_name` here.

##### another_param

Full description of `another_param` here.

#### Variables

Describe any variables this tag has. You should use either a bullet list like:

- `{variable_name}` - The thing
- `{another_variable}` - The other thing

or use level 5 headers like below. The latter should be used if you need more than a brief sentence to describe how to use the variables. Choose one or the other, do not mix the two styles.

##### param_name (*required*)

Full description of `param_name` here.

##### another_param

Full description of `another_param` here.

### `{exp:addon:another_tag}`

Repeat as above for every tag your add-on includes.

## Changelog

### 1.1

- Improved the handling of `param_name` options
- Fixed a bug where this might happen

### 1.0

- Released!

## Disclaimer

Optional, typically only needed when stating independence from trademarked third-party services the add-on might integrate with.

## License

Optional, but you may include a software license here if you don't store a separate file in your repo.