Overview:

The ELIXIR toolkit theme is a Jekyll theme designed to support easy deployment of documentation websites, as well as more complex websites that require a central tool table and linking towards ELIXIR resources.

Features:

• Easy deployment using GitHub pages
• Advanced content search
• Create your own look with the many theme variables
• Change style using custom classes
• Support for a central tools table
• Page tagging and listing of those tagged pages
• Linking to ELIXIR resources including Bio.tools, FAIRsharing, FAIR Cookbook, TeSS, and DSWE
• Easy side navigation, top navigation, and footer management
• Mobile-friendly
• Create website sections with each section having its own sidebar
• Out of the box search engine optimizations including schema.org attributes and many other metadata attributes
• Support for Google Analytics, Matomo, and Plausible

Installation:

To use the ELIXIR toolkit theme in your Jekyll project, you have a few options:

Via Remote Theme:

1. Open your config.yml file.
2. Set the remote_theme property to elixir-toolkit-theme:

remote_theme: elixir-toolkit-theme

Via Ruby Gems:

1. Make sure you have Ruby Gems installed on your machine.
2. Add the following line to your Jekyll site’s Gemfile:

gem 'elixir-toolkit-theme'

3. Lock it onto a specific version by specifying the version number (e.g., 0.1.0):

gem 'elixir-toolkit-theme', '0.1.0'

4. Add the following line to your Jekyll site’s _config.yml file:

theme: elixir-toolkit-theme

Deployment:

The ELIXIR toolkit theme can be deployed using different methods:

Via GitHub Actions:

1. Make sure you have a GitHub workflow file setup similar to the one in the repo.
2. Go to Settings > Pages and enable GitHub Actions as a source.
3. Go to Environments > github-pages and remove the rule under Deployment branches if you want to deploy other branches than master or main via Workflow Dispatch (manually triggered action).

Via GitHub Pages:

This is the quickest way to deploy the elixir-toolkit-theme but gives less flexibility and does not allow you to make use of the new way of tagging tools. Visit the GitHub documentation to find out more about how to setup GitHub Pages. Note that this way of deploying does not support the tool-tag in the text of the markdown file to tag tools and resources.

Via GitLab Pages:

1. Add an extra .gitlab-ci.yml file in the root of the repo with the necessary deployment configuration.

Locally using Jekyll:

1. Install Ruby on your machine if it is not already present.
2. Install Jekyll by following the instructions provided in the Jekyll documentation.
3. Install any necessary dependencies.
4. Deploy the website.

Locally using Docker:

1. Install Docker if it is not already installed on your machine.
2. From the root of the elixir-toolkit-theme directory, run the command to start the Docker container and serve the website locally.
3. Make sure the .\_site directory is not yet created to avoid permission errors.

Summary:

The ELIXIR toolkit theme is a Jekyll theme that provides easy deployment of documentation websites and supports more complex websites requiring a central tool table and ELIXIR resource linking. It offers various features such as easy deployment using GitHub pages, advanced content search, customizable look and style, central tool table support, and mobile-friendly design. The theme can be installed via remote theme or Ruby Gems and can be deployed using different methods including GitHub Actions, GitHub Pages, GitLab Pages, or locally using Jekyll or Docker.