Legacy Documentation
You are using the documentation for version 3.5.17. Go here for the latest version or check here for your available upgrades to the latest version.
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
Markdown File Structure¶
The basic structure is:
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)
Documentation Template¶
The template below demonstrates sections to include, the order to include them, and the meaning behind each header level.
# 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.