Documentation
This page describes jekyll-theme-centos-download component and how you can use it in your sites.

Concepts

The downloads cards

The downloads cards exist to present download information in your site pages.

The downloads cards is the result of combining the downloads cards presentation template and the downloads cards data file. This combination happens when you add downloads cards to pages.

Related Concepts:

Related Tasks:

The downloads cards presentation template

The downloads cards presentation template organizes download information vertically, using title, description, and release selector fields. The title and description provide common information to releases exposed through the release selector. The release selector controls the visibility of release-dependent information like screenshots, mirrors, documentation, end of life and commands.

The downloads cards presentation template allows you to customize the visibility of all its elements using include arguments. Fig. The downloads cards presentation template illustrates the vertical organization of components inside the downloads cards presentation template and their respective include arguments.

fig-the-downloads-cards-presentation-template
Fig. The downloads cards presentation template

The downloads cards presentation template does not provide a way to change the vertical presentation order of its elements. However, you can include several downloads cards presentation templates in the same page and control the visibility of their components using include arguments to reach the vertical organization you need.

The downloads cards presentation template reads download information from the downloads cards data file.

The downloads cards data file

The downloads cards data file provides download information for the downloads cards presentation template.

The downloads cards data file default location is src/_data/download/cards.yml. When this file does not exist in your site, it is read from the theme. When you create this file in your site, then it is used instead.

The downloads cards data file is a list of dictionaries written in YAML format. The simplest dictionary structure you can provide on each list item contains the title, description, and releases properties.

---
- title: "CentOS Stream"
  description: |
    Continuously delivered distro that tracks just ahead of Red Hat Enterprise
    Linux (RHEL) development, positioned as a midstream between Fedora Linux
    and RHEL. For anyone interested in participating and collaborating in the
    RHEL ecosystem, CentOS Stream is your reliable platform for innovation.
  releases: []

The following table describes the meaning of these three configuration properties:

Property Type Description
title "" The name of the GNU/Linux distribution you are providing releases for.
description "" A brief description about the GNU/Linux distribution you are providing releases for.
releases [] A list of dictionaries describing the GNU/Linux distribution release names and their respective dependencies.

NOTE: The releases property configuration is not described in this section. Instead, the documentation uses task-oriented sections below to describe each possible configuration you can perform.

The release property accepts the following configurations:

Tasks

Adding downloads cards to pages

To add the downloads cards to pages, do the following:

  1. Include download/card.html, the downloads cards presentation template.

    {% include download/cards.html %}
    
  2. Provide the include arguments to control the presentation.

    {% include download/cards.html id="DownloadsCard-1"
    with_title=false
    with_description=false
    with_release=true
    with_mirrors=true
    %}
    
    Argument Default Description
    id "DownloadsCard-1" The download card HTML identifier. This value must be unique in the entire page. Relevant when you are includeing more than one downloads card in the same page.
    data site.data.download.cards The data variable holding the content of downloads cards.
    title "" The exact downloads card title you want to present. When you pass this argument the downloads cards presentation template limits the amount of information it output for that specific card title you provided.
    with_title false Present the download cards title. Possible values are false or true.
    with_description false Present the download cards description. Possible values are false or true.
    with_release false Present the download card release-specific content. Possible values are false or true.
    with_screenshots false Present release-specific screenshots. Possible values are false or true. Requires with_release: true.
    with_mirrors false Present release-specific mirrors. Possible values are false or true. Requires with_release: true.
    with_documentation false Present release-specific documentation. Possible values are false or true. Requires with_release: true.
    with_eol false Present release-specific end of life. Possible values are false or true. Requires with_release: true.
    with_commands false Present release-specific commands. Possible values are false or true. Requires with_release: true.

Adding releases names to downloads cards data file

To add releases names to downloads cards data file, edit the downloads cards data file, and add a release key and value to releases dictionary. For example, if you want to add release names 9 and 8 to your downloads cards data file, the releases property should have two release dictionaries. One for 9 and one for 8.

---
- releases:
   9: {}
   8: {}

In this example, both 9 and 8 releases are empty. They do not include any release-dependent information.

When the page loads, the first release key you entered in the releases dictionary (i.e., 9, in the example above) is the active release in the release selector. Subsequent release keys are presented in the same order they were entered in the releases dictionary from top to bottom.

Adding releases screenshots to downloads cards data file

To add releases screenshots to downloads cards data file, do the following:

  1. Create the src/assets/img/download/screenshots/ directory.

  2. Copy your screenshot files o src/assets/img/download/screenshots/ directory. The screenshot files titles follow the <title>-<release>-screenshot-<N>.png naming convention.

    Field Description
    <title> The GNU/Linux distribution name. This is an alphabetic string, in lowercase with space characters replaced by dash (-) character.
    <release> The GNU/Linux distribution release. For consistency, it should be the same value in the releases key.
    <N> Incremental integer to make screenshot files unique per <title> and <release>.
  3. Edit the downloads data file and add the screenshots property into the release key accordingly. For example, if the screenshots you copied are for CentOS Stream 9, the configuration would be like the following:

    ---
    - title: CentOS Stream
      releases:
        9:
          screenshots:
            - src: "centos-stream-9-screenshot-1.png"
              alt: "centos-stream-9-screenshot-1.png"
    
    Property Description
    src The screenshot image file title, relative to src/assets/img/download/screenshots/ directory.
    alt The screenshot image alternative text.

Adding releases mirrors to downloads cards data file

To add releases mirrors to downloads cards data file, edit the downloads data file and add the mirrors property into the release key accordingly. The value of mirrors property is a list of dictionaries describing the relation between architecture, release name, and download links for the named distribution in different formats.

---
- title: "CentOS Stream"
  releases:
    9:
      mirrors:
        - architecture: "x86_64"
          iso: "https://mirrors.centos.org/mirrorlist?path=/9-stream/BaseOS/x86_64/iso/CentOS-Stream-9-latest-x86_64-dvd1.iso&redirect=1&protocol=https"
          rpm: "http://mirror.stream.centos.org/9-stream/"
          cloud: "https://cloud.centos.org/centos/9-stream/x86_64/images"
          containers: "https://quay.io/centos/centos:stream9"
          vagrant: ""
Property Description
architecture The architecture name the mirrors provide content for. For example, x86_64, ARM64 (aarch64), IBM Power (ppc64le), IBM Z (s390x).
iso The download mirror URL where you can find ISO files for the architecture defined.
rpm The download mirror URL where you can find RPM packages for the architecture defined.
cloud The URL where you can find cloud images for the architecture defined.
containers The URL where you can find container images for the architecture defined.
vagrant The URL where you can find Vagrant boxes for the architecture defined.

Adding releases documentation to downloads cards data file

To add releases documentation to downloads cards data file, edit the downloads data file and add the documentation property into the release key accordingly. The value of mirrors property is a list of dictionaries describing the relation between release name, and documentation links for the named distribution.

---
- title: "CentOS Stream"
  releases:
    9:
      documentation:
        - title: Release Notes
          link: "https://blog.centos.org/2021/12/introducing-centos-stream-9/"
        - title: Release Email
          link: "https://lists.centos.org/pipermail/centos-announce/2021-December/060971.html"
        - title: Website
          link: "https://docs.centos.org/en-US/docs/"
Property Description
title The documentation name.
link The documentation link.

Adding releases end of life to downloads cards data file

To add releases end of life to downloads cards data file, edit the downloads data file and add the eol property into the release key accordingly. The value of eol property is a list of dictionaries describing the relation between release name, and end of life date for the named distribution.

---
- title: "CentOS Stream"
  releases:
    9:
      eol:
        - date: ""
          description: |
            End of RHEL9 <a href="https://access.redhat.com/support/policy/updates/errata#Full_Support_Phase">full support</a> phase.
Property Description
date The end of life date. For example, 31 May 2024.
description The end of life description. Useful if you need to explain what happens during the end of life date, or provide a link to external resources explaining it.

Adding releases commands to downloads cards data file

To add releases commands to downloads cards data file, edit the downloads data file and add the commands property into the release key accordingly. The value of commands property is a list of dictionaries describing the relation between release name, and auxiliary commands you can run in the named distribution to do specific stuff.

---
- title: "CentOS Linux"
  releases:
    8:
      commands:
        - title: "Converting from CentOS Linux 8 to CentOS Stream 8"
          lines: |-
            dnf --disablerepo '*' --enablerepo extras swap centos-linux-repos centos-stream-repos
            dnf distro-sync
Property Description
title A string describing the end of life date. For example, 31 May 2024.
description The end of life description. Useful when you need to describe what happens during the end of life date, or provide a link to external resources explaining it.

References

This documentation tries to follow The DITA Style Guide Best Practices for Authors.