infotorg-api-jekyll-theme

infotorg-api-jekyll-theme

Jekyll theme for Infotorg API

Download

Jekyll Infotorg APIs theme

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

=2.3-green?logo=ruby&logoColor=white title="Ruby - >=2.3" loading="lazy" />

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.

Remove the Unnecessary

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

Demo

View a live demo on GitHub Pages:

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

  • 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'

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

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:

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

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 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 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 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 or Main Heading

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.

Site Subtitle

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

_config.yml:

subtitle: Onboarding guidelines and documentation

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:

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"

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:

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"

Enabling Google Analytics

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.

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 

- 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.
  1. On a page you need the resources link use documentation layout ```yaml

layout: documentation title: Documentation permalink: documentation


Or you can manually include documentations links instead of using layout.
```html
---
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 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.

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

Services Layout

services.html based on the default layout to show a list of services defined in the _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 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 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 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.

minimalacademicresumeportfoliodocumentationwikitailwindbootstrapdarkecommercegithub-pagesblog