Create a Help File

All commands need a help file. It’s useful to make the helpfile first because it lets you think about what the commands are actually supposed to do before you code them.

Create the Help File

Create a file in aresmush/plugins/custom/help/en named goals.md. The directory probably won’t exist at first, so you’ll need to create it by using mkdir. Give the file the following text:

---
toc: Character Creation
summary: Setting goals.
---
# Goals
This command lets you record your character's goals.  Goals are only visible to yourself and staff, and may be changed at any time.

`goals` - Show you own goals.
`goals/set <goals>` - Sets your goals.

Characters with the "view_bgs" permission can view goals using `goals <name>`.

Type load custom in game to reload the custom plugin and register the new help file.

Type help goals to view the help file.

About Help Files

Now let’s look at this file in detail.

Help File Location

Help files live in a help\<language code> folder under each plugin’s folder. This supports having help files in multiple languages, based on the game’s locale. “en” is the language code for English.

The name of the help file will be the topic name. For instance, if we name the file goals.md then you can type help goals.

Help File Metadata

The first few lines of the help file define important metadata used by the help system. There are many help fields available (you can find a complete list in the Advanced Tutorial on Help Files later), but only two are required:

  • toc - Defines where the topic falls in the help table of contents.
  • summary - The summary text that shows up next to the topic in the help table of contents.

The metadata is in YAML format, which is a simple markup language using a field: value format.

Help File Contents

After the metadata (which is set off by --- lines) comes the actual help text. Like a lot of Ares text, this uses Markdown format. Markdown is nice because it can be shown in both text-only format (for the MU client) and web format (for the web portal). If you’ve ever used web forum or wiki formatting codes, you’ve probably used Markdown.

This article is part of the Adding a Command tutorial.