Jekyll Infotorg APIs theme

Scaffold for a basic Jekyll theme for use as a reference or template

Infotorg API Jekyll theme has been developed as a Gem-based theme for easier use, and 100% compatible with GitHub Pages when used as a remote theme.

Theme preview

Create a new project from this template. Or just use the code or docs here as a reference.

If you forked or downloaded the theme repo you can safely remove the following folders and files:

• /docs
• infotorg-api-jekyll-theme.gemspec
• README.md
• screenshot.png
• any not needed files from /pages folder
• update _data/navigation.yml file

View a live demo on GitHub Pages:

If you build a Jekyll site, you'll typically use a theme to style your site or at least give a base which you and customize on top of.

A theme is a way of packaging layout files, CSS styling and includes files to be installed in another Jekyll project. A theme might be made from scratch or based on a static HTML. A theme is a great way of making styling reusable across projects by you and other people.

A good example of a theme is Minima, which is the default theme used when running jekyll new PATH.

The part that allows this project gem to be packaged as an installable gem-based theme is this file:

• infotorg-api-jekyll-theme.gemspec

The other parts like the config and Gemfile or the layout and includes directories are standard for a Jekyll project.

Resources:

• Creating a gem-based theme in Jekyll docs.
• Publishing your theme in Jekyll docs.
• Adding a theme to your GitHub Pages site using Jekyll guide on Github's help.

Install this theme in your project

There are three ways to install: as a gem-based theme, as a remote theme (GitHub Pages compatible), or forking/directly copying all of the theme files into your project.

Only a few standard themes are available on the locked GH Pages environment. So you must use this Remote Theme plugin to fetch your custom theme.

Use the remote theme approach to load a theme using GitHub details.

_config.yml

####
# --- Required configuration ---
####

# Set a branch name or version at the `remote_theme` value e.g. `@main` or `@v1.0.0`.
# Be careful if you omit the branch then automatically will be used `master`. 
remote_theme: "infotorg/infotorg-api-jekyll-theme@main"
plugins:
  - jekyll-remote-theme
  - jekyll-seo-tag

Other available options can be added later. See [Configuration] section.

Continue to Install project gems

While gems are locked on GH Pages, you can install custom gems like a theme if you use a CI flow. Such as with GH Actions or Netlifym.

With Gem-based themes, directories such as the assets, _layouts, _includes, and _sass are stored in the theme’s gem, hidden from your immediate view. Yet all of the necessary directories will be read and processed during Jekyll’s build process.

Update your project's _config.yaml:

####
# --- Required configuration ---
####
theme: infotorg-api-jekyll-theme

Other available options can be added later. See [Configuration] section.

To install from RubyGems:

• Gemfile

  source "https://rubygems.org"
  
  gem "github-pages"
  gem "infotorg-api-jekyll-theme"

To install from GitHub:

• Gemfile

  source "https://rubygems.org"
  
  gem "github-pages"
  gem "infotorg-api-jekyll-theme", git: "https://github.com/coderua/infotorg-api-jekyll-theme", branch: 'main'

Now install your gems locally. This is also needed on GH Actions. Netlify takes care of gems for you though.

Configure Bundler locally - only needed once.

$ bundle config set --local path vendor/bundle

Install project gems.

$ bundle install

To set up your environment to develop this theme, run bundle install.

To test the theme, run bundle exec jekyll serve --livereload --trace and open your browser at http://localhost:4000/. This starts a Jekyll server. As modifications are made to the theme and test site, it will regenerate and you should see the changes in the browser without a refresh.

Useful info for understanding where your theme gets installed based on the approach.

Themes downloaded from RubyGems usually install here:

• vendor/bundle/ruby/RUBY_VERSION/gems/THEME_NAME-THEME_VERSION

The Remote Theme plugin stores the theme in memory and not on disk with gems.

If you added your theme to your Gemfile directly and installed from GitHub URL, it will get installed here:

vendor/bundle/ruby/RUBY_VERSION/bundler/gems/THEME_NAME-THEME_VERSION

Where the version at the end is a hash (123456789abc) or a tag number (1.0.0).

See the gemspec file to see what dependencies get installed. This came with the scaffold. Update minimum Jekyll version.

Settings that affect your entire site can be changed in Jekyll’s configuration file: _config.yml, found in the root of your project. If you don’t have this file you’ll need to copy or create one using the theme’s default _config.yml as a base.

Note: for technical reasons, _config.yml is NOT reloaded automatically when used with jekyll serve. If you make any changes to this file, please restart the server process for them to be applied.

Take a moment to look over the configuration file included with the theme. Comments have been added to provide examples and default values for most settings.

To save yourself time setting Front Matter Defaults for pages is the way to go. Sure you can assign layout and toggle settings like show_navigationin each file, but that’s not ideal.

Using the default key in _config.yml you could set the layout and enable/disable navigation for all pages — in one shot.

Instead of adding layout: "default" and show_navigation: true to each page, apply as defaults in like so:

_config.yml

defaults:
  - scope:
      path: ""
    values:
      layout: "default"
      show_navigation: true

To change layout add layout: <LAYOUT_NAME> to its YAML Front Matter, overriding what was set in _config.yml. The same with the show_navigation.

Example:

---
layout: layout_name
show_navigation: false
---

site.lang is used to declare the primary language for each web page within the site.

Example: lang: "en-US" sets the lang attribute for the site to the United States flavor of English, while en-GB would be for the United Kingdom style of English. Country codes are optional and the shorter variation lang: "en" is also acceptable. To find your language and country codes check this reference table.

_config.yml:

lang: "en-US"

site.title is used to set a heading title for a page.

_config.yml:

title: infotorg API

It used as a part of title in a <title> tag as well. Let's imagine we have a "Security" page that looks like:

pages/security.md

---
title: Security
---

# The Security Guideline

Some other content...

And a configuration in the _config.yml:

#...

title: infotorg API

#...

As a result, in the html output we'll have a page.title and site.title together, separated by | delimiter.

<title>Security | infotorg API</title>

This is achieved by using jekyll-seo-tag plugin.

The site.subtitle sets a visible subtitle under the title on the page.

_config.yml:

subtitle: Onboarding guidelines and documentation

product_url used to set a direct url to a product on the Infotorg.no website. Default: https://www.infotorg.no/

_config.yml:

product_url: "https://www.infotorg.no/"

product_url_title used to set Sets the product link title. Default: Infotorg.no

_config.yml:

product_url_title: "Infotorg.no"

Will be shown only on a concrete API documentation page.

main_page_url used to set url to the main APIs page (a list of services, also called a lending page). Default: https://infotorg.github.io/

_config.yml:

main_page_url: "https://infotorg.github.io/"

main_page_url_title used to set a title to APIs page link. Default: Infotorg APIs

_config.yml:

main_page_url_title: "Infotorg APIs"

To enable Google Analytics, add the following lines to your Jekyll site:

google_analytics_tag_manager: GTM-XXXX

Customize a site navigational links through a Jekyll data file _data/navigation.yml

- name: Overview
  link: /
  show: true

- name: Security
  link: /security
  show: true

- name: Onboarding
  link: /onboarding
  show: false # won't be presented in a navigation

- name: FAQ
  link: https://faq.socialboards.com/infotorg/
  target: _blank # will opened in a new tab
  show: true

Optional keys:

• target - adds a target html attribute to a navigation link. Possible values are: _self, _blank, _parent, _top. [More details]
• show - Boolean flag shows/hides the navigation item. Possible values: true, false.

The theme gives you an ability to easily show links to external documentation resources.

1. Create a file with links to the documentation resources. By default, this is _data/documentation_links.yml.

_data/documentation_links.yml

- name: WSDL
  link: http://ws-test.infotorg.no/xml/EVRY/InfotorgKjoeretoey/2018-11-28/InfotorgKjoeretoey.wsdl
  target: _blank
  show: true

- name: XSD
  link: http://ws-test.infotorg.no/xml/EVRY/InfotorgKjoeretoey/2018-11-28/InfotorgKjoeretoey.xsd
  target: _blank
  show: true

- name: Documentation
  link: http://ws-test.infotorg.no/xml/EVRY/InfotorgKjoeretoey/2018-11-28/InfotorgKjoeretoey.xsd.xhtml
  target: _blank
  show: true  

Optional keys:

• target - adds a target html attribute to a navigation link. Possible values are: _self, _blank, _parent, _top. [More details]
• show - Boolean flag shows/hides the item. Possible values: true, false.

2. On a page you need the resources link use documentation layout

---
layout: documentation
title: Documentation
permalink: documentation
---

Or you can manually include documentations links instead of using layout.

---
title: Documentation
permalink: documentation
---
<h1>{{ page.title }}</h1>

{% include documentation_links.html links=site.data.documentation_links %}

documentation_links requires only links [see step 1 above].

NOTE: a page where you're including the documentation_links should have the .html extension, not .md.

The bread and butter of any theme. Below you’ll find the layouts included with the theme, what they look like and the type of content they’ve been built for.

NOTE: The theme is based on Bootstrap v5.0.0-beta1.

Feel free to use any Bootstrap features in your sites.

Refers to files within the _layouts directory, that define the markup for your theme.

• default.html — The base layout that lays the foundation for subsequent layouts. The derived layouts inject their contents into this file at the line that says {{ content }} and are linked to this file via FrontMatter declaration layout: default.
• documentation.html — The layout for automatic output external documentation links. [More Info.]
• services.html — The layout for your Services list. [More Info.]
• swagger-ui.html — The layout for your Swagger UI documentation that contain FrontMatter: layout: swagger-ui. [More Info.]

Each of the layouts injects all needed CSS and JavaScript to render your page correctly.

default.html is a flexible HTML layout for the site's landing-page / home-page / index-page.

documentation.html based on the default layout to show a list of links to external documentation defined in the _data/documentation_links.yml file.

services.html based on the default layout to show a list of services defined in the _data/services.yml file.

services.html is a flexible HTML layout for the to show Swagger UI.

Path to Open API file can be set in the openapi option in the _config.yml or via FrontMatter: openapi: /assets/openapi/YOUR_OPEN_API_FILE

pages/swagger-ui.html

---
layout: swagger-ui
title: Swagger UI
permalink: swagger-ui
openapi: /assets/openapi/YOUR_OPEN_API_FILE
---

NOTE: As a convention, all Open API files should be stored in the /assets/openapi folder.

Refers to snippets of code within the _includes directory that can be inserted in multiple layouts (and another include-file as well) within the same theme-gem.

• footer.html — Defines the site's footer section.
• head-app-css.html — Inserts CSS links.
• head-favicon.html — Inserts favicons for different sizes. Icons are located in the /assets/images/favicon directory
• head-fonts.html — Inserts fonts.
• head-google-analytics.html — Inserts Google Analytics module.
• navigation.html — Inserts navigation block (for desktop and mobile devices). Managing by show_navigation option in a global _config.yml or via FrontMatter: show_navigation: true/false
• title.html — Defines the site's main header section.
• documentation_links.html — Output external documentation links.

Refers to .scss files within the _sass directory that define the theme's styles.

• _variables.scss — SCSS variables which can be used anywhere in SCSS files.
• _bootstrap.scss — Bootstrap main file.
• _bootstrap_variables.scss — Used to configure bootstrap defaults.
• _typography.scss — Basic typography styles.

Refers to various asset files within the assets directory.

• assets/css/main.scss — Imports sass files from within the _sass directory and gets processed into the theme's stylesheet: assets/css/main.css.
• assets/css/print.scss — Print related styles and gets processed into the theme's stylesheet: assets/css/print.css
• assets/images — A folder with image assets.
• assets/images/favicon — A folder contains image assets for favicon.
• assets/images/icons — A folder contains icon image assets.
• assets/images/icons/services — A folder contains Infotorg API Services icons. *By default used in the services layout.

The theme comes with jekyll-seo-tag plugin preinstalled to make sure your website gets the most useful meta tags. See usage to know how to set it up.

Distributed under the MIT License.