Cuttlebelle workerThe Cuttlebelle mascot with a hard hat on ready to work
#Edit this partial

Getting started

To start using Cuttlebelle make sure you got NodeJs installed.

Install Cuttlebelle so that the cuttlebelle command is available to you globally.

npm install cuttlebelle -g

Run the init command now to get you started with a bunch of files and a minimum layout.

💡 Make sure you run this in an empty folder

cuttlebelle init

This command will create the below files and compile them for you into the site folder.

.
├── assets
│   └── css
│       └── site.css
├── code
│   ├── page.js
│   └── partial.js
├── content
│   ├── _shared
│   │   ├── footer.md
│   │   └── header.md
│   └── index
│       ├── body.md
│       └── index.yml
└── site
    ├── assets
    │   └── css
    │       └── site.css
    └── index.html

9 directories, 9 files

Now running the watch command will open the browser for you and show you what you got so far.

cuttlebelle watch

The address the server will listen on starts at http://localhost:8080/ and increase its port number depending on what ports are available on your machine. So the address you put in your browser could be http://localhost:8081/ or http://localhost:8085/ etc.

A screenshot of a browser showing an almost empty star page that welcomes you to your new Cuttlebelle site

#Edit this partial

Create a new page

Each folder inside the content folder with an index.yml file represents a web page. Inside those folders you keep what Cuttlebelle call partials. Each partial has a part of the content of your page. It is all glued together by the index.yml file. This file lists all the partials in the order you want them to appear on the page.

An animation of how partials add content blocks to your browser

If we look at the folder inside content you will notice two folders.

.
├── _shared
│   ├── footer.md
│   └── header.md
└── index
    ├── body.md
    └── index.yml

The index folder is special. It represents the root of your website. It will compile to yourwebsite.com/. Note that the _shared folder does not have an index.yml file. That means this folder wont be generating any web pages.

Now lets add a new page. Create a folder inside content called page1. Inside there add a file called index.yml. Your folder structure should now look like this:

├── assets
│   └── css
│       └── site.css
├── code
│   ├── page.js
│   └── partial.js
├── content
│   ├── _shared
│   │   ├── footer.md
│   │   └── header.md
│   ├── index
│   │   ├── body.md
│   │   └── index.yml
│   └── page1           # <-- Our new folder
│       └── index.yml
└── site
    ├── assets
    │   └── css
    │       └── site.css
    └── index.html

10 directories, 10 files

Inside the index.yml copy / paste the below content.

title: Page 1

main:
  - Hello world

Now in your browser append /page1 to your URL. You should now see the new site.

A screenshot of a browser showing the new page with the hello world phrase

Lets have a look at this index.yml file again.

The title: Homepage is just the title of this page. It should be visible in the header of your browser.

The - Hello world bit is the main body part of this page. It should just read Hello world in the browser. But Hello world is not really a lot of content nor is it particular helpful. Lets imagine we want to add a whole sentence or even a paragraph here. Adding all that content into the index.yml will be hard to follow so lets create our first partial.

Create a new file called body.md inside the page1/ folder and put some paragraphs inside of it. See example below. (An excerpt from the 1870 novel Twenty Thousand Leagues Under the Sea by Jules Verne)

The year 1866 was signalised by a remarkable incident, a mysterious and puzzling
phenomenon, which doubtless no one has yet forgotten. Not to mention rumours
which agitated the maritime population and excited the public mind, even in the
interior of continents, seafaring men were particularly excited. Merchants,
common sailors, captains of vessels, skippers, both of Europe and America, naval
officers of all countries, and the Governments of several States on the two
continents, were deeply interested in the matter.

For some time past vessels had been met by "an enormous thing," a long object,
spindle-shaped, occasionally phosphorescent, and infinitely larger and more
rapid in its movements than a whale.

And now replace your Hello world string inside the page1/index.yml with body.md so that it looks like this:

title: Page 1

main:
  - body.md

Your browser should refresh automatically and you see the new content.

A screenshot of a browser showing the new page with the new content

If you compare this page to the homepage at / youll see that its missing its header and footer. We can fix that the same way we added the body partial. Edit your page1/index.yml so that it looks like the code below:

title: Page 1

header:
  - /_shared/header.md

main:
  - body.md

footer:
  - /_shared/footer.md

You can easily share partials between pages by pointing to them via a path. If you start the path with a slash / it will be resolved relative to the root of your content folder. So a path like /_shared/header.md regardless whether it is added inside the page1/index.yml or the page1/subpage/subsubpage/index.yml will always point to content/_shared/header.md.

Upon saving the index.yml file you should see the header and footer in your new page.

Youve done it. You created a new page.

#Edit this partial

What is markdown

Cuttlebelle comes with a markdown engine. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid HTML.

Following the example above, lets add a line below the text that highlights where this text came from.

The year 1866 was signalised by a remarkable incident, a mysterious and puzzling
phenomenon, which doubtless no one has yet forgotten. Not to mention rumours
which agitated the maritime population and excited the public mind, even in the
interior of continents, seafaring men were particularly excited. Merchants,
common sailors, captains of vessels, skippers, both of Europe and America, naval
officers of all countries, and the Governments of several States on the two
continents, were deeply interested in the matter.

For some time past vessels had been met by "an enormous thing," a long object,
spindle-shaped, occasionally phosphorescent, and infinitely larger and more
rapid in its movements than a whale.

Excerpt from *Twenty Thousand Leagues Under the Sea* by **Jules Verne**

Here we added formatting to Twenty Thousand Leagues Under the Sea by making it italic and Jules Verne by making it bold.

Have a look at all the markdown options in our cheat-sheet.

#Edit this partial

Create a new layout

Now lets get fancy and create a new layout. Adding a blob of text to your website wont cut it for very long. You want designs that require your content to be placed into wrapping HTML elements and CSS to shape it.

Lets create a new file inside the code/ folder called book.js with below content.

import React, { Fragment } from 'react';
import PropTypes from 'prop-types';

/**
 * Our new book component
 */
const Book = ({ _body }) => (
  <Fragment>{ _body }</Fragment>
);

export default Book;

Now give our content/page1/body.md file this layout by adding below top to the file so that it looks like this:

---
layout: book
---

The year 1866 was signalised by a remarkable incident, a mysterious and puzzling
phenomenon, which doubtless no one has yet forgotten. Not to mention rumours
which agitated the maritime population and excited the public mind, even in the
interior of continents, seafaring men were particularly excited. Merchants,
common sailors, captains of vessels, skippers, both of Europe and America, naval
officers of all countries, and the Governments of several States on the two
continents, were deeply interested in the matter.

For some time past vessels had been met by "an enormous thing," a long object,
spindle-shaped, occasionally phosphorescent, and infinitely larger and more
rapid in its movements than a whale.

Excerpt from *Twenty Thousand Leagues Under the Sea* by **Jules Verne**

Saving both files wont change much in the browser. But now we can add some special information to this content file that the layout file can digest.

---
layout: book
book: Twenty Thousand Leagues Under the Sea
image: https://goo.gl/KResEh
alt: The cover of the book "Twenty Thousand Leagues Under the Sea"
link: https://en.wikipedia.org/wiki/Twenty_Thousand_Leagues_Under_the_Sea
---

The year 1866 was signalised by a remarkable incident, a mysterious and puzzling
phenomenon, which doubtless no one has yet forgotten. Not to mention rumours
which agitated the maritime population and excited the public mind, even in the
interior of continents, seafaring men were particularly excited. Merchants,
common sailors, captains of vessels, skippers, both of Europe and America, naval
officers of all countries, and the Governments of several States on the two
continents, were deeply interested in the matter.

For some time past vessels had been met by "an enormous thing," a long object,
spindle-shaped, occasionally phosphorescent, and infinitely larger and more
rapid in its movements than a whale.

Excerpt from *Twenty Thousand Leagues Under the Sea* by **Jules Verne**

Those variables we just added are now available in our layout via react props:

import React, { Fragment } from 'react';
import PropTypes from 'prop-types';

/**
 * Our new book component
 */
const Book = ({ _body, book, image, alt, link }) => (
  <article className="partial" style={{ overflow: 'hidden' }}>
    <img src={ image } alt={ alt } style={{ float: 'left', width: '30%' }} />
    <div style={{ float: 'left', width: '68%', margin: '0 0 0 2%' }}>
      { _body }
      <a href={ link } style={{ fontWeight: 'bold', fontSize: '1.3rem' }}>
        Read about { book }
      </a>
    </div>
  </article>
);

export default Book;

(I personally would use a proper CSS file here but that is out of scope for this quick basics intro)

A screenshot of a browser showing the new layout with the image on the left

#Edit this partial

What is frontmatter

With front-matter we can add more complex data to our content than just blobs of text. Front-matter has to be on the top of the file and begins and ends with three dashes ---. Front-matter is completely optional and each content partial has layout: partial as the default variable. You can overwrite that of course. index.yml files have layout: page as the default variable.

---
# this is YAML front matter
variable: one
array:
  - one thing
  - two things
  - several things
# all of this data is available to our layout
---

This is _markdown_.
Even with dashes inside of it

---

Still **markdown** :)

💡 Make sure you save your files in utf-8 encoding.

You can get really tricky and smart here as YAML supports many different forms of data. Read more what YAML can do in our cheat-sheet.

#Edit this partial

Using the double save

Cuttlebelle's watch tries hard to only render what you changed. But that can sometimes fail and it does less work than required. If you ever change something and it doesnt appear in your browser, chances are Cuttlebelle was a bit over-eager to save time. For those cases you have the double-save. If you save your document or your layout twice in a row, just like a double click, Cuttlebelle will render all pages for you again.

A screenshot of the watch showing that at first generating all pages took 10s but subsequent saves took only 0.009s

Note from the screenshot above the time it took to generate all pages (~10s) vs the time it took to save only one (~0.009s).

This can be really handy when adding content and developing layouts while keeping the default render time as low as possible.