> For the complete documentation index, see [llms.txt](https://esmp-fun.gitbook.io/plugins/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://esmp-fun.gitbook.io/plugins/markdown-guide/getting-started/your-first-page.md).

# Your first page

A page is a text file in `plugins/MarkdownGuide/pages/`, ending in `.md`. What you write in it is Markdown: plain text with a few marks for headings, bold words and lists, the same as on GitHub, Discord or Reddit.

{% hint style="success" %}
**Rather not touch files?** [Edit in your browser](/plugins/markdown-guide/getting-started/the-web-editor.md) does all of this with buttons, and shows the page as players will see it while you type.
{% endhint %}

## Step 1 - Make the file

Make a new file in the `pages` folder called `03-shops.md`, and put this in it:

```markdown
# Shops

The market at spawn buys and sells at fixed prices.

- Diamonds sell for **25** coins.
- Emeralds sell for **10** coins.

> [!TIP]
> Prices change every month, so check back here first.
```

## Step 2 - Reload and look

Save the file, then in game run:

```
/guide reload
/guide shops
```

Your page opens, and it is in the list on the left with the others.

## Order and names

**The number in front sets the order.** `01-welcome.md` comes before `02-towns.md`, which comes before `03-shops.md`. Use two digits, so `10` comes after `09` and not after `1`.

**The rest is the page's name**, the one players type and links use. The number and the `.md` are dropped, and capitals don't matter:

| File                          | Opened with           |
| ----------------------------- | --------------------- |
| `pages/01-welcome.md`         | `/guide welcome`      |
| `pages/03-shops.md`           | `/guide shops`        |
| `pages/04-mantle/01-zones.md` | `/guide mantle/zones` |

**Folders group pages.** Put a few pages in a folder inside `pages`, and the folder becomes a heading in the page list with its pages under it. A number in front of a folder's name sets its place too.

{% hint style="warning" %}
**Don't name a page after a command word.** A page called `edit`, `reload`, `config`, `settings`, `apply`, `trust`, `widgets` or `menu` can still be opened from links and the page list, but `/guide edit` runs the command instead.
{% endhint %}

## The first heading is the title

The first `#` heading of a page is its title: it is what the page list shows. A page without one is named after its file.

Every `##` heading under it is a section. The sections of the page being read are listed under it in the page list, so long pages are easy to find your way around.

<figure><img src="https://1037515809-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F37kaU8TF94yOlMmCwXdl%2Fuploads%2Fgit-blob-f9894e5b5bbe983f04c6d83f103fa04a97cc7aa8%2Fguide-towns.png?alt=media" alt="A page with two sections listed under it in the page list"><figcaption><p>The Towns page has two sections, listed under it on the left.</p></figcaption></figure>

## Page settings

A page can start with a few settings between two `---` lines:

```markdown
---
icon: nav-shops.png
---
# Shops
```

| Setting      | What it does                                                                                                                                                                                                                                                           |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `icon`       | A picture in front of the page's name in the page list. The PNG goes in the `images` folder.                                                                                                                                                                           |
| `permission` | A permission players need to see the page at all. Without it the page is left out of the page list, the contents, the previous and next buttons and `/guide` tab-completion, and opening it by name says it does not exist. Example: `permission: esmp.staff.trainee`. |
| `controls`   | How [other plugins' settings](/plugins/markdown-guide/writing-pages/settings-on-a-page.md) on the page are drawn: `native` (the default) or `inline`.                                                                                                                  |

## Next

* Everything a page can hold is under **Writing pages**, starting with [text, headings and lists](/plugins/markdown-guide/writing-pages/text.md).
* [Edit in your browser](/plugins/markdown-guide/getting-started/the-web-editor.md) for a live preview.