The Juicebox File Layout

Two versions of the Juicebox file layout exist. Both run on the same Juicebox kernel code. The versions are distinguished by

  juicebox_version: '4'

Version 3

Version 3 is designed so that each stack directory contains all resources needed for that stack.

app.yaml                   App details, list of stacks to display
theme.yaml                 Defines logo, css
help/                      Markdown or html help
public/                    Contains images used in the app
        stack.yaml         Stack and slice definitions.
        templates.html     Custom templates used by this stack.     Dynamic data services for this stack.
        help/              Stack specific help and tour definition files.

Version 4

With version 4, “stacks” have been renamed to “stories”. The file structure has been simplified to allow visual theming reuse and to consolidate all data service code in a single place.

app.yaml                  App details and list of stories to display or help.html      Application help
    theme.yaml            Theme logo and parentage
    variables.scss        Theme variables
    styles.scss           Custom css to apply to slices
    img/                  Image assets to use as slice backgorunds
    templates/            Custom html templates
    {story_name}.yaml     Story and slice definitions.
public/                   Additional public assets that the app may rely
                          on. For instance, custom javascript code.
data_services/            Dynamic data service code for all stories

Converting from version 3 to version 4

A conversion script will allow version 3 apps to be rewritten as version 4 apps. This conversion script will be available in spring 2019.


  • variables.scss are moved from theme.yaml and placed in their own file for easier editing.
  • All templates are moved from templates.html in stacks to individual files named after each template.
  • Slice extra_css is converted to a class that can be applied to any slice in the entire app. It’s now possible to re-use theming code across slices.
  • Images that were used as slice or story backgrounds are now stored with the theme rather than in public/
  • Application footer content is now part of the theme.yaml.


  • Stack.yaml is now renamed as {story_name}.yaml
  • Tours are moved from individual yaml files in stack/{stack_name}/help/{tour_name}.yaml to story.yaml.


  • Stack level help doesn’t exist. All help is in a markdown or html file at the top level of the app.