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

How to use this project

Quickstart

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

[![Use this template](https://img.shields.io/badge/Use_this_template-2ea44f?style=for-the-badge&logo=github)](https://github.com/coderua/infotorg-api-jekyll-theme/generate)

Remove the Unnecessary

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

Demo

View a live demo on GitHub Pages:

[![GH Pages - View demo](https://img.shields.io/badge/GH_Pages-View_demo-green?style=for-the-badge)](https://coderua.github.io/infotorg-api-jekyll-theme/)

What is a Jekyll theme?

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.

About

Package a theme

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

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

Resources:

Installation

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}[https://github.com/coderua/infotorg-api-jekyll-theme/generate]/directly copying all of the theme files into your project.

Remote Theme method

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

Gem-based method

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.

1. Add to your config

Update your project's _config.yaml:

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

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

2. Add to Gemfile

To install from RubyGems:

“`ruby source “rubygems.org

gem “github-pages” gem “infotorg-api-jekyll-theme” “`

To install from GitHub:

“`ruby source “rubygems.org

gem “github-pages” gem “infotorg-api-jekyll-theme”, git: “github.com/coderua/infotorg-api-jekyll-theme”, branch: 'main' “`

Install project gems

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

Development and testing

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 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.

Installed path

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

GH Pages supported theme

Themes downloaded from RubyGems usually install here:

Remote Theme method

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

Gem-based method

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

Installed dependencies

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

Contents At-A-Glance

Configuration

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](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.

Front Matter Defaults

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](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 language

[site.lang](_config.yml) 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](https://msdn.microsoft.com/en-us/library/ee825488(v=cs.20).aspx).

`_config.yml`:

yaml lang: “en-US”


##### Site Title or *Main Heading*

[site.title](_config.yml) is used to set a heading title for a page.

`_config.yml`:

yaml title: infotorg API

![Site title screenshot](docs/screenshots/site.title.png)

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`

markdown

title: Security

The Security Guideline

Some other content…

And a configuration in the `_config.yml`:

yaml

title: infotorg API

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

html <title>Security | infotorg API</title>

This is achieved by using [jekyll-seo-tag](https://github.com/jekyll/jekyll-seo-tag) plugin.


#### Site Subtitle

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

`_config.yml`:

yaml subtitle: Onboarding guidelines and documentation

![Site subtitle screenshot](docs/screenshots/site.subtitle.png)

#### Url to a Product page

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

`_config.yml`:

yaml product_url: “www.infotorg.no/”

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

`_config.yml`:

yaml product_url_title: “Infotorg.no”

![Site subtitle screenshot](docs/screenshots/site.product_url.png)

#### Url to main page

> 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`:

yaml main_page_url: “infotorg.github.io/”

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

`_config.yml`:

yaml main_page_url_title: “Infotorg APIs”

![Url to Infotorg APIs main page screenshot](docs/screenshots/site.main_page_url.png)


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

yaml google_analytics_tag_manager: GTM-XXXX


### Navigation

![Site navigation screenshot](docs/screenshots/navigation.png)

Customize a site navigational links through a Jekyll data file [_data/navigation.yml](_data/navigation.yml)

yaml - name: Overview link: / 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.

How to use it

  1. Create a file with links to the documentation resources. By default, this is [data/documentation_links.yml](data/documentation_links.yml).

_data/documentation_links.yml “`yaml - name: WSDL link: ws-test.infotorg.no/xml/EVRY/InfotorgKjoeretoey/2018-11-28/InfotorgKjoeretoey.wsdl target: _blank show: true

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.

Layouts

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](layouts) directory, that define the markup for your theme.

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

Default Layout

{default.html} is a flexible HTML layout for the site's landing-page / home-page / index-page. <br/>

Documentation Layout

documentation.html based on the default layout to show a list of links to external documentation defined in the [data/documentation_links.yml](data/documentation_links.yml) file.

Services Layout

services.html based on the default layout to show a list of services defined in the [data/services.yml](data/services.yml) file.

Swagger UI Layout

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](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.

Includes

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

Sass

Refers to .scss files within the [sass](sass) directory that define the theme's styles.

Assets

Refers to various asset files within the assets directory.

Plugins

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.

License

Distributed under the MIT License.