templates for self-hosting game jams (or any other kind of jam tbh)
veryroundbird.house
1# Installation
2> Install this theme in your project
3
4Two approaches are covered for installing the theme. The Remote Theme approach is necessary for plain GH Pages setup, while the second approach needs some kind of CI like GitHub Actions or Netlify. Both require only a few lines of code.
5
6
7## GH Pages Remote Theme flow
8
9Only 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.
10
11### 1. Add to the config
12
13Use the [remote theme](https://github.com/benbalter/jekyll-remote-theme) approach to load a theme using GitHub details.
14
15- `_config.yml`
16 ```yaml
17 remote_theme: MichaelCurrin/jekyll-theme-quickstart
18 ```
19
20Optionally set a version at the `remote_theme` value e.g. `@v1.0.0` or `@develop`.
21
22### 2. Add to Gemfile
23
24Update your project's `Gemfile`.
25
26- `Gemfile`
27 ```ruby
28 source "https://rubygems.org"
29
30 gem "jekyll', '~> 3.9"
31 gem "kramdown-parser-gfm", "~> 1.1.0"
32
33 gem "jekyll-theme-quickstart", git: "https://github.com/MichaelCurrin/jekyll-theme-quickstart"
34
35 group :jekyll_plugin do
36 gem "jekyll-remote-theme", "~> 0.4.3"
37 end
38 ```
39
40#### Notes
41
42- I recommend adding the `jekyll` part to lock to a certain version - especially if the theme allows 3 and 4 and so would upgrade you to 4.
43- By adding the theme to your Gemfile, you install the theme and its dependencies - if you don't do this you will likely get errors on a local build. When the build is run, the remote theme plugin is used to get the theme, so the locally installed theme is not actually used, but its dependencies are.
44- By using a _group_ as above, the plugin will be enabled for you so you do not have to add it to `plugins` in your config.
45
46Continue to [Install project gems](#install-project-gems)
47
48
49## Custom CI flow
50
51While 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 Netlify.
52
53### 1. Add to your config
54
55Update your project's `_config.yaml`:
56
57```yaml
58theme: jekyll-theme-quickstart
59```
60
61### 2. Add to Gemfile
62
63_TODO Update your version of this file on your new repo, using just **one** of the two approaches. Note the RubyGems approach needs sign-up and publishing on RubyGems site while the GitHub approach only needs a public repo to exist._
64
65To install from RubyGems:
66
67- `Gemfile`
68 ```ruby
69 source "https://rubygems.org"
70
71 gem "jekyll-theme-quickstart", "~> 1.0.0"
72 ```
73
74To install from GitHub:
75
76- `Gemfile`
77 ```ruby
78 source "https://rubygems.org"
79
80 gem "jekyll-theme-quickstart", git: "https://github.com/MichaelCurrin/jekyll-theme-quickstart"
81 ```
82
83
84## Install project gems locally
85
86Now install your gems locally. This is also needed on GH Actions. Netlify takes care of gems for you though.
87
88Configure Bundler locally - only needed once.
89
90```sh
91$ bundle config set --local path vendor/bundle
92```
93
94Install project gems.
95
96```sh
97$ bundle install
98```
99
100
101## Installed path
102
103Useful info for understanding where your theme gets installed based on the approach.
104
105### GH Pages supported theme
106
107Themes downloaded from RubyGems usually install here:
108
109- `vendor/bundle/ruby/RUBY_VERSION/gems/THEME_NAME-THEME_VERSION`
110
111### GH Pages Remote Theme flow
112
113The Remote Theme plugin stores the theme in memory and not on disk with gems.
114
115### Custom CI flow
116
117If you added your theme to your Gemfile directly and installed from GitHub URL, it will get installed here:
118
119```
120vendor/bundle/ruby/RUBY_VERSION/bundler/gems/THEME_NAME-THEME_VERSION
121```
122
123Where the version at the end is a hash (`123456789abc`) or a tag number (`1.0.0`).
124
125
126## Installed dependencies
127
128See the [gemspec](/jekyll-theme-quickstart.gemspec) file to see what dependencies get installed. This came with the scaffold. Update minimum Jekyll version.