Update the GHPages site

[jrfnl]

This PR is the outcome of a review of the GH Pages website as published on https://requests.ryanmccue.info/ in anticipation of the site needing to be updated for the 1.8.0 release.

The review focused on a number of things:

• What is the effect when the site is regenerated with the current version of the GHPages gem ?
• Are there any "smart fixes" which could be applied to make updating the site easier ?
• Is the information on the site still relevant/correct ?

This PR is not 100% ready yet for the 1.8.0 release.

To dos:

• Regenerate the API docs once 1.8.0 has been tagged.
• Run the build script once README: fix code blocks #462 and Docs: update content and various tweaks to the markdown #465 have been merged and 1.8.0 has been tagged. (done manually for now)
• Possibly update the CI status badges if CI: switch to GitHub Actions for PHP 5.5 - current #467 gets merged for the 1.8.0 release.

Also see issue #466

Commit details

GH Pages: add Gemfile

A GH Pages site needs a Gemfile to be able to generate and to allow for testing locally.

It may be that in the past this was not a hard requirement, but either way, it is good practice to have the file in place.

Includes adding the lock file to .gitignore and both the Gemfile and the lock file to the list of files which should not be copied over into the live website.

.gitignore: add more files which should be ignored

GH Pages: add a simple favicon

... to stop Jekyll complaining about the favicon.ico file missing.

Note: I've not added any code to the page header for the favicon as all modern browsers will pick up on it automatically anyway.

GH Pages: make the API documentation more discoverable

At this moment, there is only one link to the API documentation and it is hidden away on the first page of the "Documentation" page where it can be easily overlooked.

This adds a new menu item in the main menu at the top of the page linking to the API Docs for improved discoverability.

GH Pages: fix code block and syntax highlighting

Code blocks and inline code snippets were no longer parsed correctly.

Additionally, in the previous generated site, the syntax highlighting of code was already broken.

This commit fixes both.

Includes:

• Adjusting the script which adjusts the files from the master branch and pulls them into the gh-pages branch.
  The string replacement for PHP code blocks is no longer needed and actually detrimental.
• Removing most {% highlight ... %} liquid syntax in favour of markdown fenced code blocks.

GH Pages: use the GH API

During the generation of the site, select information from the GitHub API is available in the site.github object.

Using that information will allow for automatically updating "frequently" changing - and easily forgotten - content and will lower the maintenance burden.

This commit:

• Enables the use of the GH API via the jekyll-github-metadata plugin.
• Ensure that this will work when testing the site locally by adding a repository key to the config.
• Adds the retrieved data cache file to the .gitignore and the site building exclude list.
• Use URLs from site.github to refer to various parts of the repository.
  This will automatically update the URLs in the website for the move to the WordPress organisation.
• Use the site.github.latest_release.tag_name key to automatically update the version number of the last release in all the relevant places whenever the site is regenerated.
• Automate the generation of the "Previous versions" list on the Download page based on the information from the GH API.

Ref: https://github.com/jekyll/github-metadata/blob/master/docs/site.github.md

Also:

• The gems key is deprecated. Replaced by plugins.

GH Pages: use absolute URLs

... in templates used throughout the site and create those absolute URLs the Jekyll way.

This will create the URLs as absolute URLs for the online version of the website, while for local testing relative URLs will be used.

GH Pages: add a custom variable array

This commit:

• Adds a custom site.requests array to the config file for information used in various places in the site.
• And then updates the site to use those variables instead.

This will make it easier to update this information througout the site in one go.

GH Pages: add a robots.txt file

GH Pages: minor other tweaks

• Blank line between frontmatter and the page title.
• Update the URL for Composer.

GH Pages: expand the lists of files which should not be copied into the site

Any files in the root directory and in directories which don't start with a _, will normally be copied into the site and depending on settings be processed for variables and markdown parsing.

The exclude key allows to ignore select files during site generation.

This commit:

• Expands the list with:
  • the Jekyll defaults as the list overwrites the defaults;
  • various files already in the branch, which should not be copied to the site;
  • a few common backup file types which may be present while working on the site locally.
• Adjusts the format of the key for readability.

Ref: https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml#L37-L55

GH Pages: update the "docs" directory

Sync the files in the docs subdirectory with the changes made in the master branch.