The Multipage Template

The Multipage template is designed for creating an Idyll blog with multiple posts. It can be used with any static hosting service, and is pre-configured to organize output for easy use with github pages.

While the syntax used when editing a page in a multipage Idyll blog is the same as when editing a single-page article, the directory layout and usage of templates for sub-pages is different, this guide is provided to help you get started with the multipage template and some of the key differences between it and the single-page templates.

Quick Start

To create your multipage template, use the command idyll create and select the Multipage template when prompted.

Using your multipage post:

• To run the main page, use the idyll command in this directory.
• To create a new page, cd posts to navigate to the posts directory, then use idyll create --template ../template --no-install to create a new post.
• To run a sub-page, cd posts/name-of-page to navigate to that page's directory, then use idyll.
• Any pages that have been built will go to the docs directory (found within the top level of the multipage post).

Project Overview

Below is an overview of each directory generated within a multipage project.

• posts - all of the available posts, each directory within contains a full idyll post
• components - shared components, can be used by any post. Each post also has its own components folder where you can put components that don't need to be shared.
• template - the post template to use when you run idyll create. Update this template with site specific styles, configuration, etc.
• index.idyll - the root/index page for the blog. Note this is not autogenerated.
• docs - the folder where the output is built. Deploy to any static hosting service (we name it docs so its easy to host on github pages).

Creating a Post

Navigate to the posts directory and run idyll create --template ../template/ --no-install. Alternatively, use idyll create, select Custom for the template when prompted, and provide the path ../template/.

Using the idyll create command without one of the other templates will work, but the above will automatically follow the default structure of the multipage post, while the other preset templates will not. If you do choose to use another template, your build files will go to posts/name-of-post/build/ instead of docs/name-of-post/.

To change the output location, change the output option in package.json in the template directory (if using the provided template) and at the root of this project (and any existing posts!).

Building a post for production

Navigate to the post's directory and run idyll build. The output will appear in the top-level docs folder. To change the output location, change the output option in package.json in the template directory and at the root of this project (and any existing posts!). (This assumes that you are using the template provided for multipage blogs.)

Deploying

Make sure all of your posts have been built, then deploy the docs folder via any static hosting service. Please note that, currently, idyll publish does not work with multi-page projects.

Known limitations

• Note that idyll.pub (used by the idyll publish command) does not yet support multi-page projects, so it is up to you host the output online.
• The index page needs to be updated manually, it is not yet autogenerated based on the posts directory.