How to have Minimal theme up and running locally on Windows

Help
1

Hi there,

I’m struggling to have minimal theme (GitHub - pages-themes/minimal: Minimal is a Jekyll theme for GitHub Pages) up and running on Windows machine. Jekyll and Ruby are up and other themes running ok under my setup. But minimal requires following step for setup -
‘Run script/bootstrap to install the necessary dependencies’.

How can I do it on windows?

Thanks!

2

It looks like the Theme’s bootstrap script just installs Bundler and then runs bundle-install for the theme. So you could just do those steps manually (you probably already have Bundler installed):

It looks like the bootstrap script is only needed for local theme preview/development. If you just want use the theme, then I think you could probably just add theme: jekyll-theme-minimal to _config.yml.

3

I agree. Avoid using a fork of a theme and running a shell script in scripts dir. You’re going to have to deal with files and CI commands that you actually can ignore and don’t want to be slowed down by.

Plus if you install a theme using theme field can switch themes and upgrade theme versions without trying to see how your fork of 100 files differs from the original theme of 100 files. You just have to care about your few md files and config

BTW I have a project here which uses a theme on GH Pages using config approach above.

For local development, note how minima is covered in both config and Gemfile. Necessary so you can install the theme before serving.

You can try out my project locally or on GH Pages deploy yourself or browse the site and code.

4

Thank you both for reply.

I have already written theme tag in config.yml. This is what I get:

bundle exec jekyll serve
Could not find gem ‘html-proofer (~> 3.0) x64-mingw32’ in any of the gem sources listed in your Gemfile. Run bundle install to install missing gems.

There is a gemspec file with bunch of dependencies:
s.platform = Gem::Platform::RUBY
s.add_runtime_dependency ‘jekyll’, ‘> 3.5’, ‘< 5.0’
s.add_runtime_dependency ‘jekyll-seo-tag’, ‘~> 2.0’
s.add_development_dependency ‘html-proofer’, ‘~> 3.0’
s.add_development_dependency ‘rubocop’, ‘~> 0.50’
s.add_development_dependency ‘w3c_validators’, ‘~> 1.3’

This is the real reason for the issue - I don’t know how to install those gems. Should I just go ahead and remove them from the gemspec?

5

The html-proofer, rubucop, etc. gems are for developing jekyll-theme-minimal. To just utilize the theme, you’d use the pre-built Gem from jekyll-theme-minimal | RubyGems.org | your community gem host (Note that jekyll-theme-minimal requires Jekyll 3, not the current 4.)

Add it to your site’s Gemfile with:

gem 'jekyll-theme-minimal', '~> 0.1.1'

And set the site’s theme in _config.yml:

theme: jekyll-theme-minimal

After re-installing Gems with bundle, you should be able to build your site with the jekyll-theme-minimal.

1 Like
6

Chuck,

Thank you for the suggestion. I have removed those missing gems from the gemspec file and all seems to work, so far so good. BTW I don’t use fork for the sources - I have downloaded latest release of the theme as zip archive. Still it contains those dependencies for some reason.

Thank you!
Anton

7

Downloading a zip is close to forking, and we are advising against either of those approaches here.

Your aim sounds like to build a site which uses a theme. Not to build a theme. Or to mix theme and site in one.

Start a new project with a index.md page and config and Gemfile and nothing else, pointing to the theme as described above. That will keep your project super easy to manage.

To deploy the site, you just push to GitHub Pages and it will build for you. No CI scripts needed.

Locally you need

bundle config set --local path vendor/bundle
bundle install 

bundle exec jekyll serve

As you commands.

8

Why not fork a simple project like this.

Get it deployed without changing any values.

Then change the theme in Gemfile and config to use the theme you want and wait for it to redeploy.

9

Michael,

Thank you for your tips. The matter is I find design of Minimal theme appropriate to my needs with a little customization.
I’m new to gems and stuff. In general case, will running ‘bundle install’ setup all dependencies?

10

Update a fork of my suggested small repo to use the Minimal theme

gem 'jekyll', '3.9'

gem 'jekyll-theme-minimal', '~> 0.1.1'

When you run

bundle install

Then the theme and all its dependencies will be installed.

In this case just Jekyll SEO plugin.

I’d recommend setting Jekyll 3 in your Gemfile as i did above otherwise the theme will install Jekyll 4 for you.

And set theme in config as suggested in previous comments. This enables the theme locally and on GH Pages.

11

Regarding customizing a theme.

It isn’t so maintainable to copy an entire theme just to change a few lines. You forget what you wrote and what comes with the theme and you won’t understand how all the files fit together.

The Jekyll approach is that if you configure your site to use a theme and then add a file to your own repo to override.

For example if is a theme has 3 layouts

  • default.html
  • post.html
  • page.html

And I want to change post.html to maybe shown an icon for post heading.

I copy the whole post.html layout file to my project as

_layouts/post.html

And then I make my updates to the file. I don’t have to add the other layouts. I don’t even need an includes folder or layouts folder in my repo if those all come from the theme.

If I want to add a new layout, I just had author.html for example to my layouts folder.

Themes sometimes provide instructions of how to extend things like CSS so you can just add your own code to one file and have the theme CSS files of 100s of lines get quietly loaded for you.

12

Michael,

Thank you for detailed answer. I’m trying to include only those files that I touch into my repo. I assume if developers down the road change theme layout dramatically, it won’t brake my site since there’s original version number included in my configuration.

Thank you,
Anton

13

Indeed. You should lock the version of the theme in Gemfile. So if the theme changes drastically it won’t break your site.

Unfortunately you can’t control what version of the theme GH Pages gives you of the theme, but they do lock things and they change them slowly, if at all.

When it comes to using themes that are not on in the default set of 10 or so, you can choose one and lock it like this.

remote_theme: someuser/somerepo@1.2.3

You can even do that with the default supported Jekyll minimal theme if you wanted to lock down to a particular version that is new or old.

But I’d stick with the standard themes and standard approach as a beginner to get your site going. and then explore more options later.

14

Michael,

I got it. Thank you for the explanation. Your advice is very helpful.

пт, 26 февр. 2021 г., 11:59 michaelcurrin via Jekyll Talk <jekyllrb@discoursemail.com>:

1 Like