Markdown docs

The emi md command describes a module in Markdown. It is the fastest way to get human readable, always up to date documentation for a module: a title, the description, a table of contents, and a section per action listing the method, URL, CLI name and the request/response fields.

Because the Markdown is produced from the same definition that generates your code, the documentation cannot drift out of sync with the actual API.

Generating the markdown

emi md --path module.yaml --output ./out

Without --output, the generated file is printed to the terminal.

Options

Flag	Description
`—path`	Path of the Emi definition file (`.yaml` or `.json`) on disk.
`—output`	Directory the generated markdown is written to. Omit it to print to stdout.
`—tags`	Comma separated compile features to add or remove.

Example

For the postsModule from the OpenAPI page, emi md produces:

# PostsModule

> A small module to manage posts

| | |
|---|---|
| **Name** | `postsModule` |

## Contents

- [Actions](#actions) — 1

## Actions

### `GetSinglePostAction`

> Gets a specific post from the endpoint

| | |
|---|---|
| **Method** | `GET` |
| **URL** | `/posts/:id` |
| **CLI** | `get-single-post` |

#### Response

| Field | Type | Description |
|---|---|---|
| `userId` | `int64` |  |
| `id` | `int64` |  |
| `title` | `string` |  |
| `body` | `string` |  |

This output can be committed next to the module, served in a docs site, or rendered straight into a README.