cobalt-bin 0.9.0

Static site generator written in Rust
Documentation

Cobalt

A static site generator written in Rust.

Content

Installation

Using the install script

No prerequisites

$ curl -LSfs https://japaric.github.io/trust/install.sh | sh -s -- --git cobalt-org/cobalt.rs --crate cobalt

You can also manually download all releases here. If your platform is not supported yet, please try installing from source (see below) and file an issue.

Using cargo

Requires Rust

$ cargo install cobalt-bin

Examples

There are a few people already using cobalt. Here is a list of projects and their source code that use cobalt.

Usage

  $ cobalt init myBlog
  $ cobalt build -s myBlog -d path/to/your/destination

See more options with

  $ cobalt -h

Layouts

You can have custom layouts in the _layouts directory.

Layouts will be compiled as liquid templates.

Posts

Posts live in posts by default, but you can use a different directory for posts with the -p flag or by setting the posts variable in your .cobalt.yml.

Example:

extends: posts.liquid

title:   My first Blogpost
date:    01 Jan 2016 21:00:00 +0100
---
Hey there this is my first blogpost and this is super awesome.

My Blog is lorem ipsum like, yes it is..

The content before --- are meta attributes ("front matter") made accessible to the template via their key (see below).

The extends attribute specifies which layout will be used.

The date attribute will be used to sort blog posts (from last to first). date must have the format %dd %Mon %YYYY %HH:%MM:%SS %zzzz, so for example 27 May 2016 21:00:30 +0100.

You can change the order of posts from newest first (default) to oldest first by setting post_order: "asc" in your .cobalt.yml

Drafts

Cobalt supports leaving posts in "draft" state. Drafts will not be rendered unless Cobalt is run with the --drafts flag.

To mark a post as draft you can either set draft: true in your front matter or add it to the drafts folder (_drafts by default). The draft folder location can be specified using the draft key in your .cobalt.yml.

Other files

Any file with the .md or .liquid file extension is considered a liquid template and will be parsed for metadata and compiled using liquid, like a post.

Unlike posts, files outside the posts directory will not be indexed as blog posts and not passed to the index file in the list of contents.

All other files and directories in the source folder will be recursively added to your destination folder.

You can specify different template extensions by setting the template_extensions field in your config file:

template_extensions: ['txt', 'lqd']

Custom paths

Custom paths are much like permalinks in Jekyll, but with a bit more flexibility. You can specify a path attribute in the front matter of any document to give it a custom path. The path is always relative to the document root, independent of where the file is located.

Example:

extends: posts.liquid

title:   My first Blogpost
path: /some/other/path/

would result in a file with the url your-website.com/some/other/path/index.html.

You can also set a global attribute post_path in your .cobalt.yml that will be used for all posts.

Any attribute in the front matter can be interpolated into the path. If you set a date attribute you have access to several other custom attributes. See the Jekyll documentation.

More examples:

date: 01 Jan 2016 21:00:00 +0100
path: /:year/:month/:day/thing.html

/2016/01/01/thing.html

date: 01 Jan 2016 21:00:00 +0100
author: johann
path: /:author/:year/:month/:day/title

/johann/2016/01/01/title/index.html

You can use :slug to include a slugified version of the title in the path. E.g. using post_path in .cobalt.yml:

post_path: /post/:slug

/post/dashed-version-of-title/index.html
/post/another-post-title/index.html

Attributes

All template files have access to a set of attributes.

In example above title is accessible via {{ title }} and date via {{ date }}, for the layout template as well as the post template.

Special Attributes

content

{{ content }} is accessible only to layouts and contains the compiled text below the --- block of the post.

posts

{{ posts }} is a list of the attributes of all templates in the posts directory. Example usage on a page listing all blog posts:

{% for post in posts %}
 <a href="{{post.path}}">{{ post.title }}</a>
{% endfor %}

RSS

To generate an RSS file from the metadata of your posts, you need to provide the following data in your config file:

# path where the RSS file should be generated
rss: rss.xml
name: My blog!
description: Blog description
link: http://example.com

None of these fields are optional, as by the RSS 2.0 spec.

Make sure to also provide the fields title, date and description in the front matter of your posts.

Syntax Highlighting

This feature is currently experimental and causes installation to fail on Windows. To enable syntax highlighting, you need to install Cobalt using cargo like this:

cargo install cobalt-bin --features="syntax-highlight"

If you annotate your Markdown code blocks, Cobalt will automatically highlight source code using Syntect.

Import

To import your site to your gh-pages branch you can either pass a build --import flag when you build the site or after you have build the site with build you can run import. There are also some flags that can be found via import --help.

Deployment

With Travis CI

You can easily deploy a cobalt site to gh-pages! To do this with travis is also very easy. You will need to have rust available on travis. In your travis.yml you will need to have something similar to this:

sudo: false
language: rust

before_script:
  - cargo install cobalt-bin
  - export PATH="$PATH:/home/travis/.cargo/bin"

script:
  - cobalt build

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GH_TOKEN
  local_dir: build
  on:
    branch: master

For the GH_TOKEN you will need to create a personal access token, which can be found here, then you will need to use the travis cli tool to encrypt your personal access token. You can do this like so travis encrypt GH_TOKEN=... --add env.global(make sure to include the public_repo scope).

With GitLab CI

You can also deploy a cobalt site to GitLab Pages using GitLab CI. GitLab CI uses Docker, you can use nott/cobalt or any other image with cobalt in PATH.

An example of .gitlab-ci.yml:

image: nott/cobalt:latest

pages:
  script:
  - mkdir -p public
  - cobalt build -d public
  artifacts:
    paths:
    - public/
  only:
  - master