Initial commit

docs/advanced_theme.md

@@ -0,0 +1,34 @@
+# Advanced theme options
+
+`theme.yml` includes some advanced theme options to make it easy to customize the look and standard colors.
+Additionally, see "color-theme.md" for information about automatic theming Bootstrap color classes for buttons, text, and backgrounds.
+
+## Navbar colors
+
+By modifying `navbar-color` and `navbar-background` the basic colors of the navigation elements can be switched following Bootstrap theme colors (see [Bootstrap navbar docs](https://getbootstrap.com/docs/5.1/components/navbar/)).
+
+- `navbar-color`: either navbar-light" for use with light background colors, or "navbar-dark" for dark background colors
+- `navbar-background`: choose from standard Bootstrap color utilities, bg-primary, bg-secondary, bg-success, bg-danger, bg-warning, bg-info, bg-light, bg-dark, or bg-white
+
+## Bootswatch themes
+
+To play with more Bootstrap theme-ing, try swapping out a [Bootswatch](https://github.com/thomaspark/bootswatch) favor. 
+This will remove default Bootstrap CSS for the Bootswatch version (from a CDN), swiftly changing the entire look.
+Choose from: cerulean; cosmo; cyborg; darkly; flatly; journal; litera; lumen; lux; materia; minty; pulse; sandstone; simplex; sketchy; slate; solar; spacelab; superhero; united; yeti.
+
+This is mainly just a fun way to demonstrate the power of CSS and frameworks to transform look and feel. 
+
+## Theme fonts 
+
+To tweak the default font and text colors check the "Theme fonts" section.
+These setting will be passed to `/assets/css/cb.scss` which in turn passes the values to the `_sass` to build out the final CSS. 
+
+- `base-font-size` we set font size a bit bigger than Bootstrap default, which can be tweaked here.
+- `text-color` we set the base color to a darker black.
+- `link-color` by default set to match Bootstrap "info". This is an easy way to add a distinctive brand color to your site.
+- `base-font-family` sets the font-family for `body`, overriding Bootstrap. It will be necessary to use `font-cdn` or manually add loading the font in the head element (_includes/head/head.html). 
+- `font-cdn` will add a font stylesheet, such as from [Google Fonts](https://fonts.google.com/), to the head element. Use valid markup, e.g. `<link href="https://fonts.googleapis.com/css?family=Roboto&display=swap" rel="stylesheet">`. Keep in mind, these CDN expose your users to a 3rd party service and trackers.
+
+## Theme icons 
+
+See "docs/icons.md" for details.

docs/analytics.md

@@ -0,0 +1,19 @@
+# Analytics 
+
+CollectionBuilder templates have a builtin method to add analytics tracking snippets to your site.
+
+Any analytics platform can be added by pasting the tracking snippet they provide into "_includes/head/analytics.html".
+During "production" build *only*, the include is added to the head of every page.
+By default, Jekyll is in the "development" environment, so analytics will not be added while you are testing your site locally.
+
+## Production environment
+
+Analytics is only included when building with `JEKYLL_ENV=production`.
+By default, Jekyll is in the development environment, and analytics will not be added.
+To add analytics during build, use this command into Git Bash or Terminal: 
+
+`JEKYLL_ENV=production bundle exec jekyll build`
+
+Or use our short cut Rake task: 
+
+`rake deploy`

docs/build.md

@@ -0,0 +1,41 @@
+# Building your Collection
+
+## Developing Locally 
+
+Before serving/building your project for the **first time**, open terminal in the repository root and run `bundle install`. 
+The Gem "bundler" will manage dependencies based on the project's "Gemfile", and generate a new "Gemfile.lock" with the full list of dependencies being used.
+From then on, you will use `bundle exec` to prefix Jekyll commands to ensure you are using the bundled dependencies.
+
+When developing the collection locally, use `bundle exec jekyll s` to start the development server.
+Jekyll will serve the site at the local host url so the links will look like `http://127.0.0.1:4000/demo/psychiana/`.
+
+In the background, Jekyll generates the site and outputs the files to the "_site" directory in your project repository.
+Ruby provides a development server from that location.
+
+By default the Jekyll environment is "development" when using `jekyll s`. 
+In this environment CollectionBuilder skips some template elements to cut down on build time, including these `_includes`:
+
+- head/item-meta
+- head/page-meta
+- head/analytics
+
+## Building for Deployment 
+
+To deploy the collection on the live web, you will need to use the Jekyll environment variable "production" and the `build` command rather than serve. 
+
+This is set by adding the env variable, `JEKYLL_ENV=production`, in front of the command: 
+
+`JEKYLL_ENV=production bundle exec jekyll build`
+
+To simplify, this command is added in a [Rake](https://github.com/ruby/rake) task in this repository.
+Typing the command `rake deploy` will set the correct environment and build. 
+You will get an error if you have not previously done `bundle install` for the project.
+(*note:* setting ENV cannot be done on windows CMD, use the rake task or Git Bash terminal)
+
+Jekyll will output the site files to the "_site" directory. 
+Everything in "_site" should be copied over to your web server into the correct file location depending on what you set in "_config.yml" as the `baseurl`.
+
+*Note:* Since the extra elements are included during "production", the build time will be *significantly* higher than when using the development server.
+During production build, Jekyll will generate `relative_url` and `absolute_url` using the `url` and `baseurl` values set in _config.yml. 
+Keep in mind that because CollectionBuilder makes use of `absolute_url` for many assets and links, the site built using `rake deploy` will only work correctly if it is copied to the correct location on your web server.
+It will not work in the "_site" folder, since the links point to locations on your server.

docs/cloud.md

@@ -0,0 +1,69 @@
+# Create Cloud Visualizations
+
+## Built-in clouds
+
+For simplicity, the default CB theme has two pre-configured cloud visualization pages pre-configured named "Subjects" and "Locations". 
+These can be configured using variables in the "_data/theme.yml" to generate clouds from any field(s) in your metadata (not necessarily just a "subject" or "location" field). 
+The theme options look like:
+
+```
+# Subject page
+subjects-fields: subject;creator # set of fields separated by ; to be featured in the cloud
+subjects-min: 1 # min size for subject cloud, too many terms = slow load time!
+subjects-stopwords: # set of subjects separated by ; that will be removed from display, e.g. boxers;boxing
+
+# Locations page
+locations-fields: location # set of fields separated by ; to be featured in the cloud
+locations-min: 1 # min size for subject cloud, too many terms = slow load time!
+locations-stopwords: # set of subjects separated by ; that will be removed from display, e.g. boxers;boxing
+```
+
+The files "pages/subjects.md" and "pages/locations.md" pull in these values to create the default cloud pages.
+The settings also create matching data outputs in the "/assets/data/" folder.
+
+If `subjects-fields` or `locations-fields` is blank or commented out, the template will not build out the related cloud page or data, which saves build time. 
+If you are developing a particularly large collection, you can comment out these options to make rebuild much quicker. 
+
+Keep in mind these page stubs (`/subjects.html`, `/locations.html`) will also have to be present in "config-nav.csv" to show up in your navigation, and to have the data files to show up in data download options. 
+
+## Cloud Layout and Front matter
+
+Custom cloud pages can be easily created using the cloud layout and page front matter.
+Create a new page stub with standard front matter, and add these cloud values: 
+
+- `cloud-fields:`, with a value of a set of fields separated by `;` to be featured in the cloud.
+- `cloud-min:` (optional), with a integer value such as `2`.
+- `cloud-stopwords:` (optional), with a set of terms separated by `;` that will be removed from display.
+
+For example, to create an "Authors" cloud page, create a file named "authors.md" in the "pages" folder. 
+Edit the "authors.md" with this front matter and content:
+
+```
+---
+title: Authors
+layout: cloud
+permalink: /authors.html
+cloud-fields: creator
+cloud-min: 
+cloud-stopwords:
+---
+
+## Browse Authors
+
+Example custom cloud page.
+```
+
+## Cloud include 
+
+Clouds can also be directly added to any page using the "_include/js/cloud-js.html" include in the page stub content.
+This makes it possible to embed a cloud anywhere in other interpretive content pages. 
+
+First, add a div with `id="cloud"` where you want the cloud to display.
+Then below the div add the cloud-js include and provide the variable `fields`, and optionally variables `min` and `stopwords`. 
+
+For example:
+
+```
+<div id="cloud" class="text-center my-4 bg-light border rounded p-2"></div>
+{% include js/cloud-js.html fields="creator;publisher" min=2 stopwords="example;another" %}
+```

docs/code_design_notes.md

@@ -0,0 +1,30 @@
+# Code Design Notes
+
+General notes about how the template is set up, design decisions, and features available to customize the code. 
+
+## Template Page Design
+
+Generally CB template pages are made of three parts:
+
+- a "stub" found in "pages" folder, generally in markdown. The stub can contain markdown content and feature includes, but should not generally contain complicated JS.
+- a "layout" found in "_layouts" folder, in html. This is the template html that the content will be injected into. Most layouts will have an additional layout of "page" or "default".
+- component includes found in "_includes" folder, generally in html. Includes contain modular components of html, JS, and Liquid that add content or code to the page.
+
+To ensure JS is loaded in correct order, JS includes are added via the "_includes/foot.html".
+See "docs/foot.md" for details.
+
+## Links and Btn
+
+We use Bootstrap button classes to style many of our links. 
+If they are actual links, i.e. go to a different page or to an anchor on the page, they should NOT have the attribute `role="button"` since this can trigger odd rendering and unnecessary screen reader interactions. 
+For example, `<a class="btn btn-primary" href="https://example.com">Link</a>`.
+
+If `<a>` tags are used to trigger interactivity on the page, for example opening a modal, then they SHOULD have `role="button"` for accessibility purposes. 
+For example, `<a class="btn btn-primary" href="#" role="button" data-toggle="modal" data-target="#exampleModal">Link</a>`.
+However, in these cases it is generally better for accessibility and semantic markup to use a `<button>` element, rather than use a `<a>`.
+
+For accessibility and useability we avoid using links with `target="_blank"` attribute (a [summary of reasons](https://css-tricks.com/use-target_blank/)).
+If that attribute is used, you should also include the attribute `rel="noopener"` for [security](https://web.dev/external-anchors-use-rel-noopener/).
+For example, `<a href="" target="_blank" rel="noopener">link</a>`.
+Target _blank links are currently used for links to JSON files (so they can be viewed in the browser) and Item downloads (since these could be a variety of file types or links).
+ 

docs/color_theme.md

@@ -0,0 +1,21 @@
+# Color Theme
+
+For simplicity, CollectionBuilder uses pre-compiled Bootstrap CSS.
+However, to make basic theming possible, we have added some code in `_sass/_theme-colors.scss` based on Bootstrap Sass to generate custom color CCS for btn-, btn-outline-, text-, and bg- classes. 
+The custom classes can override existing Bootstrap theme colors or create new color classes. 
+
+By default, these options are not used.
+
+To add custom colors, edit the two columns in `_data/config-theme-colors`:
+
+- Add a "color_class", e.g. `primary` (i.e. the part after the `-` in `btn-primary`).
+- Add a "color" in hex code, e.g. `#4232a8`.
+
+Any "color_class" with a "color" value will generate a btn-, btn-outline-, text-, and bg- class for the color, e.g. `btn-primary`, `btn-outline-primary`, `text-primary`, and `bg-primary`. 
+Any "color_class" with a blank "color" will be ignored.
+For convenience, the standard Bootstrap theme colors are provided to fill in if desired, which will override the existing Bootstrap colors.
+Adding a non-Bootstrap "color_class" will generate new custom btn colors.
+E.g. "color_class" `special` will generate CSS for `.btn-special` and `.btn-outline-special`.
+
+CollectionBuilder uses `btn-primary`, `btn-outline-primary`, `btn-success`, `btn-info`, `btn-outline-secondary`, `btn-light`, and `btn-outline-light` in page layouts, so overriding those styles will have immediate effects on the colors.
+The nav elements use `bg-dark` and `text-dark` by default.

docs/compound_objects.md

@@ -0,0 +1,59 @@
+# Compound Objects
+
+"Compound objects" are a concept used in some repository platforms to describe items that are made up of a set of digital files intended to be treated as one singular connected record in the system.
+CollectionBuilder has built in item page templates for displaying compound objects that are represented in your metadata.
+This is similar to choosing a "display_template" value for your records (see "docs/item_pages.md"), however, because compound objects require some additional metadata conventions, the details are described here.
+
+## Quick Overview + Requirements
+
+Compound objects can be added to CollectionBuilder following these conventions in your metadata:
+
+- A "parentid" column must be present in your metadata spreadsheet/csv. The "parentid" will be empty for all normal items. 
+- A parent metadata record must be created for each compound object with a display_template value of either `compound_object` or `multiple`. 
+    - a `compound_object` will display a grid of collected items (of any accepted CB type) whose metadata and media can be viewed in a series of browsable modals
+    - a `multiple` is image based and will display a vertical series of larger images that scroll down the page
+- The parent metadata record requires an objectid but no parentid.
+- Each child record must have an objectid AND a parentid.
+- Each child record's parentid value must match the parent metadata record's `objectid` 
+    - e.g. If the parent's objectid is example002, then all children for have "example002" in their parentid field
+
+Please look at the demo compound object metadata sheet for an example of how this might look in the metadata: <https://docs.google.com/spreadsheets/d/1UNwl02r3fB-ybiKqb3SY4K30Tf4_rY_NOv5_o5WtVoY/edit?usp=sharing>, and see the demo CollectionBuilder-CSV site for how this looks in operation. 
+
+## Context 
+
+There are two main approaches to representing these types of objects in a CollectionBuilder project. These correspond to the display templates "compound_object" and "multiple." 
+
+A `compound_object` can include any type of media that CollectionBuilder handles, i.e. image, pdf, video, audio, panorama, or record. A `multiple` should be image based, and is best used for items such as postcards or multi-view records of a 3-dimensional object. These items will display as such: 
+
+- Those items with the display_template of `compound_object` will display as a grid of cards featuring item thumbnails that, upon being clicked, will open a child object page as a modal. 
+- Those items with the display_template of `multiple` will display as larger small images that *do not* have child object pages. If one clicks on one of these larger images, they will open up in a zoomable spotlight gallery.
+
+**Note:** The "multiple" display template works well if the additional files do *not* require their own extensive metadata. Our build will only represent the "title" of the child elements on the item page -- all other metadata for child objects with the display_template postcard will be ignored. 
+
+### `compound_object` Examples
+
+- Scrapbook: for a digitized book the "compound object" might contain a series of 25 individual page images. The parent metadata record provides full details about the book, while the child metadata records will only describe the unique information about each page such as a transcript.
+- Oral history: each object might contain different derivatives of an interview, audio, video, transcript, and portrait.
+- Gallery: a gallery of images from one event that are individually described
+
+### `multiple` Examples
+
+- Postcard: usually a compound object containing a front and back image. 
+- 3D archeological artifact: archeological objects are often imaged from standardized perspectives to provide experts information about the piece.
+- Gallery: a gallery of images from one event that are not individually described
+ 
+## parentid
+
+Our approach for describing "compound objects" and "multiples" require a top level metadata record describing the object overall (the parent). As such, these items diplays depends on the parentid field, which connects child metadata record(s) that describe the individual related files to the parent record. 
+This allows each child object to be fully described individually (or not) using your full metadata template.
+It is also useful if you are exporting existing metadata from a platform such as CONTENTdm with "page level" metadata.
+
+These are the basic conventions:
+
+- The child record(s) must have a "parentid" that matches the "objectid" of their parent.
+- Both the parent and the child must have an "objectid".
+- The parent should have a "display_template" of "compound_object" or "multiple" to use the respective display templates.
+- Child records should have their own "display_template" to help choose the appropriate features on the item page. (i.e. use "image" for a .JPG file)
+- The image listed in image_thumb and image_small of the parent will be used to represent the item in all visualizations.
+- You can use the Compound Objects options in the theme page to determine if you would like your compound objects to show up in the timeline, map, or browse pages.
+- Default visualizations (except the item page) use *only* the parent record, so child records are not searchable on the browse page of search page.

docs/data.md

@@ -0,0 +1,45 @@
+# Data export
+
+CollectionBuilder uses Jekyll to generate specialized derivatives of your metadata to consume for visualizations and to expose for others to download.
+
+Data used by the website and available for download is in the `/assets/data/` directory.
+
+Data used by the visualizations is usually specialized and optimized for page load, thus limited to the exact fields and information used by the specific page consuming it.
+These derivatives are often written directly into the HTML pages for faster load time.
+
+Since this data is not easy to understand or reuse, CollectionBuilder also generates more complete versions for others (and yourself) to consume. 
+
+The `/assets/data/metadata.csv`, `/assets/data/metadata.json`, and `/assets/data/geodata.json` data downloads are driven by the `site.data.theme.metadata-export-fields`. 
+This means the CSV/JSON download can be more complete, containing more fields than are displayed anywhere on the site.
+
+Other data derivatives are provided to explore and quantify collection content.
+`facets.json` can summarize the unique value counts of metadata fields. 
+The fields evaluated by `facets.json` is configured using `site.data.theme.metadata-facets-fields`.
+The `subjects.json`, `subjects.csv`, `locations.csv` and `locations.json` use the same routine to generate commonly used facets, plus links to the collection's browse page to explore them.
+The fields used are configured in `site.data.theme.subjects-fields` and `site.data.theme.locations-fields`.
+
+`timelinejs.json` is a time-focused format designed to work with the standalone version of Knight Lab's [TimelineJS](http://timeline.knightlab.com/).
+
+A link to the source code repository will be included if `source-code` is set in _config.yml, otherwise it will link to CollectionBuilder.
+
+## Data Markup
+
+The data found in `/assets/data/` can be seen as a "datapackage" containing all the derivatives related to the collection.
+This data is described by two markup standards. 
+
+First, the Data page (`/data.html`) contains [schema.org Dataset](https://schema.org/Dataset) markup embedded on the page in json+ld format (written in the `_includes/data-download-modal.html` file). 
+This markup is [required by Google](https://developers.google.com/search/docs/data-types/dataset) to be indexed into their datasets search engine. 
+
+Second, `/assets/data/` contains `datapackage.json` as described by the Frictionless Data [Data Package Spec](https://specs.frictionlessdata.io/data-package/).
+Each data file "resource" is described following the [Data Resource Spec](https://specs.frictionlessdata.io/data-resource/).
+
+Both methods provide metadata about the collection and a list of all downloadable data formats, documenting the data for better reuse and preservation.
+
+## Data download logic
+
+The data downloads displayed on the Data page, on the home page "Collections as Data" box, and in the data markup schemas is based on which pages are present in `config-nav.csv` "stub" field. 
+If stubs contain "subject", "location", "map", and/or "timeline" the corresponding data formats will be displayed for download and included in the markup.
+If you change the default name of the stubs, or use the default pages for different content, this logic may display the incorrect set of data. 
+Please manually check over `_includes/data-download-modal.html`, `_includes/index/data-download.html` and `assets/data/datapackage.json` to select the correct files.
+
+See docs/markup.md for additional information.

docs/foot.md

@@ -0,0 +1,38 @@
+# Foot Section
+
+All JS is loaded at the bottom of the page in "foot.html" include.
+This ensures JS libraries are loaded in correct order and are optimized for page load.
+
+First, "foot.html" adds bootstrap bundle and lazysizes assets which are required on all pages. 
+Next, any other chunks of JS are added via includes based on the page layout or front matter options.
+
+Most default CB layouts have a custom JS component specific to the visualization.
+In general, these are added to the page using the `custom-foot` option in the layout's front matter.
+
+## custom-foot Option
+
+To add an include to any page or layout, use the `custom-foot` option in the yml front matter. 
+
+Create the include in the "_includes" folder, then provide the filename in the `custom-foot` value.
+Multiple includes can be added separated by a semicolon `;`.
+
+### custom-foot Example
+
+You want to add some custom JS to "pages/about.md".
+
+Create the includes "_includes/js/example.html" and "_includes/js/another_example.html" with the module component parts. 
+The JS will be written in the includes inside of `<script>` tags, as if it is an html file.
+
+In the file "pages/about.md", add the front matter option `custom-foot: js/example.html;js/another_example.html`.
+The resulting front matter might look like:
+
+```
+---
+title: About
+layout: about
+permalink: /about.html
+custom-foot: js/example.html;js/another_example.html
+---
+```
+
+The two includes will be added by "foot.html", after bootstrap js is loaded.

docs/gallery.md

@@ -0,0 +1,11 @@
+# Gallery viewer
+
+Powered by Spotlight gallery, https://github.com/nextapps-de/spotlight
+
+Used to add full screen view to item pages, potentially with support for multiple images or for browse (not currently implemented, for example see items in [HJCCC](https://www.lib.uidaho.edu/digital/hjccc/)).
+
+Add assets and basic initialization to any page by adding front matter `gallery: true`. 
+
+The items to include in the gallery require a `a` around each individual image with `class="spotlight gallery-img"` plus `href=` with the link to higher quality image.
+
+This is currently automatically added to item pages for objects with images.

docs/icons.md

@@ -0,0 +1,88 @@
+# Icons
+
+The template includes [Bootstrap Icons](https://icons.getbootstrap.com/) 1.5.0 for use in pages. 
+The full icon set is in "assets/lib/icons".
+
+## Full Bootstrap SVG Sprites
+
+It is set up to use the SVG Sprite with external file method (svg + `use`), which is efficient for users and relatively easy to use (however is NOT supported in older versions of Internet Explorer). 
+Use is similar an icon font, but is more efficient and icons can scale to any size.
+The external svg file will only be loaded once by the browser, then cached and used to load icons through out the site, which makes it more efficient than loading individual svg as images or inlining the svg.
+
+The pattern to use the full Bootstrap SVG Sprite set looks like this:
+
+```
+<svg class="bi icon-sprite" aria-hidden="true">
+    <use xlink:href="{{ site.lib-assets | default: '/assets/lib' | relative_url }}/icons/bootstrap-icons.svg#arrow-up-square" href="{{ site.lib-assets | default: '/assets/lib' | relative_url }}/icons/bootstrap-icons.svg#arrow-up-square"></use>
+</svg>
+<span class="visually-hidden">Up Arrow</span>
+```
+
+The `xlink:href` is the link to the icons file (all icons are includes in the file "/assets/lib/icons/bootstrap-icons.svg"), plus `#` plus the id of the icon you want to use. 
+Find the id/names of all icons on the [Bootstrap Icons](https://icons.getbootstrap.com/) page.
+
+Styles to make the sprites work are in `_sass/_base.scss`. 
+The `.bi` class applies to all the sprite icons generally to set some useful defaults, including add `fill: currentColor` so that the icon will follow the parent's text color.
+The `.icon-sprite` class adds a width and height of `1em` which allows the icon to be used like a font character (when combined with the `bi` styles).
+These are kept separate for instances when you might want to use the icon like an image with a percentage width or other sizing method.
+
+If the icon is used to convey meaning, you should use `aria-label=` or `<span class="visually-hidden">` to add an alternative for icon as sibling of svg.
+The svg element should have `aria-hidden="true"` added to avoid issues with the content being read twice on screen readers. 
+
+The icon-sprite style icons can be added using the feature/icon.html include, 
+e.g. `{% include feature/icon.html icon="file-play" label="Audio file" %}`.
+This include can add icons anywhere, including inline in Markdown content.
+
+To use an icon similar to an image (for example as an icon stand in for thumbnails on Browse or Timeline), follow the pattern:
+
+```
+<svg class="bi w-50 text-body" fill="currentColor" aria-hidden="true">
+    <use xlink:href="{{ site.lib-assets | default: '/assets/lib' | relative_url }}/icons/bootstrap-icons.svg#file-earmark-play"/>
+</svg>
+<span class="visually-hidden">File icon</span>
+```
+
+In this example, the classes on the svg element control the size and color: 
+
+- `w-50` to set the svg to be 50% of the parent space. This makes it easy to create responsive icons if the svg element is inside a column div.
+- `text-body` to set the color. Any BS text color utility can be used, including your custom color theme classes.
+
+## Theme Icons
+
+CollectionBuilder-CSV uses a small set of icons for fall back thumbnails for items that do no have images available. 
+If a template page is looking for `image_small` or `image_thumb` and finds it blank, it will choose an icon replacement based on `display_template` or `format` fields (on Browse, Map, Timeline, and Item pages).
+Theme icons are also used for the "back to top" button.
+
+During Jekyll's build process, CollectionBuilder's "cb_helpers" plugin processes the icons and adds them to `site.data.theme_icons`. 
+The theme icons are added to a SVG Sprite file "/assets/css/cb-icons.svg" (which is much smaller and customized compared to "bootstrap-icons.svg").
+
+Configuring the theme icons is *optional*. 
+If desired, the default icons can be overridden or new icons can be added using the `icons` object in "_data/theme.yml". 
+The default values look like:
+
+```
+icons: 
+  icon-image: image
+  icon-audio: soundwave
+  icon-video: film
+  icon-pdf: file-pdf
+  icon-record: file-text
+  icon-panorama: image-alt
+  icon-compound-object: collection 
+  icon-multiple: postcard
+  icon-default: file-earmark # fall back icon
+  icon-back-to-top: arrow-up-square
+```
+
+The icon key (e.g. `icon-image`) will become the id of the SVG sprite symbol. 
+The value must match a Bootstrap icon svg found in "assets/lib/icons/" folder.
+Adding new keys will add additional icons to the SVG sprite file.
+
+All theme icons configured in `icons` (plus the default ones) can be used in several ways:
+
+- To add a full svg inline, use the Liquid variable `site.data.theme_icons` plus the icon key plus `.inline`. E.g. `{{ site.data.theme_icons.icon-image.inline }}`.
+- To add an icon svg sprite symbol, use the Liquid variable  `site.data.theme_icons` plus the icon key plus `.symbol`. E.g. `{{ site.data.theme_icons.icon-image.symbol }}`.
+- Use the external svg sprite link markup using with href to the "cb-icons.svg" file and hash for the icon key. E.g. `<svg class="bi text-body" fill="currentColor"><use xlink:href="{{ "/assets/css/cb-icons.svg" | relative_url }}#icon-image"/></svg>`
+
+The "cb_helpers" plugin contains built in SVGs for the default icon options.
+This means if you are not customizing the icons or using feature/icon.html include, the "assets/lib/icons/" folder can be removed if desired.

docs/index.md

@@ -0,0 +1,43 @@
+# CollectionBuilder-CSV Docs
+
+## Set Up 
+
+metadata.md
+metadata-template.csv
+migrate_to_sa.md
+rake_tasks.md
+
+## Deploy
+
+analytics.md
+build.md
+
+## Customization
+
+advanced_theme.md
+color_theme.md
+
+## Page Details
+
+item_pages.md
+cloud.md
+data.md
+maps.md
+navbar.md
+tables.md
+
+## Technical Components
+
+code_design_notes.md
+foot.md
+icons.md
+lazyload.md
+gallery.md
+markup.md
+noindex.md
+oai-pmh.md
+plugins.md
+
+## API recipes
+
+youtube.md

docs/item_pages.md

@@ -0,0 +1,92 @@
+# Item pages
+
+CollectionBuilder-CSV uses "CollectionBuilder Page Generator" plugin to generate individual pages for each record in the collection metadata on the fly.
+
+Typical use requires no configuration.
+CB Page Gen will automatically generate pages from the data specified by "_config.yml" `metadata` (the same as used to populate the rest of the site).
+For more advanced configuration options, including generating other types of pages, see "docs/plugins.md".
+
+CB Page Gen passes all metadata fields through to Jekyll as if each was front matter on a normal file so that the values can be used to populate Item page content.
+This page object is passed to the layout matching the `display_template` value set in each item's metadata, falling back to the default `template` value (normally `item`).
+
+## display_template Layouts 
+
+The `display_template` layouts provide templates for presenting different item types.
+The files are found in "_layouts/item/".
+Look for comments in each layout's front matter for information.
+
+Each display_template layout is typically constructed of modular item page components (found in "_includes/item/") and arranged using Bootstrap.
+This simplifies customization and creation of different item pages depending on collection needs.
+
+Default supported options include: `image`,`pdf`, `video`, `audio`, `panorama`, `record`, `item`, `multiple`, and `compound_object`. 
+
+- `image`: Displays image_small if available, with fall back to object_location. Adds gallery view to open images full screen using object_location, with fall back to image_small.
+- `pdf`: Displays image_small if available, with fall back to image_thumb, or a pdf icon.
+- `video`: Displays a video embedded on the page with default support for video files (using `<video>` element with object_location as src), YouTube (from link in object_location), or Vimeo videos (from link in object_location).
+- `audio`: Uses `<audio>` element to embed audio file from object_location as src.
+- `panorama`: a 360 degree image. Item pages will use the Javascript based panorama viewer, [Panellum](https://pannellum.org/) to display the image in a 360 degree view.
+- `record`: metadata only record.
+- `item`: generic fallback item page, displays image or icon depending on "image_thumb"
+- `compound_object`: a record for a object that includes multiple file instances that are described/managed separately in the metadata. Compound objects use their own set of conventions, see "docs/compound_objects.md" for details.
+- `multiple`: a record for a object that includes multiple images (such as a postcard) that are listed separately in the metadata. Multiples use their own set of conventions, see "docs/compound_objects.md" for details.
+
+Each of these layouts in turn is generally given `layout: item-page-base`, so that the custom features of the display templates will share the same standard page layout.
+If you want to change the basic structure of all items pages (breadcrumbs and title at top, citation and rights at button), edit the "_layouts/item/item-page-base.html" or the relevant item includes. 
+
+To create a new custom template, create a ".html" file in the "_layouts/item/" folder. 
+Add front matter to the top of the file (i.e. `---` front matter lines `---`).
+You can use `layout: item-page-base` to inherit the default styles, or you can skip to `layout: page` or `layout: default` to have a completely custom page.
+
+## Item Page Components
+
+Components intended for use in Item page layouts can be found in "_includes/item".
+They can be included in the layouts following the pattern `{% include item/component-name.html %}`.
+Look for information about each include in the comments at the top of the file.
+
+The components use Liquid to pull item metadata into the content elements. 
+Since the metadata is provided with the page object, fields can be accessed following the pattern `{{ page.field_name }}`.
+
+Compound object display_template types use a specialized subset of includes in "_includes/item/child", which make use of the pattern {{ child.field_name }} to pull child item metadata rows, in to the parent Item page.
+
+Below are a few notes on special item components:
+
+### browse-buttons
+
+Item pages can have browsing buttons linking to previous/next item page. 
+This option is turned off or on in _data/theme.yml:
+
+```
+# Item page 
+browse-buttons: true 
+```
+
+Generating browse buttons adds some time to builds on very large collections, so can be turned off to save time during development, or if browse doesn't make sense for the collection content.
+The item order follows the order in the metadata CSV, so pre-sort the CSV to the desired order.
+
+Requires "cb_page_gen" plugin, which provides values for `page.previous_item` and `page.next_item`.
+
+### image-gallery
+
+For image items, a zoomable, full screen gallery view is added using [Spotlight gallery](https://github.com/nextapps-de/spotlight).
+Ensure dependencies are added by including `gallery: true` in the layout front matter.
+See "docs/gallery.md" for more details.
+
+### metadata 
+
+The metadata fields displayed on an item page are configured by "config-metadata.csv". 
+
+Only fields with a value in the "display_name" column will be displayed, and only if the item has a value for that field. 
+(*Note:* if you want a field to display without a field name visible, enter a blank space in the "display_name" column)
+
+Fields with "true" in the "browse_link" column in config-metadata will generate a link to the Browse page. 
+Values in "browse_link" fields will be split on semicolon `;` as multi-valued fields before adding links.
+These often mirror the "btn" links on the Browse config-browse. 
+Keep in mind that for the browse links to be useful, the field must also be available to filter on the Browse page--so the field should also appear in "config-browse.csv" (displayed, btn, or hidden). 
+
+## Item Meta Markup
+
+The default `item-page-base` layout has the front matter value `item-meta: true`.
+This will pull specialized meta markup in head from "_includes/head/item-meta.html" designed to help search indexing, social sharing, and SEO.
+The mark up is configured using "_data/config-metadata.csv" and driven by the metadata fields (see "docs/markup.md").
+
+If you create a new custom layout that does not use `layout: item-page-base`, you will want to add `item-meta: true` to your layout front matter.

docs/lazyload.md

@@ -0,0 +1,10 @@
+# Lazyload images
+
+To avoid making browser load times too long, it is best to defer loading images until they are actually visible to the user. 
+To do this CollectionBuilder uses [lazysizes](https://github.com/aFarkas/lazysizes) library.
+Lazysizes is a simple to use, up-to-date lazyload library that requires no initialization, and will simply load all images if browser support is missing. 
+
+Since lazysizes is used on most pages in the project, `lazysizes.min.js` is loaded as part of the default template in the foot.html include.
+
+For images that should be lazy loaded, add `class="lazyload"` and replace normal `src` with `data-src`.
+No initialization is necessary. 

docs/maps.md

@@ -0,0 +1,76 @@
+# Map visualization
+
+Powered by Leaflet.js, https://github.com/Leaflet/Leaflet
+
+Following best practices listed in the Leaflet guide to accessibility, https://leafletjs.com/examples/accessibility/
+
+With plugins: 
+
+- search, https://github.com/naomap/leaflet-fusesearch
+- cluster, https://github.com/Leaflet/Leaflet.markercluster
+- cluster plugin (for search and cluster to work together), https://github.com/ghybs/Leaflet.MarkerCluster.Freezable
+- full screen, https://github.com/Leaflet/Leaflet.fullscreen
+
+## theme Configuration Options
+
+Set base configuration in "_data/theme.yml" Map section, including:
+
+```
+auto-center-map: true # have the map auto fit all features into its view
+latitude: 46.727485 # to manually center map if not using auto-center-map option
+longitude: -117.014185 # to manually center map if not using auto-center-map option
+zoom-level: 5 # zoom level for map if not using auto-center-map option
+map-base: Esri_WorldStreetMap # set default base map, choose from: Esri_WorldStreetMap, Esri_NatGeoWorldMap, Esri_WorldImagery, OpenStreetMap_Mapnik
+map-search: true # not suggested with large collections
+map-search-fuzziness: 0.35 # fuzzy search range from 1 = anything to 0 = exact match only
+map-cluster: true # suggested for large collection or with many items in same location
+map-cluster-radius: 25 # size of clusters, from ~ 10 to 80
+```
+
+These "theme" options will load the correct CSS and JS for leaflet features, while setting some configuration variables in the javascript.
+
+With the default `auto-center-map: true` option, Leaflet will automatically center and zoom the map based on all the items added to the map--you do not need to set the latitude, longitude, or zoom-level. 
+If you would like to manually set the center and zoom level for the map, set `auto-center-map: false` and set values for the latitude, longitude, and zoom-level.
+
+The `map-search: true` option adds a Fuse-based client-side text search of the configured metadata fields (using leaflet-fusesearch plugin). 
+The index is relatively slow, so you may want to set this option to `false` if you find the map lagging.
+
+The `map-cluster: true` option clusters features on the map (using Leaflet.markercluster plugin).
+Because of the way markers are handled, for larger collections it is strongly suggested to keep cluster on, since it makes loading and navigating the map significantly more efficient.
+The `map-cluster-radius` sets the maximum radius a cluster can cover in pixels on the map.
+A smaller radius will create more, smaller clusters, and increasing will create fewer, larger clusters on the map.
+
+## map-config.csv Options
+
+The metadata displayed on object popups and included in search is configured using using "_data/map-config.csv":
+
+- `field`: matches a column name in the metadata csv that will be displayed in object popups.
+- `display`: display name for the field to appear on popup. if blank, field will not be displayed (but could be used in search)
+- `search`: `true` or `false`/blank. If theme has `map-search` as `true`, then fields with true in this column will be indexed and displayed on the map search feature.
+
+## URL parameters 
+
+The map page supports parsing a query string to set the center and display an Item popup. 
+If the url includes a query string, it will be parsed and set as the map view box with full zoom and open the popup.
+
+Item pages that have lat/long will generate a "View on Map" button link. 
+These link to the "map.html" page with a query string created from their lat long and objectid.
+
+For example: 
+`/map.html?location=46.726113,-117.015671&marker=example_004`
+
+This can be created using the Liquid:
+`{{ '/map.html?location=' | append: page.latitude  | append: ',' | append: page.longitude | append: '&marker=' | append: page.objectid | relative_url }}`
+
+## Customizing the Base Map
+
+You can customize the base maps by editing the template code in "_includes/js/map-js.html".
+
+There is three parts to add a new one:
+
+1. Set up a variable containing the map layer information. For some example free base maps that follow the same pattern as we are using, you can copy the variable from [Leaflet Providers Preview](https://leaflet-extras.github.io/leaflet-providers/preview/).
+2. Add name to the base map switcher. The `baseMaps` variable sets up the names that appear in the switcher that appears in the upper right of the map. It follows the pattern of `"Display Name": Map_Layer_var_name`.
+3. Set the default base map. This is usually set in "theme.yml" as the `map-base` option. If you add a new layer variable, use that name instead of the default ones. Alternatively, in map-js.html you can edit the variable name used to load the base map (which is next after setting up the `baseMaps` var).
+
+Keep in mind that some of the base maps in the free [Leaflet Providers Preview](https://leaflet-extras.github.io/leaflet-providers/preview/) may have usage limitations--check the [Leaflet Providers readme for notes](https://github.com/leaflet-extras/leaflet-providers).
+If you want to do more customization, check the [Leaflet docs](https://leafletjs.com/reference.html), and [Leaflet basemap providers plugins](https://leafletjs.com/plugins.html#basemap-providers).

docs/markup.md

@@ -0,0 +1,104 @@
+# Rich markup
+
+Pages in CollectionBuilder contain machine readable rich markup following several standards to improve discoverability, search representation, and social media sharing.
+
+## Dublin Core 
+
+Dublin Core elements are added to Item pages driven by the "dc_map" column of config-metadata.csv.
+
+Choose mapping options directly from the DCMI Terms namespace: http://purl.org/dc/terms/
+*Note: DMCI the original 15 Elements namespace is mirrored in the Terms namespace (i.e. both have "title", "creator", etc), however, using the newer Terms namespace is preferred.*
+
+The values will be directly added to meta tag name attribute, thus should use the `DCTERMS` prefix.
+
+For example, to use Dublin Core [Title](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/title) from the "Terms" namespace, the value would be `DCTERMS.title`.
+To use [abstract](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/abstract), `DCTERMS.abstract`.
+If the "dc_map" column is empty, no DC meta tags will be added.
+
+Recommended fields to map include:
+
+- `DCTERMS.title`
+- `DCTERMS.creator`
+- `DCTERMS.created` or `DCTERMS.date`
+- `DCTERMS.description`
+- `DCTERMS.subject`
+- `DCTERMS.type`
+
+This implementation is based on DSpace, following the [DC-HTML](https://www.dublincore.org/specifications/dublin-core/dc-html/2008-08-04/) conventions.
+
+## Open Graph Protocol
+
+[Open Graph](https://opengraphprotocol.org/) provides basic metadata in a open standard used by social media sites to generate representations of links shared on the platform.
+Open Graph was established by Facebook, but can be read by other platforms.
+
+OG meta tags are automatically added to every page and are not configurable.
+They provide an authoritative title, description, and image that can be used to represent a link to the page.
+The OG image will be the item image/thumb in the case of item pages, or the site featured image for all other pages.
+For example:
+
+`<meta property="og:title" content="{{ page.title | escape }}" />`
+
+## Schema.org 
+
+Schema is a standard designed to provide structured semantic markup for search engines to better understand content of web pages. 
+The concepts described apply to a generalized web landscape, centered mostly around commercial sites, and don't necessarily follow the logic and structure of library-based metadata or digital collections.
+However, it is useful to provide the markup to drive better representations of the data in search results.
+See [Full Schema hierarchy](https://schema.org/docs/full.html), or [Google Guide to Structure Data](https://developers.google.com/search/docs/guides/intro-structured-data).
+
+Keep in mind that Schema is an open standard, however, Google is the biggest consumer, so information found in Google's [Developer Docs](https://developers.google.com/) is potentially more pragmatically useful (e.g. Google highly recommends using JSON-LD vs. Schema suggesting microdata).
+Markup can be tested using Google's [Structured Data Testing Tool](https://search.google.com/structured-data/testing-tool).
+
+The Schema markup is different on a variety of page types:
+
+### Item pages 
+
+Item pages have in depth Schema markup in JSON-LD format driven by the object metadata. 
+Schema elements are driven by the "schema_map" column of config-metadata.csv.
+Each item page is given the basic type of `CreativeWork`, thus metadata fields can be mapped to any of the properties listed on the [CreativeWork documentation](https://schema.org/CreativeWork). 
+Copy the exact property name, as this value will be turned into schema JSON-LD markup.
+If the "schema_map" column is empty, only the automatically generated markup will be added.
+
+Suggested field mappings include:
+
+- `headline` (i.e. the title)
+- `creator`
+- `dateCreated`
+- `description`
+- `keywords`
+- `contentLocation`
+- `encodingFormat` (MIME type, should = format field of CollectionBuilder items)
+- `license` (should only be used with a standardized rights URL)
+
+Additionally, the Schema type, `isPartOf` (the collection), `image` (url), `thumbnailUrl` (url), and page `url` will be added automatically. 
+
+Note: in the future, our base item type may move to `ArchiveComponent` when this spec is fully integrated into the standard, https://schema.org/ArchiveComponent .
+An alternative approach would be to use `ItemPage`, https://schema.org/ItemPage to describe the object pages, although this seems less direct.
+
+Item pages are also marked up with Schema [BreadcrumbList](https://schema.org/BreadcrumbList) to represent their nesting in the site, which may be [represented in search results](https://developers.google.com/search/docs/data-types/breadcrumb). 
+
+### Data page
+
+The Data page includes Schema markup in JSON-LD representing the various data derivatives that can be downloaded (implemented in _includes/data-download-modal.html which is included by the data layout). 
+See [Google dataset docs](https://developers.google.com/search/docs/data-types/dataset) and [Schema Dataset](https://schema.org/Dataset) for details behind this implementation.
+
+The full metadata download in csv and json are automatically added.
+A metadata facets json file is added if fields are set in theme "metadata-facets-fields".
+Additional datasets described are selected based on what pages are in the config-nav, following the same logic used to select which data download buttons are shown to users.
+If the config-nav contains the following "stub", the following data files will be added to the markup:
+
+- "subject", subjects.csv, json
+- "location", locations.csv, json
+- "map", geodata.json
+- "timeline", timelinejs.json
+
+This may not be accurate for all use cases. 
+An easy way to manually set the downloads, is to create a list based on the stub values shown above, and edit the "stubs" assigned on the data.html layout. 
+For example, if I want to show all data downloads, even though I don't have the pages in the navigation or have named them something different, edit the "assign stubs" line on data.html like this:
+
+`{%- assign stubs = "subject;map;location;timeline" -%}`
+
+Also check docs/data.md for more information.
+
+### Content pages
+
+Other pages in the site receive more basic markup from the head/page-meta.html include following the [WebPage schema type](https://schema.org/WebPage).

docs/metadata-template.csv

@@ -0,0 +1,2 @@
+objectid,parentid,title,creator,date,description,subject,location,latitude,longitude,source,identifier,type,format,language,rights,rightsstatement,display_template,object_location,image_small,image_thumb,image_alt_text,object_transcript
+demo_001,,"Administration Building, University of Idaho, No. 30",Pacific Photo Co.,1910,"Photographic postcard of the University of Idaho administration building in Moscow, Idaho.",universities; buildings; campuses; picture postcards,"Moscow, Idaho",46.725562,-117.009633,"PG 9, Postcard Collection, University of Idaho Library Special Collections and Archives",pg_9_12_01bl,Image;StillImage,image/jpeg,eng,,http://rightsstatements.org/vocab/NoC-US/1.0/,image,/objects/demo_001.jpg,/objects/small/demo_001_sm.jpg,/objects/thumbs/demo_001_th.jpg,historic sepia photograph depicting a formal brick and stone building in the College Gothic style,

docs/metadata.md

@@ -0,0 +1,40 @@
+# Metadata Standards for CB-CSV
+
+See general documentation: <https://collectionbuilder.github.io/cb-docs/docs/metadata/>
+
+## Required fields
+
+- `objectid`: unique string, all lowercase with no spaces or special characters as it will used to form the item’s URL. Underscores (_) and dashes (-) are okay; slashes (/) should NOT be used in this field. Objects without an objectid will not be displayed in the collection. Objects with non-unique objectid will be overwritten.
+- `title`: string description of object, used through out the template in representations of the object. *A title is not technically required, but will leave blanks areas in the template.*
+
+## Object Download and Display images
+
+These metadata values are optional, but provide representations of the items in site visualizations and item pages for your users:
+
+- `object_location`: a full URL to download the full quality digital object or relative path if items are contained with in the project. This file is not used for display on the website, except in the case of image galleries on item pages.
+- `image_small`: a full URL to a small image representation of the object or relative path if items are contained with in the project. If this field is filled, the image will be displayed to represent the item on Item pages or in features added to content pages.
+- `image_thumb`: a full URL to a thumb image representation of the object or relative path if items are contained with in the project. If this field is filled, the image will be displayed to represent the item on visualization pages.
+- `image_alt_text`: an appropriate textual description of the image_small/image_thumb representation of the item. This value will be used as the "alt" value of the image element. If no image_alt_text is provided, the template will fall back to using the item description or title value (which in many cases is not ideal for your users). Using the image_alt_text field allows you to provide more carefully crafted alt text depending on the item contents, type, and context.
+- `object_transcript`: a text transcript of the item's content, most commonly used with video and audio items. The transcript can be added in two ways: 1. adding the full text as the value directly in the field. This is a straight forward way to keep transcript data directly in your metadata. Keep in mind that spreadsheet software typically has limits on the number of characters per cell, so this won't work well with larger transcripts. 2. add the relative path and filename of a transcript text file (.txt, .md, or partial .html) contained in the project repository (usually the "/objects/" folder). The value in "object_transcript" must start with "/" (indicating the root of the repository similar to other relative paths used in the template), e.g. `/objects/transcript1.txt`. The transcript text file must have yaml front matter at the top of the file so that it will be processed by Jekyll (the front matter can be empty, i.e. `---` line break `---`). The transcript text will be retrieved from the file and rendered as Markdown.
+- `format`: object's MIME media type. If an object does not have an image_thumb, format is used by template logic to switch between different icons.
+
+Each object will likely have an object_location value, the link where the digital file can be downloaded (or potentially accessed in a different platform). 
+It is not a required field--items without an object_location will become metadata only records.
+
+For display images in various visualization pages the template checks the fields image_thumb for links to image derivatives (Browse, Map, Timeline).
+If image_thumb derivatives are not available (i.e. the field is left blank), the logic will select icons alternatives based on the display_template or format field.
+If the item has neither display_template or format, it will fall back to a default icon.
+
+These fields should be filed out in your spreadsheet using formulas / recipes depending on where your objects are hosted. 
+This provides flexibility to include objects from multiple sources and to generate the URLs using a variety of approaches without needing to modify the template code.
+CollectionBuilder-CSV aims to provide API recipes to generate the links for a variety of hosting solutions--but this work is done on the metadata, not embedded in the collectionbuilder-csv template code logic.
+
+If the objects are included within the project repository use the relative path starting with `/` from the root of the repository. 
+For example if some images are in the "objects" folder, use a relative path, e.g. `/objects/example_object.jpg`.
+The relative path will be converted into a full URL during build.
+Do not include the `baseurl` value that you set in "_config.yml", since this will be added by the template.
+
+## Display Template
+
+- `display_template`: a template type used in logic to set up different Item page features. If blank the object will default to a generic item page. Default supported options: `image`,`pdf`, `video`, `audio`, `panorama`, `record`, `item`, `multiple`, and `compound_object`. See docs/item-pages.md for details.
+- `parentid`: used to designate child items in the "multiple" and "compound_object" templates, a unique string matching the objectid of the parent item. See docs/compound_objects.md for details.

docs/migrate_to_sa.md

@@ -0,0 +1,50 @@
+# Migrate Older CollectionBuilder Projects to New CSV
+
+CollectionBuilder-CSV introduces a new metadata centered approach to managing the links to collection object downloads and image representations. 
+Rather than embedding the various API options inside the project template, the collection metadata CSV has fields for "object_location", "image_small", and "image_thumb".
+Thus the work of figuring out the API or locations of digital objects is pushed into the metadata, rather than the Liquid includes in the template code. 
+
+This approach enables greater flexibility to adapt to multiple content sources without requiring extensive customization of the template code.
+We hope this better leverages and acknowledges librarian's skill in metadata and spreadsheet data, creating a more accessible and agile approach to customization.
+
+Migrating an existing CollectionBuilder project to the new template is relatively straightforward, involving generating the new fields from your existing metadata values.
+CB-CSV provides recipes to generate the fields which can be used to create new project or migrate existing ones.
+Other configuration options are backwards compatible (_config.yml, _data/theme.yml, _data/config-metadata.csv, etc), but can also be updated to simplify or access new options.
+
+## Migrating Configurations
+
+- "_config.yml": existing configurations options will work in the new template. Changes include:
+    - `objects` value is no longer used (previously used to set location of digital objects). Use the value in your old configuration to help generate the new "objects_download" field in metadata.
+    - `page_gen` object is no longer necessary. The new CB page gen plugin does not require separate configuration, and will generate pages from your configured `metadata`. However, it is compatible with old style configuration, so your settings can be left as is if desired.
+- "_data/theme.yml": existing theme configurations options work the same in the new template. New options include: 
+    - "THEME ICONS" section to customize the default icons used for items with out image representations.
+- "_data/config-" CSVs: The CSVs used to configure individual pages are the same in all versions of CB. Newer versions have more option columns than older templates. 
+
+## Migrating Metadata CSV from CB-GH
+
+CollectionBuilder-GH metadata templates have a column "filename" containing the digital object filename or full URL to the object.
+In most cases "filename" matches a file in the "objects" folder in the project.
+
+Starting from "filename" create a new column "object_location" using `/objects/` + the value of "filename", e.g. `/objects/demo_001.jpg`.
+
+YouTube items should have the full YouTube video link in "object_location" (not just the youtubeid), e.g. `https://youtu.be/dbKNr3wuiuQ` or `https://www.youtube.com/watch?v=dbKNr3wuiuQ`.
+If necessary, these can be generated by adding `https://youtu.be/` + the old "youtubeid" field.
+Vimeo items should have the full Vimeo video link in "object_location", e.g. `https://vimeo.com/330826859`.
+A youtubeid or vimeoid field is not necessary.
+
+## Migrating Metadata CSV from CollectionBuilder-SA
+
+Older style CollectionBuilder-SA metadata templates had a column "filename" containing the digital object filename or full URL to the object, plus the option to set an `objects` value in _config.yml which provided a custom directory location or full url to the web location hosting the objects.
+
+Starting from "filename" create a new column "object_location" using the `objects` value + the value of "filename".
+For example, if the objects are contained with the project in the "objects" folder, the resulting "object_location" should look like `/objects/demo_001.jpg`.
+If the objects are at an external location, they would contain the full url, e.g. `https://example.com/objects/demo_001.jpg`.
+
+If you generated derivatives for your objects (i.e. smalls and thumbs), add the link to those files in "image_small" and "image_thumb" following the same pattern, e.g. `/objects/small/demo_001_sm.jpg` and `/objects/thumbs/demo_001_th.jpg`.
+
+## Migrating metadata CSV from CB-CONTENTdm 
+
+CollectionBuilder-CONTENTdm collections contain values for "cdm-url", "cdm-collection-id" / "collectionid", and "cdmid" which can be used to generate the values for "object_location", "image_small", and "image_thumb".
+
+Collections focused on remaining a skin to a CONTENTdm repository will likely want to continue using CB-CONTENTdm. 
+However, if your collection contains items from multiple repositories or mixes non-CONTENTdm items with CONTENTdm content, there may be advantages to migrating to the new CB-SA template to simplify customization. 

docs/navbar.md

@@ -0,0 +1,39 @@
+# Nav configuration
+
+The navigation bar in the CollectionBuilder template uses the [Bootstrap navbar component](https://getbootstrap.com/docs/5.1/components/navbar/) to add links to the main pages and a search box. 
+The Bootstrap navbar automatically collapses into a menu button on smaller screens (break point `-lg`, which is approximately tablet size). 
+
+The navbar is configured using "_data/config-nav.csv". 
+It is added to the default layout (so that every page has it) using "_includes/collection-nav.html". 
+The same nav items will also be automatically added to the footer ("_includes/footer.html").
+The navbar colors can be configured in theme.yml (see "advanced-theme.md").
+
+config-nav allows you to easily control which pages will show up in your navbar and how they are labelled, as well as create dropdown menus.
+Removing an item does not delete the page, but will make the page invisible to users.
+Each item in the nav is one row of config-nav, including the columns `display_name`, `stub`, and `dropdown_parent`: 
+
+- `display_name` will be the word(s) used on the navbar. Generally you will want these to be single words that are easy for users to understand--typically: Home, Browse, Subjects, Locations, Map, Timeline, Data, About. Modifying this value allows you to quickly change the display name without needing to update the file names or titles. e.g. for some collections a label such as "Creators" might replace "Subjects", while still pointing to the /subjects.html page.
+- `stub` is the relative url of the page in this project. To properly link to a page, the `stub` value will match the `permalink` value of a specific page file. e.g. "browse.md" has `permalink: /browse.html`, thus in config-nav has a stub value of `/browse.html`. These will be converted into relative links in the navbar. The `stub` value will be empty for items that are parents for a dropdown menu (see below).
+- `dropdown_parent` is only used when adding dropdowns to your navbar, and should be empty for any normal nav item. For items that should appear inside a dropdown, the value will match the `display_name` of the parent item (see below).
+
+## Dropdown menus
+
+A [Bootstrap dropdown menu](https://getbootstrap.com/docs/5.1/components/dropdowns/) can be added to a nav item following this convention in config-nav:
+
+- if the item has a `stub`, but no value in `dropdown_parent`, it becomes a normal nav item
+- if the item has NO `stub`, it will become a dropdown menu
+- if the item has a value in `dropdown_parent`, it will only show up under the parent dropdown
+
+For example, a dropdown with two pages under the label About would look like:
+
+```
+display_name,stub,dropdown_parent
+About,,
+About the Collection,/about.html,About
+CollectionBuilder,/tech.html,About
+```
+
+"About" (with no value in stub or dropdown_parent) would appear in the navbar as a dropdown button. 
+When clicked, the dropdown would appear with "About the Collection" and "CollectionBuilder" listed.
+
+Note: dropdowns do NOT appear in the footer nav. The parent will appear, with a link to the top child. 

docs/noindex.md

@@ -0,0 +1,10 @@
+# Robots and Indexing
+
+If you are building a demo or prototype collection you may want to avoid having the content indexed by Google and other search engines. 
+This can be done using a Robots.txt at the root level of the site, or a [robots meta tag](https://developers.google.com/search/reference/robots_meta_tag) on each page. 
+To make adding robots meta tag easy, CollectionBuilder includes the option to add it across the project or to individual pages:
+
+- full site, uncomment or add `noindex: true` to "_config.yml". 
+- individual page or layout, add `noindex: true` to the YML front matter.
+
+This will cause `<meta name="robots" content="noindex" />` to be added to the page(s) head during production build. 

docs/oai-pmh.md

@@ -0,0 +1,69 @@
+# OAI-PMH static implementation
+
+[Open Archives Initiative](http://www.openarchives.org/) develops a set of interoperability standards used in cultural heritage repositories to facilitate aggregation and harvesting of metadata.
+[OAI-PMH](http://www.openarchives.org/OAI/openarchivesprotocol.html) is a standard built into most digital collection repository platforms that requires a server to process a specific set of requests and provide an XML response.
+However, OAI-PMH also specifies a "static repository" implementation intended for smaller collections (less than 5000 records) without processing OAI-PMH requests. 
+
+A "Static Repository" is an XML file following the spec describing the collection published at a persistent URL. 
+
+The Static Repository is made available to harvesters via a single "Static Repository Gateway" which is a server which can respond to OAI-PMH requests, but uses the information in the "Static Repository" to answer.
+
+CollectionBuilder implements the XML template for a Static Repository. 
+Users will need to investigate the arrangement for registering with a Gateway.
+
+## Static Repository File
+
+CollectionBuilder implementation of the "Static Repository" is the "oai.xml" file in the "utilities" directory.
+The file is only generated during production environment build.
+
+Configuration:
+
+- Set `gateway-baseurl` in "oai.xml" front matter: `oai:baseURL` is required for the static repository to be valid, following the pattern Gateway-url + Static-repository-url (without the protocol), 
+  e.g. if the Gateway is "http://gateway.institution.org/oai/" and the static repository is at "http://example.org/ma/mini.xml", the oai:baseURL is `http://gateway.institution.org/oai/example.org/ma/mini.xml`.
+  The template automatically calculates the static repository location, but requires a valid `gateway-baseurl` to be set in the oai.xml front matter.
+- Set `admin-email` in "oai.xml" front matter: a `oai:adminEmail` is required. Please set the `admin-email` in the oai.xml front matter to your valid contact email.
+- Set `dc_map` fields in "config-metadata.csv": OAI XML uses their own version of basic Dublin Core metadata ([oai_dc spec](http://www.openarchives.org/OAI/2.0/oai_dc.xsd)) as a base for records.
+  This allows only the fields: dc:title, dc:creator, dc:subject, dc:description, dc:publisher, dc:contributor, dc:date, dc:type, dc:format, dc:identifier, dc:source, dc:language, dc:relation, dc:coverage, dc:rights.
+  The oai.xml template will iterate over all items using the `dc_map` of fields listed in `site.config-metadata`. 
+  It will compare dc_map (which are given in format like `DCTERMS.title`) with the available oai_dc terms. 
+  E.g. if you have `DCTERMS.creator` in dc_map, it will fill in `<dc:creator>` in the XML. 
+
+Notes: 
+
+- must have "oai-identifier" following pattern `oai:domain-name:local-identifier`, e.g. `oai:foo.org:some-local-id-53`. In CB context this is translated as: `oai:{{ site.url | remove: 'https://' }}:{{ site.baseurl | remove: '/' }}/{{ item.objectid }}`
+- Specification for an OAI Static Repository and an OAI Static Repository Gateway, http://www.openarchives.org/OAI/2.0/guidelines-static-repository.htm
+- Static Repository XML schema, http://www.openarchives.org/OAI/2.0/static-repository.xsd
+
+## Static Repository Gateway
+
+The "static repository" must be intermediated by a Gateway that responds to OAI-PMH requests. 
+Gateways are currently beyond the scope of the CollectionBuilder implementation. 
+Users will have to make arrangements to be registered with a Gateway to complete the OAI-PMH functionality.
+
+A "static repository" must be registered with only one Gateway.
+Access to harvesting will be via the Gateway, following pattern 
+`gateway-url/oai/static-repository-url`, 
+e.g. `http://gateway.institution.org/oai/an.oai.org/ma/mini.xml`.
+
+To set up a new "static repository", need to initiate by sending a request:
+`<Static Repository Gateway URL>?initiate=<Static Repository URL>`, 
+e.g. `http://gateway.institution.org/oai?initiate=http://an.oai.org/ma/mini.xml`
+
+To stop using the Gateway send a termination request:
+`<Static Repository Gateway URL>?terminate=<Static Repository URL>`
+
+Example Gateway Container for a Static Repository Gateway:
+
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<gateway xmlns="http://www.openarchives.org/OAI/2.0/gateway/"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/gateway/
+                      http://www.openarchives.org/OAI/2.0/gateway.xsd">
+  <source>http://an.oai.org/ma/mini.xml</source>
+  <gatewayDescription>http://www.openarchives.org/OAI/2.0/guidelines-static-repository.htm</gatewayDescription>
+  <gatewayAdmin>pat@institution.org</gatewayAdmin>
+  <gatewayURL>http://bar.edu/oai-gateway/2.0/</gatewayURL>
+  <gatewayNotes>http://gateway.institution.org/oai/</gatewayNotes>
+</gateway>
+```

docs/plugins.md

@@ -0,0 +1,133 @@
+# Jekyll Plugins
+
+Jekyll is designed to be extensible via [Plugins](https://jekyllrb.com/docs/plugins/) written in Ruby.
+The simplest method is to add Plugins directly to the "_plugins" directory, making them a part of the project repository (rather than an external Gem).
+The plugins are Ruby code and run immediately as Jekyll starts.
+
+CollectionBuilder-CSV currently uses three custom plugins "CollectionBuilder Page Generator" ("cb_page_gen.rb"), "CollectionBuilder Helpers" ("cb_helpers.rb"), and "Array Count Uniq" ("array_count_uniq.rb").
+
+Keep in mind that plugins can not be used on GitHub Pages default build (although they *can* be used by setting up a GitHub Actions based build process).
+Thus, collectionbuilder-gh uses fairly slow and complicated Liquid and Javascript to generate items pages and unique counts from metadata.
+Those methods are not efficient enough to handle larger collections.
+
+---------
+
+## CollectionBuilder Page Generator
+
+"CollectionBuilder Page Generator" ("cb_page_gen.rb") creates individual html pages from each record in your metadata CSV (or other _data files). 
+I.e. it generates Item pages for your collection driven directly from your metadata.
+It can also generate all sort of other pages from any data file.
+
+Basic use following CB conventions requires no configuration. 
+CB Page Gen will automatically generate pages from the data specified by "_config.yml" `metadata` option.
+
+Alternatively, for more advanced use you can provide one or more configurations in the `page_gen` option in "_config.yml", allowing you to customize the generation options or generate pages from multiple CSVs.
+
+### Considerations 
+
+Keep in mind that the default template pages (Browse, Map, Timeline, etc) all use the `metadata` value to pull in the collection data to populate the page, so you will still need a `metadata` value even if you customize `page_gen` (unless you do more customization to the template pages).
+I.e. `page_gen` values do not set the `metadata` value for the template, the default pages will be blank if you don't have a `metadata` value. 
+Thus `page_gen` can not be used to concatenate multiple CSVs into one collection without further customization of the template.
+Instead it is designed to allow you to generate other types of pages, in addition to item pages.
+
+If you set up a custom `page_gen` value, you will normally require one of the values to match the `metadata` value.
+
+### Page Gen options
+
+The full options with the default values look like:
+
+```
+page_gen:
+  - data: 'metadata'
+    template: 'item'
+    display_template: 'display_template'
+    name: 'objectid'
+    dir: 'items'
+    extension: 'html' 
+    filter: nil
+    filter_condition: nil
+```
+
+At minimum, a configuration must include a `data` value. 
+For example, to generate pages with the default values from three different data files would look like:
+
+```
+page_gen:
+  - data: 'metadata_one'
+  - data: 'metadata_two'
+  - data: 'metadata_three'
+```
+
+For another example, to generate default Items pages from metadata, plus a set of "glossary" pages with non-standard configuration:
+
+```
+page_gen:
+  - data: 'object_metadata'
+  - data: 'collection_glossary'
+    template: 'terms'
+    name: 'slug'
+    dir: 'glossary'
+```
+
+Full configuration options:
+
+| option | use | default | notes |
+| --- | --- | --- | -- |
+| data | A file from _data to use to generate pages | `metadata` | A valid data file is required. Plugin warns if there is no match in _data and skips generation. |
+| template_location | Optionally set the folder inside of "_layouts" that contains the layouts used for these records. This helps keep the _layouts directory organized and simplifies values set in template and display_template. By default CB uses item layouts in "_layouts/item/" folder, thus the default template_location is `item`. If you want to add a new layout, it must be added to that folder. | `item` | The values of template and display_template will be appended after the template_location, i.e. they are assumed to be inside that folder. E.g. if template_location is `item`, the plugin will look for the template and display_template layouts in "_layouts/item/". If you want to use layout files from the root of _layouts, set template_location to `""` an empty string. |
+| template | Set the default layout to use for pages from _layouts in the template_location | `item` | The default layout file should exist to provide a fallback for items. Plugin warns if there is no match in _layouts. During generation if there is no valid matching layout, individual item generation will be skipped. |
+| display_template | Optionally set layout using a value from the individual record data, allowing you to have different layouts for each page. | `display_template` | Record values must match a valid layout. Fallback is to template value. |
+| name | The value from each record to use for output filename base (no extension). | `objectid` | A valid filename is required. Plugin skips record generation if value is blank or empty. Filenames are sanitized using Jekyll's `slugify` filter in pretty mode. CB pages assume objectid will be used for the name to create links between visualizations and item pages. |
+| dir | Folder to output the pages in _site. | `items` | The dir + name + extension will control the URL of the generated pages. For example, defaults items + objectid + .html will result in link something like "/items/demo_001.html". |
+| extension | File type to output, will generally be html. | `html` |  | 
+| filter | A data value to filter records on. If the record has an empty value, it will not be generated. | `objectid` | Since CB templates assume a valid objectid for every item in the collection to create links across the site, the records are filtered by objectid by default. |
+| filter_condition | A Ruby expression to filter data. | `nil` | |
+
+Note: defaults are set for *all* configuration options, so none are technically required when providing a config.
+If none is provided, they will fallback to the default.
+If an option is invalid, the plugin will usually catch it and provide an error message.
+Configuration issues and metadata errors will not interrupt normal Jekyll build process, however your site may not have item pages generated.
+Please check the terminal output for notices and errors from cb_page_gen.
+
+Filenames are created from the "name" option, which is a key in the data (i.e. a column in the csv).
+File extension (generally .html) is added during the process.
+The value in "name" is sanitized using the Jekyll filter slugify in "pretty" mode--this will downcase, replace all spaces and invalid url characters with `-`.
+This is important to ensure valid links and filenames across platforms and servers.
+If you are using CB's "objectid" convention, your values should already meet these requirements and will not be changed by sanitizing. 
+However, if your objectid contain odd characters (and are thus sanitized), links in the rest of the collection site may not point to the correct url.
+If for some reason you can not clean up your objectid field, you can  apply slugify filter to objectid in other page templates when calculating links to fix the issue.
+
+If customizing new Item types, it maybe helpful to tweak the "Default Settings" values in CollectionBuilderPageGenerator (as an alternative to passing configuration values).
+
+**Note:** CollectionBuilder originally used a modified version of [Adolfo Villafiorita jekyll-datapage_gen](https://github.com/avillafiorita/jekyll-datapage_gen), however, the plugin has been completely rewritten following the basic [Jekyll Generator Plugins](https://jekyllrb.com/docs/plugins/generators/).
+This allows CB Page Gen to more closely follow CB conventions, configuration options, and needs.
+Much of this is CB specific, such as providing metadata-centric defaults and fairly detailed error messages.
+However, the plugin configuration is still fully backwards compatible with older jekyll-datapage_gen configuration options (as used in CB projects). 
+If you used the old page gen plugin, your existing configuration should work with the new one.
+As of 2020, jekyll-datapage_gen added additional options that are *not* supported in CB Page Gen (index_files, name_expr, title, title_expr)--if you would like to use those options, you should still be able to swap in the newest version of jekyll-datapage_gen and delete cb_page_gen in your _plugins directory.
+
+-----------
+
+## CollectionBuilder Helpers
+
+"CollectionBuilder Helpers" ("cb_helpers.rb") provides helper functions to generate theme variables which are added to `site.data` for use in templates.
+The functions set defaults and calculate values in a much more efficient manner than using Liquid in template pages.
+This helps optimize built times for large collections.
+
+Current helpers include:
+
+- Featured Item -- reads `featured-image` from "theme.yml" and provides a `site.data.featured_item` object to the template at build. This allows you to get `featured_item.src`, `.alt`, and `.link`. Currently used to populate meta tags.
+- Theme Icons -- reads `icons` object in "theme.yml", sets icon defaults, processes icon svgs, and provides a `site.data.theme_icons` objects to the template at build. See "docs/icons.md" for details of use.
+
+------------
+
+## Array Count Uniq
+
+"Array Count Uniq" ("array_count_uniq.rb") provides a convenient Liquid filter to calculate the count of unique values in an array.
+The filter takes a Liquid array as input and returns an array of the unique values and their counts. 
+This allows you to quickly extract unique terms from large metadata files, which would take too long using Liquid alone.
+This is some what idiosyncratic to the needs of CollectionBuilder projects, used to efficiently generate Cloud pages and data derivatives.
+
+For example, used in a project like `{% assign unique_terms = myarray | array_count_uniq %}`, 
+will return an array like `[ ["term one",2], ["term two",6], ["term three",1]]`,
+which can then be used in further Liquid.

docs/rake_tasks.md

@@ -0,0 +1,33 @@
+# Rake
+
+[Rake](https://github.com/ruby/rake) is a task automation tool written in Ruby.
+It is a standard part of all Ruby installs, so if you are using Jekyll, you have it.
+Adding a "Rakefile" allows you to add commands to automate repetitive tasks.
+
+CollectionBuilder-CSV provides a "Rakefile" with tasks to help set up and deploy your digital collection.
+This allows you to run `rake` commands inside this repository.
+the use of each task is documented in "docs/rake_tasks/" folder. 
+The code for the individual rake tasks is contained in the folder "rakelib".
+
+The two most commonly used task are:
+
+## deploy
+
+`rake deploy`, is a short cut to run the full Jekyll command `JEKYLL_ENV=production bundle exec jekyll build`.
+Using the production environment causes template to include analytics and additional machine markup in build, which can take considerably longer than `jekyll s`.
+
+## generate_derivatives
+
+`rake generate_derivatives`, automates the creation of optimized, small and thumbnail images from all images and PDFs contained in the "objects/" directory in this repository. (Note: Optimization is not supported for Windows users.)
+It outputs the derivatives to "objects/small" and "objects/thumbs".
+Please ensure you have the requirements installed and available on the commandline before running!
+
+Requirements:
+
+- **ImageMagick**, [download](https://imagemagick.org/script/download.php)
+- **Ghostscript**, [download AGPL version](https://www.ghostscript.com/download/gsdnld.html) (required for processing PDF items)
+
+Check the doc file for full configuration options.
+
+Note: the image_optim Gem is used to optimize images using the optimization libraries provided by the image_optim_pack Gem. 
+However, image_optim_pack does not provide binaries for Windows, so optimization is skipped when using the rake task on Windows.

docs/rake_tasks/download_by_csv.md

@@ -0,0 +1,33 @@
+# download_by_csv
+
+`rake download_by_csv` allows you to download a list of files from a CSV using Wget.
+
+Please ensure you have Wget installed and available on your terminal!
+Check by typing `wget --version` in your terminal. 
+If you need to install on Windows, see [Add more to Git Bash](https://evanwill.github.io/_drafts/notes/gitbash-windows.html).
+
+Requirements:
+
+- wget
+
+Using defaults:
+
+- Create a CSV named "download.csv" with columns "url" (the full link to the objects you want to download) and "filename_new" (optional, the name you want to save/rename the downloaded objects as). Make sure it is UTF-8 (not from Excel). 
+- Put "download.csv" into the root of this repository (i.e. same place as the Rakefile).
+- Open terminal and type `rake download_by_csv`
+- Items included in the "download.csv" will be downloaded using wget, renamed, and output in new folder "download/".
+
+The options can be changed by passing arguments with the rake command.
+
+| option | description | default value |
+| --- | --- | --- |
+| csv_file | the filename of the CSV file used to rename | "download.csv" |
+| download_link | the column name that is the full link to the objects you want to download | "url" |
+| download_rename | the column name of the new filename for the downloads (optional, if you don't provide one, it will use what ever the url uses) | "filename_new" |
+| output_dir | the name of the new folder to download the files | "download/" |
+
+
+The order follows [:csv_file,:download_link,:download_rename,:output_dir].
+For example, 
+
+`rake download_by_csv["other_down.csv","item_link","new_name","download_folder"]`

docs/rake_tasks/generate_derivatives.md

@@ -0,0 +1,44 @@
+# generate_derivatives
+
+`rake generate_derivatives`, automates the creation of optimized, small and thumbnail images from all images and PDFs contained in the "objects/" directory in this repository. (Note: Optimization is not supported for Windows users.)
+It outputs the derivatives to "objects/small" and "objects/thumbs".
+Please ensure you have the requirements installed and available on the commandline before running!
+
+Requirements:
+
+- **ImageMagick**, [download](https://imagemagick.org/script/download.php)
+- **Ghostscript**, [download AGPL version](https://www.ghostscript.com/download/gsdnld.html)
+
+The following configuration options are available:
+
+| option | description | default value |
+| --- | --- | --- |
+| thumbs_size | the dimensions of the generated thumbnail images | 450x |
+| small_size | the dimensions of the generated small images | 800x800 |
+| density | the pixel density used to generate PDF thumbnails | 300 |
+| missing | whether to only generate derivatives that don't already exist | true |
+| compress_originals | Optimize the original image files | false |
+| input_dir | Input directory | objects |
+
+You can configure any or all of these options by specifying them in the rake command like so:
+
+```
+rake generate_derivatives[<thumb_size>,<small_size>,<density>,<missing>,<compress_originals>,<input_dir>]
+```
+
+Here's an example of overriding all of the option values:
+
+```
+rake generate_derivatives[100x100,300x300,70,false,false,'images']
+```
+
+It's also possible to specify individual options that you want to override, leaving the others at their defaults.
+For example, if you only wanted to set `density` to `70`, you can do:
+
+```
+rake generate_derivatives[,,70]
+```
+
+The mini_magick Gem is used to interface with ImageMagick so it supports both current version 7 and legacy versions (which are common on Linux). 
+The image_optim Gem is used to optimize images using the optimization libraries provided by the image_optim_pack Gem. 
+image_optim_pack does not provide binaries for Windows, so optimization is skipped when using the rake task on Windows.

docs/rake_tasks/rename_by_csv.md

@@ -0,0 +1,27 @@
+# rename_by_csv
+
+This task allows you to rename a batch of files using a spreadsheet.
+
+Using defaults: 
+
+- Create a CSV named "rename.csv" with the columns "filename_old" (the exact matching current filename, not including directory) and "filename_new" (the new name you want, not including directory). Make sure it is UTF-8 (not from Excel).
+- Put your files into the "objects" folder.
+- Put your "rename.csv" into the root of this repository (i.e. same place as the Rakefile).
+- Open terminal and type `rake rename_by_csv`
+- Items included in the "rename.csv" will be copied, renamed, and output in the new folder "renamed/". (nothing will be deleted!)
+
+The options can be changed by passing arguments with the rake command.
+
+| option | description | default value |
+| --- | --- | --- |
+| csv_file | the filename of the CSV file used to rename | "rename.csv" |
+| filename_current | the column name of the old filename | "filename_old" |
+| filename_new | the column name of the new filename | "filename_new" |
+| input_dir | the name of the folder containing the files to be renamed | "objects/" |
+| output_dir | the name of the new folder to put the renamed files | "renamed/" |
+
+
+The order follows [:csv_file,:filename_current,:filename_new,:input_dir,:output_dir].
+For example, 
+
+`rake rename_by_csv["other_rename.csv","old_name","new_name","raw_folder","new_folder"]`

docs/rake_tasks/rename_lowercase.md

@@ -0,0 +1,21 @@
+# rename_lowercase
+
+This task takes a folder of files and copies them to a new folder with all filenames downcased. 
+
+Using default:
+
+- Put your files into the "objects/" folder.
+- Open terminal and type `rake rename_lowercase`
+- All files in "objects/" will be copied, filenames converted to lowercase, and output to a new folder "renamed/". (nothing will be deleted!)
+
+
+| option | description | default value |
+| --- | --- | --- |
+| input_dir | the name of the folder containing the files to be renamed | "objects/" |
+| output_dir | the name of the new folder to put the renamed files | "renamed/" |
+
+
+The order follows [:input_dir,:output_dir].
+For example, 
+
+`rake rename_lowercase["raw_folder","new_folder"]`

docs/rake_tasks/resize_images.md

@@ -0,0 +1,30 @@
+# resize_images
+
+This task resizes all images (.jpeg, .jpg, .png, .tif, or .tiff) in a folder of files within this repository. 
+It outputs the resized images to a new folder in this repository, with all filenames and extensions lowercased, and optionally converted into another image format.
+
+Requirements:
+
+- **ImageMagick**, [download](https://imagemagick.org/script/download.php)
+
+Using defaults:
+
+- Put all images in the "objects/" folder.
+- run `rake resize_images` (images will be same format, resized to 3000 pixel max width and height while preserving aspect ratio)
+- All images will be output to "resized/" folder.
+
+The options can be changed by passing arguments with the rake command.
+
+| option | description | default value |
+| --- | --- | --- |
+| new_size | resizing parameter following [ImageMagick geometry conventions](https://imagemagick.org/script/command-line-processing.php#geometry) | '3000x3000' |
+| new_format | optionally change format of the image. Leave blank or provide a valid image extension starting with `.` (".jpg", ".png", ".tif") | false |
+| input_dir | folder containing all the images | 'objects' |
+| output_dir | folder to output the resized images | 'resized' |
+
+
+The order follows [:new_size, :new_format, :input_dir, :output_dir].
+For example, 
+
+`rake resize_images["5000x5000",".jpg","raw_folder","new_folder"]`
+

docs/tables.md

@@ -0,0 +1,34 @@
+# Table visualization
+
+Powered by DataTables, https://datatables.net/ 
+
+Using [DataTables Download](https://datatables.net/download/index), we package a variety of plugins/Extensions with the asset (Bootstrap 4 styling, Buttons + HTML5 export + JSZip, minified and concatenated).
+
+`_data/config-table.csv` provides the basic options. 
+The fields listed in the config will become the columns of the table, plus a link to the item which is automatically added.
+The link will be rendered as a hyperlink on the web table around the content of the first column, which will typically be "Title".
+The table will be sorted by the second column (typically "Date").
+
+The config-table options drive the creation of:
+
+- table viz page (`/data.html`)
+- `/assets/js/metadata.min.json` is the table data in an optimized format specifically intended for the consumption by the table viz page in this project. Each item is a list of values without keys and links are relative.
+
+Since the fields listed will become columns of the web table, it is best to not select too many. 
+The table will render well with about 3 to 5 fields.
+It will become too crowded with narrow columns if more are added.
+Typical columns are: title, date, description, subjects.
+With large collections, avoid fields with lots of text, as this will make the json data slow to load.
+
+DataTables is set up in `/_includes/js/table-js.html`. 
+It loads `metadata.min.json` using ajax which optimizes initial page load time. 
+Options are set to optimize for very large data sets (deferRender, paging). 
+We have had success with over 90,000 items.
+Usability is mainly limited by load time of the metadata json (which may get to be > 3MB).
+
+DataTables Buttons extension with HTML5 Export and JSZip is used to add download/export buttons to the web table. 
+Clicking the CSV or Excel button will export the current subset of metadata displayed on the web table. 
+The export will automatically include a Link column with full link to the 
+
+Note: since this table is a small subset of metadata fields, the `/assets/data/metadata.csv` and `/assets/data/metadata.json` data download is driven by the `site.data.theme.metadata-export-fields` rather than table config. 
+This means the CSV/JSON download can be more complete, containing more fields than are displayed anywhere on the site.

docs/youtube.md

@@ -0,0 +1,39 @@
+# YouTube
+
+YouTube items are supported in Item pages via the `video` "display_template". 
+Provide the full YouTube video link in "object_location" field. 
+Use the API recipes below to fill in the "image_small" and "image_thumb" fields if desired.
+
+## Item page
+
+The default `video` display_template will display the video embedded in an [YouTube Player iframe](https://developers.google.com/youtube/iframe_api_reference). 
+It is styled using [Bootstrap ratio class](https://getbootstrap.com/docs/5.1/helpers/ratio/), set as 16x9 ratio (which is default for YouTube, however, if your videos differ significantly from that ratio try modifying the class in _includes/item/video-embed.html).
+The embed is given these options:
+
+- Privacy-enhanced mode: does not send data to YouTube unless users click play (enabled by using domain `www.youtube-nocookie.com` rather than `www.youtube.com`
+- Related videos: the option `rel=0` asks YouTube to not show related videos. However, YouTube changed this option in 2018 and may still show related videos from the same channel.
+- Modest branding: the option `modestbranding=1` removes some YouTube branding from the iframe player. 
+
+## Item images 
+
+The YouTube image API is not well documented by Google, but is used by many sites and js libraries.
+
+Basically, you can get four sizes of the default thumbnail, or four smaller thumbnails from different points in the video.
+You can use the domain "img.youtube.com" or "i3.ytimg.com"
+
+Default images:
+
+- thumb 120x90, https://img.youtube.com/vi/{{ youtubeid }}/default.jpg
+- medium quality 320x180, https://img.youtube.com/vi/{{ youtubeid }}/mqdefault.jpg
+- high quality 480x360, https://img.youtube.com/vi/{{ youtubeid }}/hqdefault.jpg 
+- SD 640x480 (not available for all videos), https://img.youtube.com/vi/{{ youtubeid }}/sddefault.jpg
+- max quality 1280×720 (or 1920x1080?, not available for all videos), https://img.youtube.com/vi/{{ youtubeid }}/maxresdefault.jpg 
+
+Auto thumbs:
+
+- default thumb, 480x360, https://img.youtube.com/vi/{{ youtubeid }}/0.jpg 
+- alternate 120x90, https://img.youtube.com/vi/{{ page.youtubeid }}/1.jpg 
+- alternate 120x90, https://img.youtube.com/vi/{{ page.youtubeid }}/2.jpg 
+- alternate 120x90, https://img.youtube.com/vi/{{ page.youtubeid }}/3.jpg
+
+For more control, you can use [YouTube Data API](https://developers.google.com/youtube/v3/), but it requires a key to access.