Getting started with

Install NodeJS & npm

You must install NodeJS to start with

On Mac with Homebrew

brew install node

npm will be also installed with the previous command.

On Ubuntu

sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs
sudo apt-get install npm

Others alternatives

Others ways to install node.js can be found here : Don't forget to install npm :


npm install -g

Create a new web site

Create a new directory and initialize the project structure :

mkdir my-webiste
cd my-website
cocoons create

By default, a project will have the following directories & files :

  • src : the artifacts of the site : content (html or markdown), images, css, ...
  • target : the generated site will be in this folder.
  • templates : the templates used to transform markdown file into HTML.
  • widgets : widgets are reusable chunks of HTML that can be inserted inside the main content of the page or somewhere else in the template (eg. a sidebar, on the top of the page, ...)
  • logs : log files used for the preview mode & during the site generation process.
  • There is also a cocoons.json file which contains the site parameters.

The command cocooons create will use a default site template called "basic". A site template is a specific site structure which contains specific widgets & templates. It is also contains demo content to show you what you can do with this site structure.

We are building others site templates. Right now, you can use the following site structures :

  • basic : it contains the general widgets and 2 templates : one with a sidebar on the right and another one without sidebar.
  • onepage : it can be used for one page sites.
  • cocoon-site : this is the site structure used for our site

If you can to create a new site based on another structure template, you can used the following command :

cocoons create [site-template-name]
eg. :
cocoons create onepage

Others site structures will be available later.

Review cocoons.json

On each project root folder, you have to add a cocoons.json file. This file is added with the command 'cocoons create'. It contains information on the project and other technical parameters.

This json object is also passed to the template engine. You are free to add more parameters or remove some of them that will not be used in the templates.

Add your content into the source folder

The web site content is in the src folder.

The usual web content

You can add all kind of content you want (HTML, pdf, images, ...). You can also create subdirectories inside the src folder. In this case, the url matches to the different directories (if defined) & the name of the file.

Markdown file

You can also add markdown files which is a very simple solution to use for a content oriented web site. In this case, you have to create 2 different files :

  • a .md file which match to the name of the page.
  • a .json file which contains the SEO meta info & other properties. This file will passed to the template engine. You can add all properties you want.

If you create your website with the command "cocoons create", see the files : & markdown.json as example.

In the preview mode (see below) and after generating the web site, you can access to this page with the url : markdown.html.

If you need more info on markdown format, please visit this page.


By default, is using Jade and Bootstrap for the templates. This is mainly used to transform markdown content into HTML. The templates are located in the folder templates.

Each template can access to 3 different objects:

  • page which contains the page properties defined in its json file (eg. :
  • config which contains the properties defined in the cocoons.json
  • widget (only for a widget template), by using this object, you can access to its properties as specified in the cocoons.json file.

You can use any kind of template engine that is supported by Express. In this case, you have to change the property templateEngine into the file cocoons.json (in theory, not yet tested ;-) )

Menus can be defined in the file. This is a usual json structure send to the template via the config object (see above). By default, there is only one main menu but it should be possible to add other menus in the file.

The menu management will maybe change in the upcoming months.


Template widgets

A widget is a chunk of HTML code that can be inserted into a template region like a sidebar or before the main content. This is useful to include ads or generic info like a list of links on all pages. This can be also used to insert scripts into the pages like the Google Analytics script.

This is quite similar to the widget concept in Wordpress.

Using widgets with is quite simple. It require the following steps :

  • Create a template for the widget into the folder widget. It could be HTML code or a jade template. There are some examples in the default web site.
  • Specify in which region you want to display the widget. This can be done in the file. If you create a new web site with the command create, you will have a default config in the file

Markdown content widgets

Markdown are very nice to produce content quickly thanks to its content tags. Unfortunately, this is not very useful to specify the content of complex widgets like a slideshow, a call to action box, ...

In, it is possible to insert widgets into a markdown content by using simple tags.

For exemple, if you write the following code into your markdown page :

{ "name" : "call2action-large.jade",
  "properties" : {
    "title" : "This is a call to action ! ",
    "text" : "You can add additional info here",
    "link" : {
      "href": "",
      "anchor" : "Click me !"

You will get on this page a call to action widget composed of a title, a text & a link within an action button.

Run the preview mode

The preview mode is useful when you have many changes to do (templates, content, ...) before generating the complete web site.

You can start the preview mode with the following command line :

cocoons preview

Now, from your browser, you can access to the site with the url :


You can change the port number in the cocoons.json file.

If you want, you can use nodemon with cocoons quickly :

nodemon --exec cocoons preview -e js,jade,json

This can help if you made a lot of modification on the widget jade templates and in the cocoons.json file.

Generate the site

When the content has been published into the project structure, you can generate the complete web site with the command line :

cocoons generate

The complete web site will be present in the folder target. You can change the target folder in the cocoons.json file.

Deploy the site

The cocoons.json can contain the following parameters to deploy the site with FTP.

  "ftp" : {
    "host"                : "hostname",
    "port"                : 21,
    "user"                : "username",
    "password"            : "password",
    "folder"              : "folder", // Not mandatory
    "deleteExistingfiles" : true

Now, you can deploy the site with the following command :

cocoons ftp

That's all for a first introduction !

Please, tell us what you like or not ! Thanks for reading !