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

Site Concepts

The site directory structure

The site configuration starts with the following directory structure:

.
├── README.md
├── public/
└── src/
   ├── _config.yml
   └── index.md

Where:

File Description
README.md File describing the site purpose.
public Directory where the final site is published. This is the directory you expose to your audience.
src/_config.yml The site configuration file. Here is where you set your site global defaults.
src/index.md The site home page.

The site configuration file

The site configuration file is src/_config.yml and the base/default layout requires the site to have, at least, the following configuration variables in it:

---
# Welcome to Jekyll!
#
# This config file is meant for settings that affect your whole blog, values
# which you are expected to set up once and rarely edit after that. If you find
# yourself editing this file very often, consider using Jekyll's data files
# feature for the data you need to update frequently.
#
# For technical reasons, this file is *NOT* reloaded automatically when you use
# 'bundle exec jekyll serve'. If you change this file, please restart the
# server process.
#
# If you need help with YAML syntax, here are some quick references for you:
# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
# https://learnxinyminutes.com/docs/yaml/

title: jekyll-theme-centos-base
description: "HTML templates, YAML files and images related to jekyll-theme-centos-base."
email: areguera@centosproject.org
url: "https://centos.gitlab.io"
baseurl: "/artwork/centos-web/jekyll-theme-centos-base"

# site.theme - Set the name of the site theme. The theme versions are
# controlled using jekyll-theme-centos container images.  These images are
# versioned and provide all you need to build jekyll sites with
# jekyll-theme-centos.
theme: "jekyll-theme-centos"

# site.component_data_dirname - Set the directory name where the navbar data files
# is stored. For example, if the navbar file is at `_data/base/navbar.yml', the
# value you need to provide is `base'.
component_data_dirname: "base"

# site.component_data_navbar - Set the name of the navbar data file. For
# example, if the navbar file is at `_data/base/navbar.yml', the value you need
# to provide is `navbar', without the extension.
component_data_navbar: "navbar"

defaults:
  - scope:
      path: "" # an empty string here means all files in the project.
    values:
      layout: "base/default"
      # ----------------------------------------------------------------
      # Nav
      # ----------------------------------------------------------------
      with_logo: "centos-whitelogo.svg"
      with_manifestation: "jekyll-theme-centos-base"
      # ----------------------------------------------------------------
      # Header
      # ----------------------------------------------------------------
      with_breakingnews: []
      with_announcements: []
      with_motif: "centos-motif.png"
      with_title: true
      with_preamble: true
      # ----------------------------------------------------------------
      # Main
      # ----------------------------------------------------------------
      with_breadcrumbs: true
      with_toc: false
      with_artwork: false
      with_content: true
      # ----------------------------------------------------------------
      # Footer
      # ----------------------------------------------------------------
      with_footer: true
      with_shortcuts: true
      with_sponsors: false
      with_social: true
      with_finale: true
      with_copyright: true
      # ----------------------------------------------------------------
      # Script (also changes Head, to manage script-related stylesheets)
      # ----------------------------------------------------------------
      with_highlight: false
      with_datatables: false

plugins:
  - jekyll-feed
  - jekyll-toc

permalink: /:path/:basename/

The site configuration variables

The base/default layout requires you to configure the following site variables:

Name Default Description
baseurl "" The base url where the site is hosted without trailing slash. E.g., /artwork/centos-web/jekyll-theme-centos-base
defaults [] Jekyll Front Matter Defaults. To know more about default values, see the site configuration file.
description "" A brief description about the site purpose.
email "" The webmaster contact email address.
component_data_dirname "base" The directory name under _data/ where the navigation bar data file lives.
component_data_navbar "navbar" The data file name where navigation bar content lives, under site.component_data_dirname.
theme "" The theme name to use. E.g., jekyll-theme-centos.
title "" The name of your site.
url "" The site url without trailing slash. E.g., https://centos.gitlab.io

The base/default layout also recognizes Jekyll built-in site variables.

The site configuration scopes

The site configuration scopes are relevant for configuration variables like with_announcements and with_breakingnews, where you need to control the visibility of important messages accross your site pages.

The site configuration scopes are “site-level” and “page-level.” You define site-level configuration variables in the site configuration file and page-level configuration variables in the front-matter section of individual site pages. When the same configuration variable is defined in both site-level and page-level scopes, the value set in the page-level scope overrides the value set in site-level scope.

At operation level, the changes related to configuration variables in both site-level and page-level scopes require you to rebuild the site files running the jekyll build command. When you provide the --watch flag to jekyll build command, it keeps watching for site changes and auto-regenerate all the site files when one happens. When the change is in the site configuration file, however, the --watch flag does not auto-regenerate the site files and you need to run jekyll build command again for changes to take effect.

The site colors

The base/default layout changes the _sass/base/_variables.scss file to customize Boostrap default color theme using the CentOS Colors. The changes introduced affect the following classes:

.bg-dark Dark .text-bg-dark
.bg-primary Primary .text-bg-primary
.bg-secondary Secondary .text-bg-secondary

Other Bootstrap color classes remain intact:

.bg-light Light .text-bg-light
.bg-danger Danger .text-bg-danger
.bg-success Success .text-bg-success
.bg-warning Warning .text-bg-warning
.bg-info Info .text-bg-info

Background gradients:

.bg-gradient-primary Section Name
.bg-gradient-secondary Section Name

Background gradients nested with gradients:

.bg-gradient-primary
.bg-gradient-secondary
.bg-gradient-secondary
.bg-gradient-primary

Background gradient nested with plain color:

.bg-gradient-primary
.bg-body
.bg-gradient-secondary
.bg-body

Text gradients:

.bg-body .text-gradient-primary
Community Enterprise Operating System
.bg-dark .text-gradient-primary
Community Enterprise Operating System
.bg-body .text-gradient-secondary
Community Enterprise Operating System
.bg-dark .text-gradient-secondary
Community Enterprise Operating System

The site fonts

The base/default layout uses the Montserrat and Source Code Pro fonts, both available under the Open Font License.

The base/default layout implements this configuration changing the following files:

_includes/base/head.html:

<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Montserrat:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&family=Source+Code+Pro:ital,wght@0,400;0,500;0,700;1,400;1,500;1,700&display=swap">
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Source+Code+Pro:ital,wght@0,400;0,500;0,700;1,400;1,500;1,700&display=swap">

_sass/base/_variables.scss:

$font-family-sans-serif: "Montserrat", sans-serif;
$font-family-monospace: "Source Code Pro", monospace;

The site data files

The base/default layout uses data files written in YAML format. Each data file has its own structure, serves its own purpose and is distributed read-only inside the jekyll-theme-centos theme.

The base/default layout reads information from the following data files:

Data file Description
src/_data/base/copyright.yml Configure the site copyright information.
src/_data/base/navbar.yml Configure the site navigation bar. The path to this specific data file can change based on the component_data_dirname and component_data_navbar site configuration variables. See the site navigation bar data files.
src/_data/base/social.yml Configure the site social media information.

These data files do not exist in the site directory structure when you create it. Instead, they are read from the theme directory structure when you run the task of regenerating the site public directory. This approach is very useful when you want to share re-usable information across different websites but preserve a single point of edition for them. The most notable examples are data files holding site copyright and site social media.

The copyright and social media data files must not exist in your site directory structure, so you always use their default values from the theme directory structure, where they are maintained. By doing so, all sites present the same information consistently with minimum maintenance effort. This is good for CentOS related sites but you might need to alter the rule when they are not.

In contrast to copyright and social media data files, the navigation bar data file is expected to be changed locally, in your site directory structure. This is because different sites have different content and navigation needs. When you create a data files in your site directory, it must meet the exact same YAML structure the theme provides. This convention allows the base/default layout to find the information you provide and present it as expected.

The site navigation bar

The site navigation bar provides an always-visible set of links on the very top of all your pages. In the navigation bar space, you can configure simple links, or menu links limited to one level.

The base/default layout reads the site navigation bar data file from the following location:

src/_data/{{ site.component_data_dirname }}/{{ site.component_data_navbar }}.yml

The configuration of both {{ site.component_data_dirname }} and {{ site.component_data_navbar }} variables take place in the site configuration file. When the site navigation bar data file you configured does not exit in the site directory structure, the site navigation bar falls back to src/_data/base/navbar.yml file, available in the theme directory structure.

The _src/_data/base/navbar.yml file has the following value:

{"name"=>"Documentation", "icon"=>"fa-solid fa-book", "link"=>"/documentation", "menu"=>[], "visible_on"=>["navbar"]}

The site navigation bar data file comprises links and menus.

The site navigation flow

The site navigation flow establishes the progression in which you find the information you want in the site. The progressing is as follows: use an inverted tree structure to cover topics in less detail up-side and in more details down-side. In this structure, down-side content is always related to up-side content. When the content is not related, a new top-level page should be created to cover the topic there. The breadcrumbs section on each page provides a way to go up in the hierarchy.

The following illustration presents the progression followed to go from one top-level page (A) to a down-side page (C) passing through a content page (B) with links to related pages.

The site navigation flow
The site navigation flow

When you expand a content page creating other pages, it becomes an index page for those pages it links to. It presents both content and links (e.g., See A, and B in the illustration above). In these cases, the presentation order is content first and index of links later.

Categories in content page

The content page is where you define the page categories. Consider the following example setting two categories named documentation and jekyll-theme-centos-base in the page front matter section:

---
title: Documentation

categories: ["documentation", "jekyll-theme-centos-base"]
---

Categories in index page

The index page is where you present links to other content-related pages. The relation is established filtering the page categories in the site.pages variable.

Example:

{% assign pages = site.pages | where: "categories", "documentation" | where: "categories", "jekyll-theme-centos-base" %}
{% include base/pages.html pages=pages %}
This page describes the jekyll-theme-centos-base component and how you can use it in your sites.

The site navigation breadcrumbs

The base/default layout provides the base/breadcrumbs.html component to build a line of page links automatically, using the site directory structure as reference. You can find the site navigation breadcrumbs on each page, between the page announcements and the page title.

The base/breadcrubms.html component describes the page location inside the site hierarchy using links you can access quickly. The breadcrumbs presentation starts with the Home page link and goes all the way down the site hierarchy linking intermediate pages until reaching the page you are currently reading, which is not linked. The breadcrumbs create a visual map that guides you while seeking specific information. Both breadcrumbs and site navigation flow schema work together to deliver a consistent navigation experience.

Example:

.
├── _config.yml
└── documentation.md

The site social networks

The site social networks are visible on the right-bottom side of all your pages.

HTML templates, YAML files and images related to jekyll-theme-centos-base.

The base/default layout reads the site social networks data file from the following location:

src/_data/{{ site.component_data_dirname }}/social.yml

The configuration of {{ site.component_data_dirname }} variable takes place in the site configuration file. When the social networks data file you configured does not exit in the site directory structure, the base/default layout presents social networks form src/_data/base/social.yml file, available in the theme directory structure.

The _src/_data/base/social.yml file has the following value:

{"name"=>"Facebook", "icon"=>"fa-brands fa-facebook-f", "link"=>"https://www.facebook.com/groups/centosproject/"}{"name"=>"X", "icon"=>"fa-brands fa-x-twitter", "link"=>"https://twitter.com/centos"}{"name"=>"Youtube", "icon"=>"fa-brands fa-youtube", "link"=>"https://youtube.com/TheCentOSProject"}{"name"=>"Linkedin", "icon"=>"fa-brands fa-linkedin", "link"=>"https://www.linkedin.com/groups/22405"}{"name"=>"Reddit", "icon"=>"fa-brands fa-reddit", "link"=>"https://www.reddit.com/r/CentOS/"}{"name"=>"Mastodon", "icon"=>"fa-brands fa-mastodon", "link"=>"https://fosstodon.org/@centos"}
Property Description
name The name of the social network you want to present.
icon The brand icon of the social network you want to present. Available icons are limited to fontawesome free brands only.
link The URL of the social network you want to present.

You can control the visibility of social networks changing the value related to with_socials page configuration variable.

The site copyright note is visible on the left-bottom side of all your pages.

Copyright © 2024 The CentOS Project Legal Privacy Site source

The base/default layout reads the site social networks data file from the following location:

src/_data/{{ site.component_data_dirname }}/copyright.yml

The configuration of {{ site.component_data_dirname }} variable takes place in the site configuration file. When the copyright note data file you configured does not exit in the site directory structure, the base/default layout presents the copyright note from the src/_data/base/copyright.yml file, available in the theme directory structure.

The _src/_data/base/copyright.yml file has the following value:

{"author"=>"The CentOS Project", "legals"=>[{"text"=>"Legal", "link"=>"https://www.centos.org/legal"}, {"text"=>"Privacy", "link"=>"https://www.centos.org/legal/privacy"}, {"text"=>"Site source", "link"=>"https://git.centos.org/centos/centos.org"}]}
Property Description
author The site creator and owner of the copyright.
legals List of links related to legal terms made of text and link elements. These items are presented on the right side of the copyright note.

You can control the visibility of site copyright note changing the value related to with_copyright page configuration variable.

Page Concepts

The page base/default layout

The page base/default layout is the default layout for content presentation in jekyll-theme-centos theme. It stands on top of Bootstrap v5.3 components and allows page customization by means of “site configuration variables”, “page configuration variables” and “site data files”.

The page base/default layout has the following structure:

The page base/default layout
The page base/default layout structure.

The page configuration variables

The base/default layout requires you to configure the following page variables:

Name Default Section Description
with_breakingnews [] header When the value is an empty list ([]), the breaking news section is not rendered. When the value is a non-empty list ([{"title": "", "content":"", "url":""}]), the breaking news is rendered, one for each item in the list. All breaking news properties in the dictionary are optional. However, you probably want to at least title to provide a meaningful message.
with_announcements [] main When the value is an empty list ([]), the announcements section is not rendered. When the value is a non-empty list ([{"title": "", "content":"", "color":""}]), announcements are rendered. One for each item in the list. All announcement elements in the dictionary are optional. However, you probably want to have at least content to provide a meaningful message.
with_artwork false main When the value is "path/to/image.png", the page artwork is rendered. In this example, path/to/image.png must be relative to /assets/img/ to display the image correctly. When the value is false the page artwork is not rendered.
with_breadcrumbs true main When the value is true, the page breadcrumbs are rendered. When the value is false the page breadcrumbs are not rendered.
with_content true main When the value is true, the page content is rendered. When the value is false the page content is not rendered.
with_copyright true footer When the value is true, the page copyright is rendered. When the value is false the page copyright is not rendered.
with_datatables false footer When the value is true, the datatables library to allow searching inside tables is enabled. When the value is false the datatables library is not enabled.
with_finale true footer When the value is true, the page finale (i.e., site title plus site description) is rendered. When the value is false the page finale is not rendered.
with_highlight "default" footer When the value is true, the highlight.js library for code highlighting is enabled. When the value is false the highlight.js library is not enabled.
with_logo "centos-whitelogo.svg" nav Path to site’s logo image in SVG format. The path is relative to {{ site.url }}{{ site.baseurl }}/assets/img/.
with_manifestation "" nav When the value is an empty string (""), the manifestation is not rendered aside the logo. When the value is a "string", that string is considered to be the manifestation name and is rendered aside the logo.
with_motif "centos-motif.png" header Path to site’s artistic motif in PNG format. The path is relative to {{ site.url }}{{ site.baseurl }}/assets/img/.
with_preamble true header When the value is true, the page preamble is rendered. When the value is false the page preamble is not rendered.
with_shortcuts true footer When the value is true, the page shortcuts are rendered. When the value is false the page shortcuts are not rendered.
with_social true footer When the value is true, the page social media are rendered. When the value is false the page social media are not rendered.
with_sponsors true footer When the value is true, the page sponsors are rendered. When the value is false the page sponsors are not rendered.
with_title true header When the value is true, the page title is rendered. When the value is false the page title is not rendered.
with_toc false main When the value is true, the page table of content are rendered. When the value is false the page table of content is not rendered.

The page variable default values are configured in the defaults site variable. To know more about site defaults, see the site configuration file.

The page variable default values are overwritten when you add them in the page front matter and change its value there.

The base/default layout also recognizes Jekyll built-in page variables.

The page breaking news

The base/default layout uses the with_breakingnews configuration variable and _includes/base/breakingnews.html template file to present breaking news.

The breaking news is way more relevant than announcement. It is always visible on the page, and the user cannot dismiss it once configured (e.g., there is not close button). Complementary, the breaking news container can present a “Known more” button to link a page describing the breaking news in more details.

Only use breaking news when you need to communicate important CentOS events, end-of-life notes, availability of new major releases, and critical issues related to CentOS Project itself.

Default presentation

---
with_breakingnews:
  - content: "This is a high impact message for testing purposes."
    url: ""
    color: ""

When you are adding content to breaking news container, consider using a maximum of two visible lines. Having more than two visible lines in the breaking news container will expand its height to greater values than the maximum value (38px) used to calculate the scroll-margin-top property. In such case, the content headings will be hidden under the breaking news container when you access them through the page’s table of content. To present effective breaking news, keep your message short, one-line if possible, and use the “know more” button URL to link details.

Custom presentation

---
with_breakingnews:
  - content: 'This is a high impact message for testing purposes.'
    color: "secondary"
    url: ""
---
with_breakingnews:
  - content: 'This is a high impact message for testing purposes.'
    color: "info"
    url: ""
---
with_breakingnews:
  - content: 'This is a high impact message for testing purposes.'
    color: "warning"
    url: ""
---
with_breakingnews:
  - content: 'This is a high impact message for testing purposes.'
    color: "danger"
    url: ""
---
with_breakingnews:
  - content: 'This is a high impact message for testing purposes.'
    color: "success"
    url: ""
---
with_breakingnews:
  - content: 'This is a high impact message for testing purposes.'
    color: "dark"
    url: ""
---
with_breakingnews:
  - content: 'This is a high impact message for testing purposes.'
    color: "light"
    url: ""

The page announcements

The base/default layout uses the with_announcements configuration variable and _includes/base/announcements.html template file to present announcements on the page main section, just below the breaking news section.

The announcements are less relevant than breaking news. You use announcements to alert your users about peculiarities affecting the page content. For example, when a page content gets outdated, or it is being worked on and you want to prevent users from relaying entirely on it during the edition process.

Default format

The announcements have the following visual format:

---
with_announcements:
  - title: "Example Title."
    content: 'This is the announcement content with <a href="#" class="alert-link">link</a> for testing purposes.'
    color: "primary"
Property Description
title The announcement title.
content The announcement content.
color The announcement color. Possible options include primary (default), secondary, info, warning, danger, success, dark, light.

Custom formats

---
with_announcements:
  - title: "Example Title."
    content: 'This is the announcement content with <a href="#" class="alert-link">link</a> for testing purposes.'
    color: "secondary"
---
with_announcements:
  - title: "Example Title."
    content: 'This is the announcement content with <a href="#" class="alert-link">link</a> for testing purposes.'
    color: "info"
---
with_announcements:
  - title: "Example Title."
    content: 'This is the announcement content with <a href="#" class="alert-link">link</a> for testing purposes.'
    color: "warning"
---
with_announcements:
  - title: "Example Title."
    content: 'This is the announcement content with <a href="#" class="alert-link">link</a> for testing purposes.'
    color: "danger"
---
with_announcements:
  - title: "Example Title."
    content: 'This is the announcement content with <a href="#" class="alert-link">link</a> for testing purposes.'
    color: "success"
---
with_announcements:
  - title: "Example Title."
    content: 'This is the announcement content with <a href="#" class="alert-link">link</a> for testing purposes.'
    color: "dark"
---
with_announcements:
  - title: "Example Title."
    content: 'This is the announcement content with <a href="#" class="alert-link">link</a> for testing purposes.'
    color: "light"

Site Tasks

This section describes frequent administration actions you perform in your site.

Regenerating the site public directory

To regenerate the public site from source files, run jekyll build command using one of the jekyll-theme-centos container images:

podman run --rm \
 -v $$PWD/public:/public \
 -v $$PWD/src:/site \
 --name jekyll-theme-centos \
 registry.gitlab.com/centos/artwork/centos-web/jekyll-theme-centos:latest \
 bundle exec jekyll build --config /site/_config.yml -s /site -d /public

In this example the jekyll build command uses the latest container image of jekyll-theme-centos and renders your site with it. This image contains the theme layouts, includes, data files, auxiliary images, and tools you need to build your site using jekyll-theme-centos theme.

CAUTION: Using latest when building the site may introduce unexpected visual changes. Always use a specific release version to have a consistent visual presentation between builds.

Adding the site announcements

To add announcements to all site pages, edit the site configuration file and add your announcements under with_announcements:

---
defaults:
 - scope:
     path: "" # an empty string here means all files in the project.
   values:
     # ----------------------------------------------------------------
     # Header
     # ----------------------------------------------------------------
     with_announcements:
       - title: "This is a info title"
         color: "info"
         content: "This is a info announcement content."

Adding the site breaking news

To add breaking news to all site pages, edit the site configuration file and add your announcements under with_breakingnews:

---
defaults:
 - scope:
     path: "" # an empty string here means all files in the project.
   values:
     # ----------------------------------------------------------------
     # Header
     # ----------------------------------------------------------------
     with_breakingnews:
       - title: "Example Title!"
         content: "This is the breaking news for testing purposes. "
         url: "#"
         color: "primary"

Changing the site artistic motif

To change the site artistic motif, do the following in your site directory structure:

  1. Copy the artistic motif in PNG format somewhere under assets/img/ directory (e.g., assets/img/site-motif.png.

  2. Add the with_motif variable to your site configuration file and change its value to have the path of the artistic motif image you copied (e.g., assets/img/site-motif.png.)

When you are producing a new site artistic motif, consider the following recommendations:

Property Description
Size The image should look good in both small and large screens. Consider using an image of 1920x1080 pixels.
Contrast The artistic motif image is used as background on headers. It must provide a high contrast ratio (e.g., AAA) image for white text presented over it.
Transparency Consider using semi-transparent images on top of #200735 (the dark color in the color schema) plain color. This allows the image to adapt itself to different background colors. In this case, consider converting the image mode from RGB to greyscale.
Position The attention point in the image must be on the right side or presented in a way that doesn’t make text on top difficult to read.
Optimization The image must load fast. So, make it small. Always optimize the final artistic motif PNG file using the pngquant tool.
Semi-transparent artistic motif on white background.
Semi-transparent artistic motif on white background.
Semi-transparent artistic motif on dark background
Semi-transparent artistic motif on dark background.
Documentation
This page describes the jekyll-theme-centos-base component and how you can use it in your sites.

Semi-transparent artistic motif on dark background with white text on top.

Changing the site favicon

To change the site favicon, ensure the following directory structure and file names exist in your site:

src/
├── site.webmanifest
└── assets/icons
    ├── android-chrome-192x192.png
    ├── android-chrome-512x512.png
    ├── apple-touch-icon.png
    ├── favicon-16x16.png
    ├── favicon-32x32.png
    ├── favicon.ico
    └── favicon.svg

You can create these files using your site logo SVG file and an online favicon generator. When you do so, review the content of site.webmanifest file to be sure it has the correct paths to find the images in your site. You can use the following site.webmanifest example as reference:

{
  "name": "",
  "short_name": "",
  "icons": [
    { "src": "/assets/icons/android-chrome-192x192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/assets/icons/android-chrome-512x512.png", "sizes": "512x512", "type": "image/png" }
  ],
  "theme_color": "#ffffff",
  "background_color": "#ffffff",
  "display": "standalone"
}

To change the site logo, do the following in your site directory structure:

  1. Copy the logo image in SVG format somewhere under src/assets/img/ directory (e.g., src/assets/img/site-logo.svg.

  2. Edit your site configuration file and set the with_logo: variable to point to your new logo image (e.g., site-logo.svg) relatively to assets/img path.

    ---
    defaults:
      - scope:
          path: "" # an empty string here means all files in the project.
        values:
          layout: "base/default"
          with_logo: "site-logo.svg"
    

Changing the site navigation bar

You can customize the navigation bar data file path using the site.component_data_dirname and site.component_data_navbar variables in the site configuration file. This is useful when you build your site from different configuration files and want to use a different navigation bar data file for each of them. For example, you have one configuration file for dev, staging, and prod environment where the navigation links to be adjusted according differences related to these environments.

To change the site navigation bar of your site, do the following:

  1. Edit the src/_config.yml file, and set the {{ site.component_data_dirname }} and {{ site.component_data_navbar }} variables.

  2. Create the src/_data/{{ site.component_data_dirname }}/{{ site.component_data_navbar }}.yml data file in your site directory structure.

  3. Edit src/_data/{{ site.component_data_dirname }}/{{ site.component_data_navbar }}.yml file to configure links and menus.

Changing Sass variables

To change the Sass variables, do the following:

  1. Identify the sass variable you want to change. You can do this checking Bootstrap’s default scss variables. This file contains all the variables you can customize. definition.
  2. Create the _sass/base/_variables.scss file in your site directory structure.
  3. Make your changes in the _sass/base/_variables.scss file.

Page Tasks

Adding contextual feedback

To add contextual feedback in your pages, do the following:

  1. Create a paragraph.
  2. Add the {:} line before the paragraph. Don’t add empty lines between {:} and the paragraph.
  3. Add Bootstrap classes related Alerts inside {:}.

Examples:

{:.alert .alert-primary}
**CentOS Recommends:** This is a CentOS recommendation message with [link](#){:.alert-link} for testing purposes.

CentOS Recommends: This is a CentOS recommendation message with link for testing purposes.

{:.alert .alert-secondary}
**CentOS Tip:** This is a CentOS Tip message with [link](#){:.alert-link} for testing purposes.

CentOS Tip: This is a CentOS Tip message with link for testing purposes.

{:.alert .alert-warning}
**WARNING:** This is a warning message with [link](#){:.alert-link} for testing purposes.

WARNING: This is a warning message with link for testing purposes.

{:.alert .alert-danger}
**CAUTION:** This is a caution message with [link](#){:.alert-link} for testing purposes.

CAUTION: This is a caution message with link for testing purposes.

{:.alert .alert-info}
**INFO:** This is an info message with [link](#){:.alert-link} for testing purposes.

INFO: This is an info message with link for testing purposes.

{:.alert .alert-light}
**NOTE:** This is a note message with [link](#){:.alert-link} for testing purposes.

NOTE: This is a note message with link for testing purposes.

{:.alert .alert-success}
**SUCCESS:** This is a success message with [link](#){:.alert-link} for testing purposes.

SUCCESS: This is a success message with link for testing purposes.

Adding the page announcements

To add announcements to one single page, add the with_announcements configuration variable to that page front matter along the announcements you want to add as value.

---
title: This is a page with announcements

with_announcements:
  - title: "This is a info title"
    color: "info"
    content: "This is a info announcement content."
---

Page content here.

To add links to site navigation bar, add the following YAML structure to site navigation data file:

---
- name: "Simple Link"
  icon: "fa-solid fa-link"
  link: "#"
  menu: []
  visible_on: ["navbar"]
Parameter Description
name The name of the link.
icon The icon class rendered on the left side menu name. Possible options to use use here are limited to fontawesome freely distributed icons.
link The URL associated to the link name. Here, URLs are relative to site.baseurl.
menu Must be an empty list. For example [].
visible_on Must be ["navbar"]. Simple links are visible in the navigation bar only. Simple links are not presented in the footer shortcuts section.

Adding menus to site navigation bar

To add menus to site navigation bar, add the following YAML structure to site navigation data file:

---
- name: "Menu Link"
  icon: "fa-solid fa-square-plus"
  menu:
    - name: "First parent page"
      link: "#"
    - name: "Second parent page"
      link: "#"
  visible_on: ["navbar", "footer"]
Parameter Description
name The name of the menu where links are organized.
icon The icon class rendered on the left side menu name. Possible options to use use here are limited to fontawesome freely distributed icons.
menu Must be a non-empty list holding one or more entries of {"name": "", "link": ""} dictionary. In this dictionary, name is the name of the link and link is the URL associated to the link name. The link can be absolute or relative.
visible_on Must be ["navbar", "footer"]. Menu links are visible in the navigation bar and in the footer shortcuts section.

Highlighting pre-formatted code

The base/default layout uses highlightjs to highlight code blocks in content. By default, highlight of pre-formatted code is disabled.

To enable pre-formatted code highlight, add the with_highlight: stackoverflow-light in the page front matter.

---
title: Page with code blocks highlighted

with_highlight: stackoverflow-light
---

Page content here.

Use one unique theme name across in all the site pages to achieve high visual consistency.

Enable highlight of pre-formatted code where you really need it. By doing so, you reduce the amount of code your page needs to load and so you make it load faster.

Adding tables

When you are adding content tables in your pages, check you provide the {:.table .table-bordered} class definition on top of your Markdown table definitions. This allows your table to be properly rendered using Bootstrap table style.

Example:

{:.table .table-bordered}
| Name | Default | Description |
| ---- | ------- | ----------- |
| a    | b       | c           |
| d    | e       | f           |
Name Default Description
a b c
d e f

When your content tables are lengthy, and you find it hard to find information inside them, consider adding a search box to improve its accessibility.

The base/default layout uses DataTables files to present your content tables with handy features, including search box and content pagination. By default, DataTables is disabled.

Enable DataTables where you really need it. By doing so, you reduce the amount of code your page needs to load and so makes it load faster.

To enable search box in your content tables, do the following:

  1. Enable DataTables in the page you plan to use it. You do this adding the with_datatables: true parameter to your page front matter.

    ---
    title: Page with datatables enabled
    
    with_datatables: true
    ---
    
  2. Attach the dataTable class to content tables you want to have the feature enabled on.

    {:.table .table-bordered .dataTable}
    | Name | Default | Description |
    | ---- | ------- | ----------- |
    | a    | b       | c           |
    | d    | e       | f           |
    

    Example:

    Name Default Description
    a b c
    d e f

Adding images

To add images, use the base/image.html template.

{% include base/image.html file="centos-motif.png"
alt="The CentOS Artistic Motif"
caption="The CentOS Artistic Motif"
extraclasses="bg-dark"
%}
The CentOS Artistic Motif
The CentOS Artistic Motif
Property Type Description
file "" The path to the image file. This path is relative to /assets/img/.
alt "" The alterntive text passed to alt property in <img> HTML element. The alt property does not allow HTML code as value.
caption "" The text passed to <figcaption> HTML element. The caption property does allow HTML code as value.
extraclasses "" Extra classes added to <img> HTML element. Supported classes include all Bootstrap classes that make sense here. For example, you can use this property to provide the background color of semi-transparent images.

CAUTION: Do not duplicate the value of alt properties when you use the base/image.html template to create more than one image in the same page. This causes figures to have duplicated id properties and make figure references to fail.

Referencing images

To reference images in you pages, do the following:

  1. Use the base/image.html template when you are adding images.

  2. Use Markdown to create the reference link. In the address part, add the value of the alt property from the image you want to reference to. When you do so, make the value lowercase, and replace all occurrences of space ( ) and slash (/) characters with dash (-) characters. All dot (.) characters are removed from the final id value.

    Example:

    [The CentOS Artistic Motif](#the-centos-artistic-motif)
    

    The CentOS Artistic Motif

References

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