NOTE: This manual is a work in progress. Please let us know if you think something is missing by filing an issue, or join our Discord server.

Contributing to the Manual

Thanks for contributing to the 📙 Caramel Manual!

We'd love this manual to be useful, inclusive, and friendly, so make sure your tone matches this.

The manual sources live in <root>/manual/src, and it is written in Markdown. It is published automatically once a PR is merged, so you don't have to worry about that.

Topics

Manual Structure

The structure of the manual is reflected in the SUMMARY.md file, so that the links that go under the same heading are within the same folder.

Here you can see that everything under the "Getting Started" section is under the ./getting_started folder.

# Summary

- [Introduction](./introduction.md)
- [Getting Started](./getting-started/index.md)
  - [Installation](./getting-started/installation.md)
  - [First Steps](./getting-started/first-steps.md)
- [CHANGELOG]()
  - [v0.1.1](./changelog/v0.1.1.md)
  - [v0.1.0](./changelog/v0.1.0.md)
  - [v0.0.14 and older](./changelog/v0.0.14.md)

--------------------------------------------------------------------------------

- [Guides]()
  - [Syntax Cheatsheet](./guides/syntax-cheatsheet.md)
  - [Using Caramel with Rebar3]()
  - [Using Caramel with Mix]()
  - [Calling Erlang code](./guides/erlang-ffi.md)
  - [Calling Elixir code]()
- [Examples]()
  - [Hello, Joe!](./examples/hello-joe.md)
  - [Simple HTTP Echo Server](./examples/simple-http-echo-server.md)

--------------------------------------------------------------------------------

- [Reference](./reference/index.md)
  - [Caramel CLI](./reference/cli/default.md)
    - [`caramel compile`](./reference/cli/compile.md)
    - [`caramel fmt`](./reference/cli/fmt.md)
    - [`caramel sort-deps`](./reference/cli/sort-deps.md)
    - [`caramel version`](./reference/cli/version.md)
  - [Language Features]()
  - [Standard Library]()
    - [`Binary`]()
    - [`Calendar`]()
    - [`Erlang`]()
    - [`Ets`]()
    - [`Io`]()
    - [`Lists`]()
    - [`Maps`]()
    - [`Process`]()
    - [`Timer`]()
  - [Typed OTP]()

--------------------------------------------------------------------------------

- [Contributing]()
  - [Contributing to the Manual](./contrib/manual.md)
  - [Building from Source](./contrib/building.md)
  - [Architecture](./contrib/architecture.md)

Editing Existing Pages

If you find a typo in some page, you can look into the SUMMARY.md to see which markdown file to modify.

You can edit the markdown files with any editor you choose, and submit a Pull Request.

Try to stick to 80 characters per line or less.

Adding New Pages

Start the server (see Previewing Your Changes) and add a new page in SUMMARY.md.

Once you save it, the server will have created the right folders and files for you.

Now you can edit the new empty Markdown files as if they were pre-existing pages.

If you want help writing a section, please draft your ideas and open a Draft Pull Request so we can work on it together.

Previewing Your Changes Locally

If you want to work on the manual locally, you will need to install mdbook.

mdbook comes with a built in server with hot-reloading. This lets you see the results automatically in the browser.

Start the server with mdbook serve and open the URL it lists. If your port 3000 is already taken, you can call mdbook serve -p PORT to use a different one.