From 4e8e2889d44290e8b4f584c8e10ce2c4a01b1f34 Mon Sep 17 00:00:00 2001
From: jeffreytse <jeffreytse.mail@gmail.com>
Date: Sun, 4 Oct 2020 14:13:25 +0800
Subject: docs: update README.md

---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 47 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index d58b1ea..5c9c18c 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,14 @@ Also, visit the [Live Demo][yat-live-demo] site for the theme.
 
 ## Installation
 
+There are three ways to install:
+
+- As a [gem-based theme](https://jekyllrb.com/docs/themes/#understanding-gem-based-themes).
+- As a [remote theme](https://blog.github.com/2017-11-29-use-any-theme-with-github-pages/) (GitHub Pages compatible).
+- Forking/directly copying all of the theme files into your project.
+
+### Gem-based Theme Method
+
 Add this line to your Jekyll site's `Gemfile`:
 
 ```ruby
@@ -60,20 +68,53 @@ theme: jekyll-theme-yat
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install jekyll-theme-yat
+```bash
+$ gem install jekyll-theme-yat
+```
 
-## Usage
+### Remote Theme Method with GitHub Pages
 
-Add or update your available layouts, includes, sass and/or assets.
+Remote themes are similar to Gem-based themes, but do not require `Gemfile` changes or whitelisting making them ideal for sites hosted with GitHub Pages.
+
+To install:
+
+Add this line to your Jekyll site's `Gemfile`:
+
+```ruby
+gem "github-pages", group: :jekyll_plugins
+```
+
+And add this line to your Jekyll site's `_config.yml`:
+
+```yaml
+# theme: owner/name --> Don't forget to remove/comment the gem-based theme option
+remote_theme: "jeffreytse/jekyll-theme-yat"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+## GitHub Pages without limitation
+
+GitHub Pages runs in `safe` mode and only allows [a set of whitelisted plugins/themes](https://pages.github.com/versions/). __In other words, the third-party gems will not work normally__.
 
-GitHub Pages runs in `safe` mode and only allows [a set of whitelisted plugins](https://pages.github.com/versions/).
 To use the third-party gem in GitHub Pages without limitation:
 
-* Here is a GitHub Action named [jekyll-deploy-action](https://github.com/jeffreytse/jekyll-deploy-action) for Jekyll site deployment conveniently. 👍
+Here is a GitHub Action named [jekyll-deploy-action](https://github.com/jeffreytse/jekyll-deploy-action) for Jekyll site deployment conveniently. 👍
+
+
+## Usage
+
+Add or update your available layouts, includes, sass and/or assets.
 
 ## Development
 
-- 
cgit v1.2.3