File and Directory Structure

While building your website’s theme, you’ll be working with a standardized set of files and folders. Learn what each piece is for and how to best organize everything.

Default file and folder structure

Create a folder in which to store your new Live Editor theme. Then run this command within that folder using Live Editor CLI to generate a new skeleton theme:

liveeditor new my_theme

You will then see this file and folder structure within a new subfolder called my_theme:

• my_theme
  • assets
    • css
      • site.css
    • fonts
    • images
    • js
      • init.js
      • site.js
  • content_templates
  • layouts
    • site_layout.liquid
    • layouts.json
  • navigation
    • global_navigation.liquid
    • navigation.json
  • partials
  • .gitignore
  • README.md
  • config.json.sample
  • theme.json

There are 2 main types of files that you’ll be working with within the theme:

JSON configuration files

All configurations of the theme and its various elements are done within .json files containing settings in JSON format.

Liquid template files

Presentation code is authored within .liquid files containing a mix of HTML and Liquid template markup.

Following are descriptions of what all of these files and folders are for, what’s required, and what you can leave out if you wish.

theme.json file (required)

theme.json is a JSON-formatted file that describes the site’s theme.

Here is an example theme.json file:

        {
          "title": "My Theme",
          "description": "Just an example. Nothing to see here. Move along.",
          "homepage": "https://github.com/liveeditor/my-awesome-theme"
        }
        

theme.json attributes

config.json.sample file (required)

You should copy the contents of this file into a new file called config.json, then configure the new config.json file based on your Live Editor environment.

The reason for this is so you can use the theme for multiple sites or even open source the theme without including information specific to your own Live Editor site.

Be sure to leave the blank config.json.sample file behind as a template for future maintainers of the theme.

Here is an example config.json file:

        {
          "admin_domain": "example.liveeditorapp.com"
        }
        

config.json file attributes

layouts folder (required)

Layouts are the general Liquid templates that define how pages within the site should be structured.

The layouts folder contains 2 types of files:

1. A JSON file called layouts.json (required) describes the layouts.
2. One or more .liquid files mark up each layout listed within layouts.json. These files’ names will always end with _layout.

See the guide on Layouts for more details.

README.md file (optional)

This file should contain whatever information you find relevant for using and maintaining your theme. It should be formatted in Markdown.

README files tend to include this information:

• General description of the project
• How to install the project’s dependencies (if any)
• Any gotchas that a maintainer should be aware of
• Links to helpful resources

assets folder (optional)

Every file and subfolder contained within the assets folder will be distributed to Live Editor’s content delivery network (CDN). These files are all treated as static assets and will be served to users as-is.

Even though the liveeditor new command provides a few base files and subfolders in the assets folder, you can structure its contents however you want. Or you can exclude it if you want to refer to assets hosted somewhere other than Live Editor’s CDN.

If you like coding plain old CSS without any preprocessors, you can write all of your CSS code within the example file provided at assets/css/site.css, and it will be distributed automatically to Live Editor’s CDN.

If you’re using preprocessors like Sass, Less, CoffeeScript, etc., the assets folder should be configured as the target for the final generated files. You’ll want to keep the source sass/scss/less/coffee/etc. files outside of the assets folder, usually within their own subfolders off of the project root. This will keep you from needlessly posting source files to the CDN.

See the guide on Layouts for more details, including how to link up your layouts to these assets.

content_templates folder (optional)

Content templates define the structure of content. They can consist of 1 or more blocks (e.g, text, image, video) and 1 or more displays (e.g., list view, full article view).

The content_templates folder contains a collection of subfolders for each content template, named with underscores as word delimiters. Within each folder are the following:

• ...
• content_templates
  • blog_post
    • full_display.liquid
    • list_display.liquid
  • content_templates.json
• ...

The content_templates.json file (required) contains JSON describing all content templates, their blocks, and their displays.

One or more .liquid scripts mark up up how content based on this template should be displayed in different scenarios. These files’ names will always end with _display.

See the guide on Content Templates for more details.

navigation folder (optional)

This folder contains configuration and Liquid markup for your site’s navigation menus.

Within the folder is a configuration file named navigation.json and .liquid files for each navigation menu. Each Liquid file name must end with _navigation.

See the Navigation Menus guide for more information.

partials folder (optional)

This folder contains Liquid partials (or “snippets” in Shopify parlance) that can be included in other Liquid templates.

For example, if your theme has 5 layouts, you probably won’t want to duplicate the site’s header into each layout. Instead, you would create a file at partials/header.liquid and use the include tag to include it in each layout:

{% include 'header' %}

.gitignore file (optional)

.gitignore is a text file that lists files and folders that Git will omit from commits. If you use Git, this file will help you ensure that you won’t accidentally check the sensitive config.json file into your Git repository.

If you’re not planning on using Git for source control, you can safely remove this file.

Introducing your own tools into the theme folder structure

The preceding list reveals what files and folders Live Editor expects to see, but it doesn’t need to end there. If you want to use your own preprocessors and build tools, you can mix those files and folders into this folder structure however you’d like.

The only rule of thumb is that you should’t store any of your tools’ source and config files in the assets/ folder because it would end up needlessly publishing those files publicly on Live Editor’s CDN.

As an example, your file tree may end up looking something like this if you choose to use Sketch to mock up the interface, Bower to manage your dependencies, Grunt to build your static assets, Git for source control, and the Sass CSS preprocessor:

• assets
  • css
    • site.min.css
  • js
    • site.min.js
• bower_components
• content_templates
• js
• layouts
• mockups
• node_modules
• partials
• scss
• .bowerrc
• .gitignore
• Gruntfile.js
• README.md
• bower.json
• config.json
• config.json.sample
• package.json
• theme.json

In this example, these are the things that would matter the most:

• Gruntfile.js is configured to combine and minify files from the root scss and bower_components folders into the file at assets/css/site.min.css.
• Gruntfile.js is configured to combine and minify files from the root js and bower_components folders into assets/js/site.min.js.
• The README.md file lists Node.js, Bower, NPM, Gulp, and Sass as dependencies and includes information or links to instructions on how to install and run them.

Next steps

Continue on to learn the Basics of Templating, the meat of Live Editor’s themes.