diff --git a/README.md b/README.md index 2feec93..f36aa81 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Documentation for CollectionBuilder, an open source tool for creating digital collection and exhibit websites that are driven by metadata and powered by modern static web technology. -This documentation covers details for CollectionBuilder-GH, CollectionBuilder-CONTENTdm, and CollectionBuilder-CSV. +This documentation covers details for CollectionBuilder-GH, CollectionBuilder-Sheets, and CollectionBuilder-CSV. If you need to get in touch, feel free to email the CollectionBuilder Team () or use the [CollectionBuilder Discussion Forum](https://github.com/orgs/CollectionBuilder/discussions). diff --git a/_change-log/cb-cdm-done.md b/_change-log/cb-cdm-done.md new file mode 100644 index 0000000..03f5ad5 --- /dev/null +++ b/_change-log/cb-cdm-done.md @@ -0,0 +1,11 @@ +--- +title: CollectionBuilder-CONTENTdm Deprecated, use CSV! +release: 2023-11-03 +--- + +The CollectionBuilder-CONTENTdm template has been fully deprecated. +CB-CDM has not been actively developed for years, and use cases are better served by the more powerful and flexible [CollectionBuilder-CSV](https://github.com/CollectionBuilder/collectionbuilder-csv). +Details specific to CB-CDM have been removed from the main cb-docs (see [Legacy Docs](/cb-docs/docs/legacy/) for reference). + +*Existing projects using CB-CDM will continue to work fine!* +However, for all new projects please use CollectionBuilder-CSV. diff --git a/_change-log/cb-sa-done.md b/_change-log/cb-sa-done.md index 3633699..7c7b1e3 100644 --- a/_change-log/cb-sa-done.md +++ b/_change-log/cb-sa-done.md @@ -1,9 +1,9 @@ --- -title: CollectionBuilder-SA Depreciated, use CSV! +title: CollectionBuilder-SA Deprecated, use CSV! release: 2021-11-04 --- -The CollectionBuilder-SA template has been depreciated. +The CollectionBuilder-SA template has been deprecated. The concepts and use case it represents have been migrated into the more powerful and flexible [CollectionBuilder-CSV](https://github.com/CollectionBuilder/collectionbuilder-csv). Details specific to CB-SA will be removed from cb-docs. diff --git a/docs/advanced/architecture-overview.md b/docs/advanced/architecture-overview.md index 4d462bf..83fc8b8 100644 --- a/docs/advanced/architecture-overview.md +++ b/docs/advanced/architecture-overview.md @@ -15,7 +15,7 @@ This section provides a high-level overview of files and folders as they are use | `_data/` | The [Jekyll data](https://jekyllrb.com/docs/datafiles/) folder contains CSVs and YAML that can be accessed by the template to build the site. In CB "_data/" will contain your metadata CSV, the "config-" CSVs that set options for visualization pages, and "theme.yml" that sets some overall configurations. | | `_includes/` | The [Jekyll includes](https://jekyllrb.com/docs/includes/) folder contains modular chunks of HTML and JS that are used by pages and layouts to generate content on the site. Most users will not need to edit these files, but please refer to the [CB Includes](#cb-includes) section below for more detailed information. | | `_layouts/` | The [Jekyll layouts](https://jekyllrb.com/docs/layouts/) folder contains HTML templates used to build all the pages on the site. CB users may want to tweak some layouts, such as ["home-infographic.html"]({{ '/docs/pages/home/' | relative_url }}), to control how pages look. In CB-CSV the folder "_layouts/item/" contains the layouts that match the `display_template` used by collection items. All layouts ultimately use the "default.html" layout, which pulls together the full page structure including head, banner, nav, footer, and javascript. | -| `_plugins/` | The [Jekyll plugins](https://jekyllrb.com/docs/plugins/) folder contains extensions to Jekyll written in Ruby. CB-CSV and CB-CONTENTdm come with [custom CB plugins](https://github.com/CollectionBuilder/collectionbuilder-csv/blob/main/docs/plugins.md) that are required to build item pages and efficiently process metadata. | +| `_plugins/` | The [Jekyll plugins](https://jekyllrb.com/docs/plugins/) folder contains extensions to Jekyll written in Ruby. CB-CSV comes with [custom CB plugins](https://github.com/CollectionBuilder/collectionbuilder-csv/blob/main/docs/plugins.md) that are required to build item pages and efficiently process metadata. | | `_sass/` | Contains "Sass partials", modular chunks of [Sass](https://sass-lang.com/) CSS. These partials are pulled into the file "assets/css/cb.scss" when the website is built, adding CB specific styles. Users can add custom CSS that will override all Bootstrap and CB styles by editing the "_custom.scss" file. In general the other partials should not be edited. | | `_site/` | Contains the full static site output by Jekyll on your local machine. This folder is ignored by Git, since it should not be committed to your project--so you will not see it on GitHub. After doing a `rake deploy` or `jekyll build`, the contents "_site" can be copied to a web hosting location. This is done automatically by [online deployment services]({{ '/docs/deploy/' | relative_url }}) such as GitHub Pages, Actions, or Render. | | `.github/` | This folder is for special files used on GitHub to configure platform features. The contents aren't a necessary part of CB, but just relate to GitHub. For example, this is where you would add a GitHub Action yml file. In CB-CSV it contains template files for Issues and PRs--you can delete those in your project if desired! | diff --git a/docs/config/collection.md b/docs/config/collection.md index e75a1d5..7388db5 100644 --- a/docs/config/collection.md +++ b/docs/config/collection.md @@ -21,29 +21,9 @@ metadata: boxing ------ -## Required Settings for CONTENTdm - -### cdm-collection-id: - -- The "collection alias" of your CONTENTdm collection -- The alias is a path assigned by CONTENTdm and can be found in CONTENTdm Admin on the Collections > Profile page, or by looking at the URL of the collection on the web. For example "https://cdm17254.contentdm.oclc.org/digital/collection/ui_ep/search" the collection alias is given after "/collection/", so would be `ui_ep`. -```yaml -cdm-collection-id: boxing -``` - -### cdm-url: - -- The full url for your public CONTENTdm instance (*with NO trailing slash!*). -- Generally these follow the pattern "https://cdm" + a number + ".contentdm.oclc.org", although custom domains should also work. However, your CDM admin interface url (starting with "server", e.g. https://server12345.contentdm.oclc.org) will not work. -```yaml -cdm-url: https://cdm12345.contentdm.oclc.org -``` - ------- - ## Optional Page Generation Settings -CollectionBuilder-CONTENTdm and -CSV use a custom Jekyll plugin to generate individual HTML pages for each item (row) in your metadata CSV. +CollectionBuilder-CSV uses a custom Jekyll plugin to generate individual HTML pages for each item (row) in your metadata CSV. By default, the "CollectionBuilder Page Generator" plugin needs no additional configuration--it will automatically use the value set in `metadata` to generate pages. In advanced use cases, you may want to tweak the CB defaults or generate pages from more than one data file. diff --git a/docs/customization/config-metadata.md b/docs/customization/config-metadata.md index 9859673..db48d72 100644 --- a/docs/customization/config-metadata.md +++ b/docs/customization/config-metadata.md @@ -28,7 +28,7 @@ The columns are described below, and an [example](#example) is provided for your ------ -The following two options are used by **CDM and CSV only**, and are not necessary to make the collection itself work and will not affect the display. +The following two options are used by **CSV only**, and are not necessary to make the collection itself work and will not affect the display. However, configuring these options adds rich machine readable markup to each item page, making your objects more discoverable by search engines. ### dc_map: diff --git a/docs/deploy/actions.md b/docs/deploy/actions.md index 62c8804..b6d69b0 100644 --- a/docs/deploy/actions.md +++ b/docs/deploy/actions.md @@ -7,7 +7,7 @@ nav_order: 4 # GitHub Actions GitHub Pages' default build process runs an older version of Jekyll and does not support plugins (see [dependency versions](https://pages.github.com/versions/) for details). -Since CB-CDM and CB-CSV use custom CollectionBuilder plugins to generate item pages and process data, they can not be built using the default GitHub Pages process. +Since CB-CSV uses custom CollectionBuilder plugins to generate item pages and process data, they can not be built using the default GitHub Pages process. However, you *can* still host your site on GitHub Pages by setting up an alternative build using the [GitHub Actions](https://docs.github.com/en/actions) feature. GitHub has recently made setting up Actions to build your site easier, so this is a great option. diff --git a/docs/deploy/build.md b/docs/deploy/build.md index 8e79f34..adec90d 100644 --- a/docs/deploy/build.md +++ b/docs/deploy/build.md @@ -6,7 +6,7 @@ nav_order: 2 # Building Your Site -The most common way to build your CB-CDM or CB-CSV site is to use Jekyll on your local computer (which can also be done with CB-GH if desired!). +The most common way to build your CB-CSV site is to use Jekyll on your local computer (which can also be done with CB-GH if desired!). Jekyll build is a bit different than [using the development server]({{ '/docs/repository/generate/' | relative_url }}) because it outputs all the URLs used in the site to match your final deployment location based on your [configuration options]({{ '/docs/config/url/' | relative_url }}). The build version will include real URLs, swapping out the development links starting with `http://localhost:4000/` used by `jekyll s` with the production url value you have configured, e.g. `https://example.org`. @@ -39,7 +39,7 @@ For static servers, some common options include: - **cPanel:** many hosts (such as Reclaim) provide cPanel as a web based interface to your server. Click on "File Manager" to upload files via the web interface. Your server will generally have a folder named something like "public_html" that represents the root of your website. *Tip:* If you don't have a server, it is possible to build and host all CB projects via GitHub Pages. -This can work well for CB-CDM since there are no objects to host. +This works well if your objects are hosted elsewhere since you won't encounter size limits in your repository. Check [GitHub Actions]({{ '/docs/deploy/actions/' | relative_url }}) and [Third party build services]({{ '/docs/deploy/thirdparty/' | relative_url }}) for more info. {:.alert .alert-yellow} diff --git a/docs/deploy/index.md b/docs/deploy/index.md index f0439e2..2ffa6e2 100644 --- a/docs/deploy/index.md +++ b/docs/deploy/index.md @@ -10,5 +10,5 @@ Depending on the version of CollectionBuilder you're using and where you would l - **Deploy using the free [GitHub Pages]({{ '/docs/deploy/gh-pages/' | relative_url }})** - this is how most **GH** and **Sheets** users deploy their sites. - **[Build the site with Jekyll]({{ '/docs/deploy/build/' | relative_url }})**, then move the files to a web server: This allows for the publishing of CollectionBuilder sites on your own or your organizations web servers. -- **[Enable GitHub Pages publishing via GitHub Actions]({{ '/docs/deploy/actions/' | relative_url }})** - These features now make publishing **CDM** and **CSV** sites freely on GitHub a fairly easy possibility. +- **[Enable GitHub Pages publishing via GitHub Actions]({{ '/docs/deploy/actions/' | relative_url }})** - These features now make publishing **CSV** sites freely on GitHub a fairly easy possibility. - **[Use Third-Party Build Services]({{ '/docs/deploy/thirdparty/' | relative_url }})** documented in this section that provide other flexible deployment solutions. diff --git a/docs/deploy/thirdparty.md b/docs/deploy/thirdparty.md index 8f21241..0b91d83 100644 --- a/docs/deploy/thirdparty.md +++ b/docs/deploy/thirdparty.md @@ -7,7 +7,7 @@ nav_order: 5 # Deploy via Third Party Services A variety of third party cloud hosting companies can integrate with GitHub to build and host your static site, often free of charge. -This option is most useful for CSV and CDM users looking for an automated build process as an alternative to GitHub Pages. +This option is most useful for CSV users looking for an automated build process as an alternative to GitHub Pages. The biggest players are Cloudflare, Netlify, and Render. This tutorial covers using [Render](https://render.com/), since we've found it to be free and easy to use. diff --git a/docs/objects/cdm-objects.md b/docs/legacy/cdm-objects.md similarity index 98% rename from docs/objects/cdm-objects.md rename to docs/legacy/cdm-objects.md index bd1f4cc..929dd89 100644 --- a/docs/objects/cdm-objects.md +++ b/docs/legacy/cdm-objects.md @@ -1,7 +1,7 @@ --- title: Objects using CONTENTdm -parent: Objects -nav_order: 3 +parent: Legacy Docs +nav_order: 2 --- # Collection Objects Using CONTENTdm diff --git a/docs/legacy/cdm_config.md b/docs/legacy/cdm_config.md new file mode 100644 index 0000000..ec20cbf --- /dev/null +++ b/docs/legacy/cdm_config.md @@ -0,0 +1,65 @@ +--- +title: CONTENTdm Config and Theme options +parent: Legacy Docs +nav_order: 3 +--- + +# _config.yml values + +## Required Settings for CONTENTdm + +### cdm-collection-id: + +- The "collection alias" of your CONTENTdm collection +- The alias is a path assigned by CONTENTdm and can be found in CONTENTdm Admin on the Collections > Profile page, or by looking at the URL of the collection on the web. For example "https://cdm17254.contentdm.oclc.org/digital/collection/ui_ep/search" the collection alias is given after "/collection/", so would be `ui_ep`. +```yaml +cdm-collection-id: boxing +``` + +### cdm-url: + +- The full url for your public CONTENTdm instance (*with NO trailing slash!*). +- Generally these follow the pattern "https://cdm" + a number + ".contentdm.oclc.org", although custom domains should also work. However, your CDM admin interface url (starting with "server", e.g. https://server12345.contentdm.oclc.org) will not work. +```yaml +cdm-url: https://cdm12345.contentdm.oclc.org +``` + +------------------- + +# theme.yml values + +This section of "_data/theme.yml" configures advanced options such as image and font size, and Bootstrap themes. +This is an optional section—-your site will work just fine without adjusting these variables, but they're available if you'd like the extra options for customization. + +## CDM image % for IIIF: + +**CDM-Users only**: This is a *CONTENTdm-specific* variable section for adjusting size of images used throughout the site. +CollectionBuilder uses the [IIIF Image API](https://help.oclc.org/Metadata_Services/CONTENTdm/Advanced_website_customization/API_Reference/IIIF_API_reference){:target="_blank" rel="noopener"} to retrieve images using a percentage size option. +The percentage must be 10% or greater. + +### image-percentage-large: + +- Default `70` + +```yaml +image-percentage-large: 50 +``` + +### image-percentage-medium: + +- Default `40` + +```yaml +image-percentage-medium: 30 +``` + +### image-percentage-small: + +- Default `20` + +```yaml +image-percentage-small: 10 +``` + +{:.alert .alert-green} +**Pro Tip:** If your images are appearing blurry or take too long to load, try adjusting the image-sizing settings. The appropriate percentage depends on the full size of images contained in your CDM repository and may require some experimentation. diff --git a/docs/metadata/cdm_metadata.md b/docs/legacy/cdm_metadata.md similarity index 99% rename from docs/metadata/cdm_metadata.md rename to docs/legacy/cdm_metadata.md index e3cb801..1821359 100644 --- a/docs/metadata/cdm_metadata.md +++ b/docs/legacy/cdm_metadata.md @@ -1,7 +1,7 @@ --- title: CONTENTdm Metadata -parent: Metadata -nav_order: 3 +parent: Legacy Docs +nav_order: 1 --- # CollectionBuilder-CONTENTdm Metadata diff --git a/docs/legacy/index.md b/docs/legacy/index.md new file mode 100644 index 0000000..01c743c --- /dev/null +++ b/docs/legacy/index.md @@ -0,0 +1,9 @@ +--- +title: Legacy Docs +has_children: true +nav_order: 99 +--- + +# Legacy Docs + +This section preserves access to some documentation from deprecated templates. diff --git a/docs/metadata/uploading.md b/docs/metadata/uploading.md index 943eeee..5c10366 100644 --- a/docs/metadata/uploading.md +++ b/docs/metadata/uploading.md @@ -7,7 +7,7 @@ nav_order: 7 # Add Your Metadata Once your metadata is ready, you'll want to add it to your project repository so CollectionBuilder can put it to use. -This can be done either by uploading via the GitHub web interface (most **GH** users) or by adding it to your local repository folder (most **CSV/CDM** users). +This can be done either by uploading via the GitHub web interface (most **GH** users) or by adding it to your local repository folder (most **CSV** users). This section provides the steps to do it! ## Prepare Metadata File @@ -29,7 +29,7 @@ To download your metadata from Google Sheets: ## Add Metadata to Project With a properly formatted and named CSV in hand, you are ready to add your metadata to your CollectionBuilder project. -This can be done either by uploading via the GitHub web interface (most **GH** users) or by adding it to your local repository folder (most **CSV/CDM** users). +This can be done either by uploading via the GitHub web interface (most **GH** users) or by adding it to your local repository folder (most **CSV** users). ### Upload via GitHub Web interface diff --git a/docs/quickstart.md b/docs/quickstart.md index 5c6767b..aa22a84 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -18,18 +18,3 @@ Instructions below provide the *way too fast* steps to creating a collection. 6. Edit the "_config.yml" with your site information. 7. Activate GitHub Pages for the repository. 8. Check out your site via the link provided on your repository's settings page! - -## CollectionBuilder-CONTENTdm - -1. Make sure you have Git, Ruby, Jekyll, and a text editor installed on your computer. -2. Create a new project repository using the [CollectionBuilder-CONTENTdm](https://github.com/CollectionBuilder/collectionbuilder-contentdm) template by clicking the "Use this template" button. -3. Clone your repository to your local computer. -4. Check the [Metadata Template](https://docs.google.com/spreadsheets/d/14iWUEoAJ6T9WDqlPnIHRN7M8-YgmMV4_bjFPVuSZ0yk/copy?usp=sharing). -5. Export your collection metadata from CONTENTdm (CDM Admin > Collections > Export), using the "Tab-delimited" option with the "Return field names in first record" option checked. -6. Transform your CDM metadata using OpenRefine or Google Sheets to include the fields required by CollectionBuilder. -7. Save/export your metadata as a CSV and copy into the "_data" folder of your repository. -8. Edit the "_config.yml" with your site and CDM information. -9. Open up a terminal in your directory and type `bundle exec jekyll s` to serve up your website on a local dev server. -10. Finish customizing your site with "theme.yml" and other config CSVs. -11. To build for deployment, use command `rake deploy`. -12. Open up the "_site" folder, copy all contents to your web server! diff --git a/docs/repository/create.md b/docs/repository/create.md index b6d4d14..7bee558 100644 --- a/docs/repository/create.md +++ b/docs/repository/create.md @@ -15,8 +15,8 @@ The best/fastest way to do this is to visit a CollectionBuilder repository on Gi 2. Visit the repository corresponding to the template you are using: - **GH (GitHub Pages):** {:target="_blank"} - **CSV:** {:target="_blank"} - - **CONTENTdm:** {:target="_blank"} -3. On the repository home page, click the green "Use This Template" button (appears on right side above the code area). + - **Sheets:** {:target="_blank"} +3. On the repository home page, click the green "Use This Template" button (appears on right side above the code area) and select "Create a new repository". 4. This brings you to a "Create a new repository" page. Fill out using these options: 1. **Repository name**: Use a lowercase name without spaces or odd characters. We often append `_source` or `_draft` to our projects to keep track of the status. If you are using GH, this name will become part of your site URL, so think through how it will look as a link! 2. Most users should choose "Public" repository. If you are hosting on GitHub Pages it *must* be public unless you upgrade to a paid account. diff --git a/docs/software/optional.md b/docs/software/optional.md index 9fc02b3..3620cf4 100644 --- a/docs/software/optional.md +++ b/docs/software/optional.md @@ -7,7 +7,7 @@ nav_order: 8 # Optional Software {:.alert .alert-blue } -Software in this section is optional and **will not be used by CollectionBuilder-GH or -CONTENTdm projects**. +Software in this section is optional and **will not be used by CollectionBuilder-GH or -Sheets projects**. If you want to use Rake tasks to batch process PDF and image files for **CollectionBuilder-CSV**, this software is required! Most (*but not all!*) CollectionBuilder projects will involve working with a collection of digital objects, i.e. JPEGs, PDFs, MP3s, etc. diff --git a/docs/templates.md b/docs/templates.md index 9a5d2e5..76aa88c 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -14,9 +14,9 @@ There are a few steps where the documentation does vary between templates, howev The templates are currently: -- **GH** - for [CollectionBuilder-GH](https://github.com/CollectionBuilder/collectionbuilder-gh), a lightweight learning-focused template designed for free hosting on GitHub Pages. This is a great option for learning, teaching, quick prototyping, or just testing! A complete collection can be built without installing anything using the GitHub web interface. - **CSV** - for [CollectionBuilder-CSV](https://github.com/CollectionBuilder/collectionbuilder-csv), a robust template for developing exhibits on your local computer (and serving them from anywhere!). CSV is flexible and highly customizable, able to accommodate a wide variety of project types. -- **CDM** - for [CollectionBuilder-CONTENTdm](https://github.com/CollectionBuilder/collectionbuilder-contentdm), a template for generating a "skin" over an existing CONTENTdm repository - *this is a **legacy** template, in general it will be better to use CB-CSV for starting new projects!* +- **GH** - for [CollectionBuilder-GH](https://github.com/CollectionBuilder/collectionbuilder-gh), a lightweight learning-focused template designed for free hosting on GitHub Pages. This is a great option for learning, teaching, quick prototyping, or just testing! A complete collection can be built without installing anything using the GitHub web interface. +- **Sheets** - for [CollectionBuilder-Sheets](https://github.com/CollectionBuilder/collectionbuilder-sheets), a minimal template designed for loading collection metadata directly from a CSV (such as a published Google Sheet!). This enables live collaboration to prototype collections with minimal set up and unique learning experiences. For technical details about what is inside a template, check [Overview of Template Structure]({{ '/docs/advanced/architecture-overview/' | relative_url }}). diff --git a/docs/theme/advanced.md b/docs/theme/advanced.md index e1ad01e..ae7b0a0 100644 --- a/docs/theme/advanced.md +++ b/docs/theme/advanced.md @@ -9,39 +9,6 @@ nav_order: 11 This section of "_data/theme.yml" configures advanced options such as image and font size, and Bootstrap themes. This is an optional section—-your site will work just fine without adjusting these variables, but they're available if you'd like the extra options for customization. -## CDM image % for IIIF: - -**CDM-Users only**: This is a *CONTENTdm-specific* variable section for adjusting size of images used throughout the site. -CollectionBuilder uses the [IIIF Image API](https://help.oclc.org/Metadata_Services/CONTENTdm/Advanced_website_customization/API_Reference/IIIF_API_reference){:target="_blank" rel="noopener"} to retrieve images using a percentage size option. -The percentage must be 10% or greater. - -### image-percentage-large: - -- Default `70` - -```yaml -image-percentage-large: 50 -``` - -### image-percentage-medium: - -- Default `40` - -```yaml -image-percentage-medium: 30 -``` - -### image-percentage-small: - -- Default `20` - -```yaml -image-percentage-small: 10 -``` - -{:.alert .alert-green} -**Pro Tip:** If your images are appearing blurry or take too long to load, try adjusting the image-sizing settings. The appropriate percentage depends on the full size of images contained in your CDM repository and may require some experimentation. - ------ ## Navbar Options: diff --git a/docs/theme/data.md b/docs/theme/data.md index 550e820..a3af71b 100644 --- a/docs/theme/data.md +++ b/docs/theme/data.md @@ -16,7 +16,7 @@ For instance, we often use the "facets.json" file to determine which fields shou - This variable determines what metadata will be made available for download via the 'Download Data' options on the Home page and on the Data page. - Format: Comma-delimited list contained between quotes ```yaml -metadata-export-fields: "title,description,subject,date,date is approximate,source,latitude,longitude,subject (lcsh),format-original,donor,identifier,format,language,type,rights,rightsstatement,cdmid,objectid" +metadata-export-fields: "title,description,subject,date,date is approximate,source,latitude,longitude,subject (lcsh),format-original,donor,identifier,format,language,type,rights,rightsstatement" ``` {:.alert .alert-green}