Link Search Menu Expand Document

CollectionBuilder

Glossary of Terms

Below are some important concepts, software, standards, and other things you might encounter in these Docs and working with CollectionBuilder.

Bootstrap

https://getbootstrap.com/

Described as “the world’s most popular framework for building responsive, mobile-first sites”, Bootstrap is a package of CSS and JS that provides grid, layout, and UI components that can be used to quickly build and style a responsive website.

CollectionBuilder currently uses version 5.1 as a base. This allows you to use Bootstrap columns, components, and utilities to customize your pages.

Resources:

Bundler

https://bundler.io/

Bundler is a utility to manage dependencies for Ruby projects. It is used to install, record, and manage the specific versions of Ruby Gems used on a per project basis.

Since Jekyll is a very complex Gem with many dependencies, they recommend using Bundler to keep everything in working order. When you start a new CollectionBuilder project, you will use Bundler to record your working development environment so that it can be reproduced on other computers to avoid breakage due to updates in dependencies.

Bundler terms:

  • “Gemfile” records the Gems required for your project (the requirements for CollectionBuilder are just Jekyll!).
  • “Gemfile.lock” records all the Gems and their specific versions that are used in your project so that the environment can be reproduced.
  • bundle install is used the first time you use a project on your computer to install the requirements listed in the “Gemfile” and “Gemfile.lock”. This will set up a “bundle” of Gems matching the requirements separate from other versions of the same Gem installed on your system.
  • bundle exec is used as prefix to all commands given in your project repository so that they are run using the bundle’s Gems, rather than other versions on your system.

Git

https://git-scm.com/

Git is a popular free, distributed version control system originally developed for coordinating huge software development projects. However, it is fast and flexible enough to be used on any scale project, from your personal notes to your research lab’s code–and offers many benefits beyond “track changes”. Git can be used on your personal computer, or by online services to track the development of a project

Git tracks the history of changes in a folder of files, called a Git “repository” or “repo”. Git captures a snapshot of your project each time you “commit”. Then it permanently stores this series of snapshots as your project’s history. Try to think of your changes as separate from the document itself. The current file that you see in your folder is made up of a specific set of those changes, while the complete history of your project is safely stored in a hidden “.git” directory.

Each commit records the creator, email, message, and changes made, providing transparency and credit for your project, as well as, checksums to ensure no information can be lost or corrupted without detection. Unlike “track changes”, this history stays with the repository permanently.

Git is distributed meaning every copy of a repository contains the complete history. This is great for collaboration, fast performance, and offline usage. Git can efficiently branch, diff, and automatically merge different sets of changes together, enabling people to work in parallel and sync their files.

Resources:

GitHub

https://github.com/

GitHub is a popular web platform for hosting Git repositories–i.e. a place to store and sync your project files online. Think of it as Google Drive for code with super robust “track changes” baked in. Built around the powerful version control of Git, it provides a handy web interface for managing, editing, and collaborating on repositories.

Originally designed to manage large open-source software projects, GitHub’s use has expanded to many other types of organizations and individuals, with over 40 million users. GitHub provides a bunch of built in project management features and services such as GitHub Actions (workflow automation) and GitHub Pages (static hosting).

To create a CollectionBuilder project you will need to set up a free account https://github.com and verify your email.

Check out these resources:

Please note that there are other version control systems (Subversion, mercurial, etc) and repository hosts (Bitbucket, GitLab, etc) out there… However, Git and GitHub are by far the most popular.

GitHub Organizations

https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/about-organizations

A GitHub organization is a useful tool to collaborate with a group and/or to brand, organize, and manage a set of related repositories. Orgs can help ensure continuity in situations when members may move on from a project or lab. Or can be used just to provide a custom branded domain name for a project.

GitHub organizations are NOT a separate account, but are a group of users, i.e. you can’t log in as an Org. One or more persons can be the Owner with full admin control over the org including managing members.

To start an organization, click the plus sign icon on the upper right of the GitHub menu bar and select “Create organization”. Choose the “Free” account option, then give your org a good name (preferably lowercase with no spaces, since this will be used for your URLs). Once created, add members using their GitHub account names!

When creating a new repository, all members can use the “owner” dropdown option to create the repository under the organization (instead of their own account). Repositories owned by the Org will be accessible and managed by the Owner accounts. They stay with the Org even if the original creator leaves the Org. Org repositories also enable more levels of access control than personal repos, which is especially important when working with collaborators.

GitHub Pages

https://pages.github.com/

GitHub Pages is free static web hosting service available as part of every GitHub repository–this means with the click of a button you can fire up a new website!

Intended to host relatively simple sites for your GitHub portfolio or project documentation, GitHub Pages is an ideal solution for creating an open educational resource or personal site to highlight your academic work. Because hosting through gh-pages is free and builds valuable transferable skills, this is a great option for teaching and learning. Users have the opportunity to become creators and participants in global digital culture, developing critical digital literacy about the fabric of the web.

Many organizations and individuals are using GitHub to collaboratively create and publish public websites. For example, Programming Historian, The Carpentries, or this site!

Resources:

HTML

HTML is the building blocks of the web! CollectionBuilder uses modular components of written in HTML which are pulled together by Jekyll to generate the pages you see on the server.

Resources:

Jekyll

https://jekyllrb.com/

Jekyll is one of the most popular and actively developed static site generators, in part because of its direct integration with GitHub Pages. Originally focused on creating simple blogs from Markdown files, it has developed into a fully featured generator used on all types of web projects from tiny to huge (browse the Showcase).

Jekyll is written in the programming language Ruby and is installed on your computer as a Ruby Gem. However, you don’t need to know anything about Ruby to get started using it!

Liquid

https://shopify.github.io/liquid/

Liquid is a flexible template language. In Jekyll it allows you to layout pages built from modular components and data, using the “_includes”, “_layouts”, and “_data” directories. Liquid includes features such as operators, loops, and filters to manipulate raw content. Liquid statements are enclosed by {% %} and variables in {{ }}.

Resources:

  • Jekyll’s Liquid docs (Note: Jekyll provides some enhancements to Liquid that are not part of the standard spec)
  • Liquid documentation (Note: these Liquid docs are for the most basic version. Some enhanced features are described in the Shopify Liquid Reference, however, these docs are focused on the Shopify platform and may not apply to Jekyll’s implementation)

Markdown

https://daringfireball.net/projects/markdown/

Markdown is a standard to simplify writing content for the web. Considered a “lightweight” markup language, it provides a set of conventions to create documents in plain text that can be converted into HTML. The basics are intuitive, modeled after how you might naturally write an email, and are intended to be easy to read for a human (compared to HTML source code!).

Markdown comes in different “flavors” that provide additional features. GitHub flavored markdown (GFM) can be used any where on GitHub and in Jekyll.

Markdown parsers read your Markdown code and output HTML (or other formats), and may also extend the syntax options. Jekyll uses the Ruby based kramdown to compile Markdown in HTML, which supports extra features such as attribute lists.

Resources:

Ruby

https://www.ruby-lang.org/

Ruby is a modern programming language popular with web applications.

You do not need to know anything about Ruby, but you do need it to run Jekyll–and thus CollectionBuilder–on your system!

Like other programming languages, Ruby can be extended by adding 3rd party libraries that can add functionality, features, or software to your system. In the Ruby ecosystem these packages of code are called “Gems”. The command gem is used to install and manage Gems on your computer.

CollectionBuilder uses two main Gems, Jekyll and Bundler–these are pieces of software written in Ruby, that are installed using gem.

Resources:

SASS

http://sass-lang.com/

Sass is a CSS extension / preprocessor. All normal CSS is valid SCSS, but Sass adds many powerful functions and programmatic features.

Writing SCSS is often easier and more sensible, for example by supporting nesting, variables, and operators. Jekyll lets you write SASS in modular chucks called partials, in the “_sass” directory, that will be combined and compiled into normal CSS files when the site is built.

Check the Sass Guide to learn more.

YAML

http://www.yaml.org/

YAML is a “human readable” plain text data format. It is used in Jekyll for configuration, site data, and Front matter.

In CollectionBuilder, YAML is used for configuration in “_config.yml” and “_data/theme.yml”. All options are basic key value pairs. Each pair is on its own line, following the pattern key + colon + space + value. Putting quotes around the value is optional, unless it contains a colon or line breaks.

Comments are added using a hash #. Anything after a # on a line is ignored in processing–so it is just notes to other humans!

For example:

# an example comment line
example_key: An Example Value
another_key: "A value with a colon: so it must be quoted"