In-App Add-On Documentation Tip

Hey developers, thought I’d pass along a sweet GitHub feature I just discovered. No doubt you are already taking advantage of ExpressionEngine 3’s in-app documentation feature for your add-ons. And you probably are also using GitHub or Bitbucket to maintain your source code. Both of these fantastic sites render README.md files on the home page of your repository.

If you use the following package structure, then your build/distribution path is clean for end users, and your in-app documentation will be rendered on your repository’s home page, without having to duplicate or keep any files in separate directories in sync.

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)

This lets your users drop your download into their system/users/addons folder without having to figure out what goes where, while keeping your in-app documentation where it belongs. The exception might be if you ship with themes, in which case you might do something like:

Your Repo
├── README.md (symlink to the real README file)
├── system/user/your_addon
│               ├── addon.setup.php
│               ├── mod.your_addon.php
│               ├── mcp.your_addon.php
│               └── README.md (your in-app documentation readme)
└── themes/user/your_addon

In either case, the key is creating the symlink in your project root folder. From your repository’s root folder, use the following command:

ln -s /path/to/the/real/README.md ./README.md

And voilà, beautiful in-app and GitHub/Bitbucket documentation for your add-on, with a user-friendly package structure and no duplication of effort. For full instructions on how to create in-app documentation, see In-App Documentation in the ExpressionEngine user guide.