redhat-cop.github.io

Documentation site for the Red Hat Communities of Practice: contribution guidelines, CoP-specific content, CI patterns, and a repository map.

Live site

https://redhat-cop.github.io

Stack

Jekyll 4 on Ruby 4, deployed to GitHub Pages via Actions

1. Repository layout

Path	Purpose
index.md	Home page
repo-map.md	Index of CoP Git repositories (/repos/)
contrib/	Contribution guidelines (fork/PR workflow)
cop/	CoP-specific documentation
ci/	Continuous integration guides for redhat-cop repos
images/	Screenshots and other static images
_config.yml	Site config, plugins, and navigation
.github/workflows/pages.yml	Build, test, and deploy workflow

Content is Markdown (.md). This README.adoc is for developers working on the repo itself and is not published to the site.

2. Prerequisites

1. Ruby 4.0+ (see .ruby-version)

   On macOS, do not use the system Ruby under /usr/bin. Install Homebrew Ruby and put it first on your PATH:

   brew install ruby
   echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   ruby -v   # should show 4.x

2. Bundler

   gem install bundler

3. Run the site locally

git clone git@github.com:redhat-cop/redhat-cop.github.io.git
cd redhat-cop.github.io
bundle install
bundle exec jekyll serve

Open http://localhost:4000. Stop the server with Ctrl+C.

Useful options:

bundle exec jekyll serve --livereload          # auto-reload on file changes
bundle exec jekyll serve --host 0.0.0.0        # reachable on the local network

4. Make a content or site change

1. Create a branch from main.

2. Edit or add Markdown under the paths listed in Repository layout above.

3. Preview with bundle exec jekyll serve.

4. Open a pull request against main.

New pages pick up the default page layout from _config.yml unless you set another layout (for example layout: home on the homepage).

For contributing to other redhat-cop repositories, follow the published guidelines: Contribution Guidelines.

5. Validate before you push

jekyll serve writes http://localhost:4000 into _site, which fails HTML-Proofer’s HTTPS check. Build in production mode first:

JEKYLL_ENV=production bundle exec jekyll build
bundle exec htmlproofer --disable-external ./_site

To check a _site produced by jekyll serve without rebuilding:

bundle exec htmlproofer --disable-external --no-enforce-https ./_site

6. Publishing

CI builds and runs HTML-Proofer on every pull request. Pushes to main also deploy to GitHub Pages.

One-time admin setup (repository Settings → Pages):

1. Under Build and deployment → Source, choose GitHub Actions.

7. Security

See SECURITY.md. Report vulnerabilities to the @redhat-cop-sre team.