Common-Service-Showcase

Website for user documentation and marketing of the common services built by the Common Service Showcase Team.

GitHub Pages

We are using GitHub Pages with gh-pages branch publishing source. We have set gh-pages as the default branch and we require that all changes are done via Pull Requests. However, in order to review/preview the changes, one must run the site locally.

Content

The site is built with Jekyll, so start by reviewing their documentation. Jekyll in turn uses Markdown, Liquid, HTML & CSS to generate the static site.

Collections

The site uses multiple pages, some of which are built from collections. See the collections key in the config.yaml

/collections is the directory that collections go in.

/collections/_services is the most likely spot to need to add new collections. Markdown files added here with the correct Front Matter will dynamically create the new pages, their navigation items, and add to lists on multiple pages.

Publishing

GitHub Pages understands Jekyll and will build and deploy sites automatically, do not check in the _site directory.

Fork the Common Service Showcase repository
Checkout gh-pages branch
Create branch from gh-pages
Add new collections (services), or other content
Build with Jekyll
Review your changes
Commit and push your changes to your fork.
Make a Pull Request in Common Service Showcase repository.
Ask for a review and approval of changes.

Build with Jekyll

Install a full Ruby development environment (2.6 works). For Windows users, visit https://rubyinstaller.org/downloads/ and download latest version WITH Devkit option. Install the installer (when prompted, just tap enter to use defaults - may happen twice)
Install Jekyll and bundler gems. Open a console window with directory at root of this repo and run:

gem install bundler
gem install jekyll
bundle install

Build and serve site (locally)

bundle exec jekyll build
bundle exec jekyll serve