Hi,
I’m trying to understand how to develop using remote_theme:. I use GitLab Pages to host my site and the theme is just-the-docs. I can make this work locally if just using theme: in the _config.yml, but I am unsure as to how to do this with remote_theme:.
Is there a way to run a remote theme locally so that one can make changes without having to check them into the repo to test? I’m wondering if I’m using this correctly.
Yes
You can use the Remote Theme plugin locally and GH Pages and any CI CI environment like for GitLabs.
I have a repo here that uses remote theme plugin. And is really light in number of files.
Note the config file and also Gemfile with Remote Theme gem.
That site exists on the gh-pages branch and pulls in the theme from the same repo on the master branch, but really you can point it at any theme on GitHub you want.
I think the remote theme plugin only exists because of the restriction on GitHub Pages to have the 10 or so standard themes only available with theme in config, but any valid GitHub repo can be used via the Remote Theme plugin.
You said GitLab Pages which I think won’t have that restriction, or it will work in a different way. so if you are not using GitHub Pages, I’d say don’t bother with Remote Theme.
Take for example this one. I have a project here which uses the plain theme config value and loads just-the-docs theme.
You can run it locally. And you can use the CI flow on GitHub Actions to build on GitHub. Or copy commands to whatever CI pipeline Gitlab might have.
I find Netlify actually great because it takes care of setting environment and installs your project gems and node packages for you, so only have to set the build command as a shell command and set a build directory.
Michael - thanks for your reply. The only thing throwing me right now is that I use GitLab Pages and you mention not to bother with remote them because of that. If that’s the case, I’m trying to understand how to add my content without having to add the theme so that my repo, as you say, is light in the number of files.
I don’t know how GitLabs works. But for a start you can get your project working locally with theme in your config and in your Gemfile. Then you can focus on the content.
You can of course clone my 2nd link and run it locally or copy code to your repo but it is all standard theme stuff.
Then when you have it running locally, you can set up GitLabs to do the install and build commands to match what you do locally.
I would recommend looking at GitLabs Pages docs to see if they give fixed gems or auto install from your Gemfile or you need to supply your own install command. And maybe find some tutorial articles on that, if the docs are too dry and not covering the end to end setup.
Actually, that’s about what I’ve already done. I had the site working locally, and then decided to refactor it for a remote theme so that I could always point it to an updated version of the theme as it evolved and not have to manage the updating of it myself. But I’ll always be adding content and therefore need a way to develop it locally before pushing/publishing.
I’ll keep at it and look over GitLabs pages a bit more. Thanks for your helpful comments, I think I’m on the right track.
Oh yeah the remote theme plugin gets the latest version of a plugin unless you explicitly lock to a tag like abc/def@1.2.3
You could do the same in a Gemfile.
One of:
gem 'some-theme' # unpinned
gem 'some-theme', '~> 2.5.1' # pinned
I would highly recommend against always pointing against the absolute latest version of a theme, if that’s what you’re thinking. Files can move around or be renamed and a layout might disappear, so if you autodeploy your site with the latest version of the theme (especially untagged, on master), then your site deploy might break or the deploy could work might the site will appear broken.
I like the approach as above of locking to a compatible version ~> 2.5.1 to get bug fixes, as 2.5.1, 2.5.2, etc. but without breaking changes allowed like 2.6.
If you are more risk-tolerant, you can do ~> 2.5 which means that it will be 2.5 or 2.6 or 2.7 etc. but not 3.
I also like using a Gemfile.lock approach. So I might lock at ~> 2.5 to let the major version float to 2.6, 2.7 etc. But because I have a Gemfile.lock, it will be locked at a 2.6.2 unless I specifically upgrade it.
Locally you would do
bundle update
When gets the latest versions of gems and subdependencies, but within the bounds of your Gemfile, and then gives you an updated Gemfile.lock which you can commit. And if you know the latest gems work locally, then you can push your deploy knowing that the versions you have locally will be exactly the same as the ones one the remote. But you can easily upgrade anytime with one command, instead of having to add a number in your Gemfile.
Hope that helps more.