Getting Started

Starting a Coal project

First, install or build Coal using the instructions below. Next, take a look at examples and read up on the Command-line interface (CLI), Layouts, Pages, and Assets

Coal via release channel (recommended)

By downloading a release binary, you do not need Rust installed. Find Coal for your OS on the releases page here.

Once installed using Operating System specific directions below, use Coal as normal, see CLI for more info.

Linux, Mac

Copy the binary into a directory of your choice, below we copy into /usr/local/bin/.

        sudo cp coal /usr/local/bin/coal
    

Windows

Copy the coal.exe into a folder that is already on the PATH, or add it to a new folder and register that new folder to your PATH.

        sudo cp coal /usr/local/bin/coal
    

Coal via Cargo

Prerequisites

You will need to have Rust 2018+ stable installed, and Cargo (which is probably likely if you have Rust).

Cargo Install

The crate for Coal can be installed via the Cargo interface, and will be installed to ~/.cargo/bin/. If you have Rust installed then this folder is already part of your PATH.

        $ cargo install coal
    

Updating From Cargo

Check your installed coal version like so:

        $ coal --version
    

You can update Coal to a new release with the --force flag.

        # check your coal version like so:
        $ coal --version
        $ cargo install coal --force
    

Compile Coal from source

Prerequisites

You will need to have Rust 2018+ stable installed, we recommend version 1.47.0 or higher, but it should work on any 2018+ version.

Obtain Source

The source code for Coal can be downloaded from the git repo on GitHub.

        $ git clone git@github.com:camsjams/rust-coal.git
    

Running From Source

You can run Coal directly from the project by using cargo run [MODE] [ARGS]. See CLI for more info.

        # Use Coal's local development server
        $ cargo run serve my_source
        # Build your Coal project into static HTML for deployment
        $ cargo run build my_source my_destination
    

Running From Local Binary

You can compile Coal into a binary for use on your machine.

        $ cargo build --release
    

A binary for Coal will be built in target/release/coal.

Copy this binary into a directory of your choice, below we copy into /usr/local/bin/.

        sudo cp target/release/coal /usr/local/bin/coal
    

Use Coal as normal, see CLI for more info.

        # Use Coal's local development server
        $ coal serve my_source
        # Build your Coal project into static HTML for deployment
        $ coal build my_source my_destination