Documentation

Theme File

The theme.yml file controls CollectionBuilder’s display options. These variables impact every page the site builds, so you should be sure to go through each one as you create your site.

To start, locate and open the theme.yml file in the repository’s _data folder.

This file controls bits of almost every page used, including:

Home Page

Home Page Banner:

  • featured-image: This is the image that appears at the top of the home page of your collection. It can be one of the following:
    • the objectid for the image from this collection that you would like to feature on your home page
      • example –> featured-image: demo_psychiana15
    • OR a relative location of an image in your repository
      • example –> featured-image: /images/palouse.jpg
    • OR a full URL to an image elsewhere.
      • example –> featured-image: https://ctrl-shift.org/images/splash/armantrout.jpg
    • if you leave featured-image blank or comment it out, the home page of your collection will have the standard page banner with no image background.
  • home-title-y-padding: Determines how much of your featured image is visible by adding padding above and below the collection banner.
    • A smaller number will feature a smaller amount of the image.
    • Range: 2em - 20em
    • example –> home-title-y-padding: 12em
  • home-banner-image-position: Determines what portion of the image will appear.
    • Options: top, center, bottom
    • example –> home-banner-image-position: bottom

Home Page Features:

  • carousel-height: Determines the height of the carousel on the home page.
    • Indicates pixels, but don’t include “px” in your input.
    • example –> carousel-height: 500
  • featured-subjects: Generates home page “subject” buttons for select subjects.
    • If left blank, automatically generates top 5 subjects. (We typically leave it blank.)
    • To customize, list your own curated subjects. Separate multiple subjects with a semicolon(‘;’).
    • example –> featured-subjects: corn;soy;basketball
  • featured-subjects-max: Sets number of top subjects to display if featured-subjects is auto-generated
    • Default: 5
    • example –> featured-subjects-max: 6
  • featured-locations: Generates home page “location” buttons for select locations.
    • If left blank, automatically generates top 5 locations.
    • To customize, list your own curated locations. Separate multiple locations with a semicolon(‘;’).
    • example –> featured-locations: University of Idaho; Sacramento, California;
  • featured-locations-max: Sets number of top locations to display if featured-locations is auto-generated
    • Default: 5
    • example –> featured-locations-max: 4

About Page

  • about-featured-image: This is the image that appears at the top of the about page of your collection. It can be one of the following:
    • the objectid for the image from this collection that you would like to feature on your home page
      • example –> about-featured-image: demo_psychiana25
    • OR a relative location of an image in your repository
      • example –> about-featured-image: /assets/img/sampleimage.jpg
    • OR a full URL to an image elsewhere.
      • example –> about-featured-image: https://ctrl-shift.org/images/splash/mcmichael.jpg
    • If this field is left blank or commented out, CollectionBuilder will use the image featured on the site’s home page (i.e. featured-image)

Browse Page

See our Customizations page and the config-browse.csv in the _data folder to configure the Browse page.

Item Page

  • browse-buttons: Adds previous/next arrows to items, but doubles build time.
    • Tip: We usually add these at the end. They’re a nice feature for improved browsing, as they let users use the mouse or the right and left arrow keys to move through the collection.
    • Options: true, false
    • example –> browse-buttons: true

Subjects Page

  • subjects-fields: Choose metadata fields from your collection metadata CSV to be included in the Subjects page tag cloud.
    • Multiple fields must be separated by a semicolon(;)
    • example –> subjects-fields: subject;creator
    • When this field is left blank, subjects will not be generated and the tag cloud on the Subjects page will be blank.
    • Important note: You must also remove the “Subjects” line from the _data/config-nav.csv in order to remove the Subjects page from the site completely.
  • subjects-min: Minimum number of times a subject term must appear before being displayed in the tag cloud.
    • Use this to improve load and build times. Too many terms = slow load time!
    • Range: 1 - 30 (note that a really large number will likely make no subjects appear)
    • example –> subject-min: 4
  • subjects-stopwords: A set of words/phrases to be removed from the tag cloud.
    • Multiple fields must be separated by a semicolon(;)
    • example –> stopwords: boxers;boxing;boxer

Locations Page

This page functions exactly as the Subjects page does.

  • locations-fields: Choose metadata fields from your collection metadata CSV to be included in the Locations page tag cloud.
    • Multiple fields must be separated by a semicolon(;)
    • example –> location;stadium
    • When this field is left blank, locations will not be generated and the tag cloud on the Locations page will be blank.
    • Important note: You must also remove the “Locations” line from the _data/config-nav.csv in order to remove the Locations page from the site completely.
  • locations-min: Minimum number of times a location term must appear before being displayed in the tag cloud.
    • Use this to improve load and build times. Too many terms = slow load time!
    • Range: 1 - 30 (note that a really large number will likely make no locations appear)
    • example –> location-min: 1
  • locations-stopwords: A set of words/phrases to be removed from the tag cloud.
    • Multiple fields must be separated by a semicolon(;)
    • example –> stopwords: Moscow;Pullman

Map Page

  • latitude: Determines the center of map.
    • example –> latitude: 46.727485
  • longitude: Determines the center of map.
    • example –> longitude: -117.014185
  • zoom-level: Determines the zoom level for your map. The higher the number, the more zoomed-in you’ll be.
    • Range: any whole number between [0 - 18]
    • example –> zoom-level: 5
  • map-base: Determines the base map layer for the map.
    • Options: Esri_WorldStreetMap, Esri_NatGeoWorldMap, Esri_WorldImagery (Default: Esri_WorldStreetMap)
    • example –> map-base: Esri_WorldImagery

The fields below determine map search and map cluster features. For larger collections with many items at one spot, we recommend turning on the map-cluster option and turning off the map-search feature.

  • map-search: Enables a user to search the map via the large magnifying glass on the top right.
    • Not suggested for large collections.
    • Options: true, false
    • example –> map-search: true
  • map-search-fuzziness: Allows for less precision with search terms.
    • Range:
      • 0 = exact match only
      • 1 = anything
    • example –> map-search-fuzziness: 0.35
  • map-cluster: Clusters markers that are near each other.
    • Suggested for large collections or for collections with many items in same location.
    • Options: true, false
    • example –> map-cluster: true
  • map-cluster-radius: Determines the size of clusters
    • Range: 10 to 80
    • example –> map-cluster-radius: 25

Timeline Page

The Timeline page represents each year as a row and each corresponding item as a thumbnail. This section will let you determine which years are in the dropdown button at the top right of the Timeline page. This button allows a user to jump down the page.

  • year-navigation: Sets the years to appear in Timeline dropdown nav.
    • Tip: If left blank, these will auto-generate. (We recommend leaving this blank.)
    • example –> year-navigation: 1900;1905;1910;1915;1920
  • year-nav-increment: Sets the increment at which the years in the Timeline dropdown nav are automatically generated.
    • Default: 5
    • example –> year-nav-increment: 7

Data Download

  • metadata-export-fields: A list of metadata fields available for export via data downloads.
    • If you’d like all your fields included, paste in the first row of your collection’s CSV
    • This variable determines what metadata will be made available for download via the ‘Download Data’ options on the Home page and on the Data page.
    • Format: Comma-delimited list contained between quotes
    • example –> metadata-export-fields: "title,description,subject,date,date is approximate,source,latitude,longitude,subject (lcsh),format-original,donor,identifier,format,language,type,rights,rightsstatement,cdmid,objectid"
  • metadata-facets-fields: Generates a facets list download option for given fields.
    • Format: Comma-delimited list contained between quotes
    • example –> metadata-facets-fields: "subject,locations,format"

Advanced Theme Options

Images

Image Size:

CDM-Users only: This is a CONTENTdm-specific variable section for adjusting size of images used throughout the site. CollectionBuilder uses the IIIF API to retrieve images using a percentage size option. The percentage must be 10% or greater.

  • image-percentage-large:
    • Default 70
    • example –> image-percentage-large: 50
  • image-percentage-medium:
    • Default 40
    • example –> image-percentage-medium: 30
  • image-percentage-small
    • Default 20
    • example –> image-percentage-small: 10

Bootstrap Themes

These options will adjust the basic colors of your site’s navigation bar (see Bootstrap navbar docs for details).

  • navbar-color: Choose from navbar-light for use with light background colors, or navbar-dark for dark background colors.
    • Options: navbar-light, navbar-dark
    • example –> navbar-color: navbar-dark
  • navbar-background: Choose from Bootstrap’s background colors.
    • Options: bg-primary, bg-secondary, bg-success, bg-danger, bg-warning, bg-info, bg-light, bg-dark, bg-white, bg-dark
    • example –> navbar-background: bg-dark

Bootswatch:

Bootswatch creates unique themes for Bootstrap-based sites. Swap out the default Bootstrap for a Bootswatch version using the options below as a fun way to demonstrate the power of CSS to transform look and feel.

  • bootswatch: leave blank or comment out for plain bootstrap
    • Options: cerulean, cosmo, cyborg, darkly, flatly, journal, litera, lumen, lux, materia, minty, pulse, sandstone, simplex, sketchy, slate, solar, spacelab, superhero, united, yeti
    • example –> bootswatch: cerulean

Theme Fonts:

These options change the way the fonts appear throughout your collection. If you leave any option blank, it will revert to the CollectionBuilder defaults.

  • base-font-size: Changes the base size for fonts throughout the site.
    • example –> base-font-size: 1.2em
  • text-color: Changes the color of the base font. Probably want a shade of black …
    • example –> text-color: "#191919"
  • link-color: Changes the link color used throughout the site. Base color is a primary blue.
    • example –> link-color: "#17a2b8"
  • base-font-family: Changes the font family
    • If it’s a google family, you’ll need to use the font-cdn option below to add the style sheet link to the site.
    • example –> base-font-family: Georiga; serif;
  • font-cdn: This lets you add fonts from Google Fonts or other online resources provided by a content delivery network (cdn). These are typically provided by the service you are using.
    • example –> font-cdn: <link href="https://fonts.googleapis.com/css?family=Roboto&display=swap" rel="stylesheet">
« Config File Back to Top Customize »