Docs website: convert to using Jekyll

The initial homepage was set up in HTML as it (temporarily) had to be hosted elsewhere.

The intention was always to use GH Pages for hosting the site and to use Jekyll to generate the homepage content based on the `README` of the project.

To allow for that to happen, some changes were needed which are contained in this PR.

1. Add a `Gemfile` pointing enabling the GH Pages gem, including enabling a new GH flavoured markdown interpreter.
2. Add a `_config.yml` file.
    - Enable the new GH flavoured markdown interpreter.
    - Set the theme.
    - Enable a variety of plugins.
    - Add the `repository` and `github` keys to allow for local testing.
    - Add a range of keys with information for the theme and SEO plugin.
    - Explicitly exclude a number of files from being included in the generated site.
3. The initial homepage was already based on the GH Pages Jekyll `minimal` theme.
    To allow the site to take full advantage of that, most copied in files from the theme can be removed as they will automatically be added now, as well as updated when needed.
4. A `.gitignore` file is put in place to ignore the typical Gem related files as well as the Jekyll output in `_site` from being committed.
5. A `.nojekyll` file is put in place in the `phpdoc` subdirectory to prevent Jekyll trying to parse the PHPDocumentor generated documentation.
6. The CSS customizations have been moved from the (theme generated) `style.css` file to `style.scss`.
    This makes it crystal clear what the customizations are and what comes from the theme.
    The Jekyll build will combine the CSS into one `style.css` file for the generated site.
7. The theme `_default.html` layout has been copied in from the theme and minimal adjustments have been made to:
    - Overrule the syntax highlighting styles by setting a separate stylesheet for those.
    - Add the "Read the docs" button in the left column.
    - Add the "Install using Composer" section in the left column.
    - Add the Twitter share button in the left column.
8. Add a `robots.txt` file pointing to the plugin generated XML sitemap fo search engines.
9. Replace the `index.html` file with an `index.md` file which contains the same basic contents as the `README.md` file.
    Includes making a few small adjustments to the `README.md` file.
    This should now allow for doing a plain copy & paste of the README content into the `docs/index.md` just before each release to update the homepage to the latest content.
    Note: there is a "readme to index" plugin available, but that does not allow for the readme and the docs being in different directories.
    A [feature request](benbalter/jekyll-readme-index#19) to allow for that has been opened.

Once this is merged, to update the website means:
1. Running PHPDocumentor.
2. Copy & pasting the content from the `README.md` file to `docs/index.md` (and double-checking the few remaining differences are intact).
3. Once those changes have been merged and `develop` has been merged into `master`, the website should be updated.

The website can be viewed locally by running:
```bash
bundle update
bundle exec jekyll serve
```
and then visiting http://localhost:4000/ to see the result.

Author: jrfnl

README.md

@@ -31,10 +31,12 @@ PHPCSUtils: A suite of utility functions for use with PHP_CodeSniffer
 Features
 -------------------------------------------
 
-This is a set of utilities to aid developers of sniffs for [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer).
+[PHPCSUtils](https://github.com/PHPCSStandards/PHPCSUtils) is a set of utilities to aid developers of sniffs for [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer).
 
 This package offers the following features:
 
+<div id="feature-list">
+
 ### Use the latest version of PHP_CodeSniffer native utility functions.
 
 Normally to use the latest version of PHP_CodeSniffer native utility functions, you would have to raise the minimum requirements of your external PHPCS standard.
@@ -71,6 +73,7 @@ A `PHPCS23Utils` standard which allows sniffs to work in both PHPCS 2.x and 3.x,
 
 To see detailed information about all the available abstract sniffs, utility functions and PHPCS helper functions, have a read through the [extensive documentation](https://phpcsutils.com/).
 
+</div>
 
 Minimum Requirements
 -------------------------------------------
@@ -216,6 +219,8 @@ Once that's done, you will need to make a small tweak to your own dev environmen
 Frequently Asked Questions
 -------
 
+<div id="faq">
+
 #### Q: How does this all work without an external standard needing to register an autoloader?
 
 A: As PHPCSUtils is registered with PHPCS as an external standard and PHPCSUtils complies with the naming requirements of PHPCS, the PHPCS native autoloader will automatically take care of loading the classes you use from PHPCSUtils.
@@ -232,6 +237,7 @@ A: The backfill for PHP 7.4 numeric literals with underscores in PHP_CodeSniffer
 
 The backfill was fixed in PHP_CodeSniffer 3.5.4.
 
+</div>
 
 Contributing
 -------
@@ -241,4 +247,4 @@ If you are unsure whether the changes you are proposing would be welcome, please
 
 License
 -------
-This code is released under the GNU Lesser General Public License (LGPLv3). For more information, visit http://www.gnu.org/copyleft/lesser.html
+This code is released under the [GNU Lesser General Public License (LGPLv3)](http://www.gnu.org/copyleft/lesser.html).

docs/.gitignore

@@ -0,0 +1,4 @@
+_site/*
+Gemfile.lock
+.sass-cache
+*.gem

docs/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem "github-pages", group: :jekyll_plugins do
+  gem 'jekyll-commonmark-ghpages'
+end

docs/_config.yml

@@ -0,0 +1,36 @@
+baseurl: /
+highlighter: rouge
+markdown: CommonMarkGhPages
+encoding: UTF-8
+theme: jekyll-theme-minimal
+repository: "PHPCSStandards/PHPCSUtils"
+github: [metadata]
+url: "https://phpcsutils.com"
+
+plugins:
+    - jekyll-github-metadata
+    - jemoji
+    - jekyll-mentions
+    - jekyll-seo-tag
+    - jekyll-sitemap
+
+phpcsutils:
+    packagist: phpcsstandards/phpcsutils
+
+# Theme info.
+title: PHPCSUtils
+description: "A suite of utility functions for use with PHP_CodeSniffer."
+logo: 
+show_downloads: false
+google_analytics:
+
+# SEO info.
+tagline: "PHPCSUtils: A suite of utility functions for use with PHP_CodeSniffer."
+twitter:
+  username: jrf_nl
+  card: summary
+  hashtags: PHPCSUtils
+author:
+  twitter: jrf_nl
+
+exclude: ['CNAME', '.gitignore', 'Gemfile', '*.bak', '*.orig']

docs/_layouts/default.html

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html lang="{{ site.lang | default: "en-US" }}">
+  <head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+{% seo %}
+    <link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
+    <link rel="stylesheet" href="{{ "/assets/css/syntax.css?v=" | append: site.github.build_revision | relative_url }}">
+    <!--[if lt IE 9]>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv.min.js"></script>
+    <![endif]-->
+  </head>
+  <body>
+    <div class="wrapper">
+      <header>
+        <h1><a href="{{ "/" | absolute_url }}">{{ site.title | default: site.github.repository_name }}</a></h1>
+        
+        {% if site.logo %}
+          <img src="{{site.logo | absolute_url }}" alt="Logo" />
+        {% endif %}
+
+        <p>{{ site.description | default: site.github.project_tagline }}</p>
+
+        {% if site.github.is_project_page %}
+        <p class="view"><a href="{{ site.github.repository_url }}">Visit the Project on GitHub <small>{{ site.github.repository_nwo }}</small></a></p>
+        {% endif %}
+
+        <p class="docs"><a href="{{ "/phpdoc/index.html" | absolute_url }}">Read the Documentation</a></p>
+
+        <div class="install">
+            <a href="https://packagist.org/packages/{{ site.phpcsutils.packagist }}">Install using Composer:</a><br>
+            <div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>composer require <span class="s">{{ site.phpcsutils.packagist }}</span></code></pre></div></div>
+        </div>
+
+        {% if site.show_downloads %}
+        <ul class="downloads">
+          <li><a href="{{ site.github.zip_url }}">Download <strong>ZIP File</strong></a></li>
+          <li><a href="{{ site.github.tar_url }}">Download <strong>TAR Ball</strong></a></li>
+          <li><a href="{{ site.github.repository_url }}">View On <strong>GitHub</strong></a></li>
+        </ul>
+        {% endif %}
+
+        <p><a href="https://twitter.com/share" class="twitter-share-button" data-related="{{ site.twitter.username }}" data-count="none" data-hashtags="{{ site.twitter.hashtags }}">Tweet about it</a></p>
+
+    </header>
+
+      </header>
+      <section>
+
+      {{ content }}
+
+      </section>
+      <footer>
+        {% if site.github.is_project_page %}
+        <p>This project is maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a></p>
+        {% endif %}
+        <p><small>Hosted on GitHub Pages &mdash; Theme by <a href="https://github.com/orderedlist">orderedlist</a></small></p>
+      </footer>
+    </div>
+
+    <script src="{{ "/assets/js/scale.fix.js" | relative_url }}"></script>
+    {% if site.google_analytics %}
+    <script>
+      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+      })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+      ga('create', '{{ site.google_analytics }}', 'auto');
+      ga('send', 'pageview');
+    </script>
+    {% endif %}
+
+    <script type="text/javascript">
+        !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');
+    </script>
+  </body>
+</html>