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.

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

Build with Jekyll

1. Install a full Ruby development environment.

   Windows: 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).

   MacOS: use chruby and ruby-install to install the latest version (MacOS comes with an outdated version). It can be installed via Homebrew.

   For up-to-date instructions on installing Ruby, please see Jekyll's installation page.

2. Install Jekyll and Bundler. Open a console window with directory at root of this repo and run:

   gem install jekyll bundler

3. Install bundler gems:

   bundle install

   If using MacOS, run the following before bundle install:

   bundle config build.nokogiri --use-system-libraries

4. Build and serve site (locally):

   bundle exec jekyll build
   bundle exec jekyll serve

5. Go to site: http://localhost:4000/common-service-showcase/