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.
If we look at the folder inside content you will notice two folders.
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 won’t be generating any web pages.
Now let’s 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:
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.
Let’s 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.
Let’s 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 let’s 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.
If you compare this page to the homepage at / you’ll see that it’s missing it’s 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:
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.
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. Read more about Markdown in our
Primer on Markdown.
Following the example above, let’s 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.
Now let’s get fancy and create a new layout. Adding a blob of text to your website won’t cut it for very long. You want designs that require your content to be
placed into wrapping HTML elements and CSS to shape it.
Let’s 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 won’t 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)
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.
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 doesn’t 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.
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.
