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:

• The downloads cards presentation template
• The downloads cards data file

Related Tasks:

• Adding downloads cards to pages

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.

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:

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:

• Adding releases names to downloads cards data file
• Adding releases screenshots to downloads cards data file
• Adding releases mirrors to downloads cards data file
• Adding releases documentation to downloads cards data file
• Adding releases end of life to downloads cards data file
• Adding releases commands to downloads cards data file

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: ""

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/"

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.

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

References

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