Cobalt::Docs::Configuration

Config File

_cobalt.yml let's you specify site-wide options as well as defaults for pages.

Default `_cobalt.yml`:

# Build options
source: "."
template_extensions:
  - md
  - liquid
include_drafts: false
ignore:
destination: _site

# Site options
site:
  title: ~
  description: ~
  base_url: ~
  sitemap: ~
  data: ~

# Page/Post options
default:
  excerpt_separator: "\n\n"
  is_draft: false
syntax_highlight:
  theme: "base16-ocean.dark"
  enabled: true
assets:
  sass:
    style: Nested
pages:
  default: {}
posts:
  title: ~
  description: ~
  dir: posts
  drafts_dir: _drafts
  order: Desc
  rss: ~
  jsonfeed: ~
  publish_date_in_filename: true
  default: {}

Build options

Setting	Format	Description
`source`	String	Directory, relative to `_cobalt.yml`, where content lives.
`template_extensions`	List of Strings	File extensions that mark a file as a page as compared to an asset.
`include_drafts`	Boolean	Specifies whether posts marked `is_draft` should be generated by default. This can be overridden with command line flags.
`ignore`	List of Strings	Specifies what files should be ignored by Cobalt by way gitignore patterns, relative to `source`.
`destination`	String	Directory, relative to `_cobalt.yml`, where the output is written to.

For example to unignore the .well-known/ folder used in LetsEncrypt, add this to your _cobalt.yml.

ignore:
  - "!.well-known"
  - "!.well-known/**/*"

Site options

These are all under site: in the yaml:

Setting	Format	Description
`title`	String	The title for the site
`description`	String	A description for the site
`base_url`	String	The root for the site. This is used in making paths absolute for RSS as well as in Liquid (`{{ site.base_url }}/docs`).
`sitemap`	String	Relative path for where to generate a sitemap XML file.
`data`	Object	Values made available via the `{{ site.data }}` variable.

In addition to changing the defaults through CLI arguments/flags, Cobalt allows to specify a config file (default: _cobalt.yml) where you can store such settings.

Pages and Posts

Global options:

Setting	Format	Description
`default`	Frontmatter	Site-wide defaults for page frontmatters.
`syntax_highlight`		Site-wide syntax highlighting settings
`- theme`	String	Site-wide syntax highlighting theme. Run `cobalt debug highlight themes` for list of available themes
`- enabled`	Boolean	Enables or disables site-wide syntax highlighting

These are under pages: in the yaml:

Setting	Format	Description
`default`	Frontmatter	Defaults for page frontmatters.

These are under posts: in the yaml:

Setting	Format	Description
`title`	String	Title for the posts collection. Falls back to `site.title` if not present.
`description`	String	Description for the posts collection. Falls back to `site.description` if not present.
`dir`	String	Directory, relative to `source`, where posts lives.
`drafts_dir`	Boolean	Directory, relative to `source`, where draft posts can live.
`order`	`Asc`, `Desc`	Sort order for `{{posts}}` variable.
`rss`	String	Path for a posts RSS file.
`jsonfeed`	String	Path for a posts jsonfeed file.
`default`	Frontmatter	Defaults for post frontmatters.
`publish_date_in_filename`	Boolean	Prepend `YYYY-MM-DD-` to filename on `publish`

These are under assets: in the yaml:

Setting	Format	Description
`sass`		Sass' CSS generation settings
`- style`	`Nested`, `Expanded`, `Compact`, `Compressed`	Site-wide format style for Sass-generated CSS.

Config File

Default _cobalt.yml:

Build options

Site options

Pages and Posts

Default `_cobalt.yml`: