Upgrade middleman to version 4 #163
Conversation
|
Turns out it doesn't build on Ruby 3.0 when running I'm setting up a new docker image instead for Ruby 2.7. Also testing the favicon maker which was disabled in #154 |
|
Awesome @tombruijn ! No objections if it doesn't work with 3.0, if it works with 2.7 it's perfectly fine.
I see a lot of I'll take a closer look later, the change is huge. |
|
Hi @pirj, I managed to get the CSS to work yes.
I had to import/install all those bourbon and neat Scss files to get it to work. It looks like it's the recommended way to install it like this, and use At first I disabled bourbon and neat in one commit to get the basic CSS to work without also tackling bourbon and neat at the same time. And then later "installed" the two gems. I really see this as a temporary solution, and replace bourbon and neat later with a different solution. Not a lot of bourbon and neat is used, so that shouldn't be a huge task. |
|
I added two more commits that fix the This is now ready to review/merge! |
Upgrade middleman to the latest version available. It's easier to work with for me if I know I'm using the latest version when referencing the docs and comparing it to other upgraded middleman sites. Fix the merge conflicts in the `Gemfile.lock` to upgrade.
Fix page loading by adding file extensions to source files. This is needed for some files in the newer middleman versions.
Fix CSS generation by adding file extensions to source files. This is needed for some files in the newer middleman versions. Also update the paths in import statements to point to the locations of the files using a relative path. I disabled bourbon and neat for now. Bourbon itself is hardly used. Neat depends on bourbon, but is so far behind it can't be easily upgraded, as all helpers have since been replaced with a new set of helpers that are not compatible.
With bourbon disabled implement this mixin ourselves. It's a small addition and the site don't need all of bourbon for a couple of these mixins.
No need for a mixin if it's only used once.
The sources looks for this extension to find the blog articles.
Add page title so that people and search engines can see the page title.
Lock bourbon and neat on the older versions of the packages and "install" them into the project. I've run `bourbon install --path source/stylesheets` and `neat install --path source/stylesheets` to install the files directly in the project. Which is why this commit adds so many files. While almost no bourbon mixins are used anymore, it exposes some variables required by neat, like `$golden` and `$georgia`. Neat is no longer maintained and I suggest it is removed from the project and another grid system or CSS grid directly is used instead. Then both bourbon and neat can be removed. This solution is a quick fix so that the middleman 4 upgrade can be completed for now. If it's replaced all the added files can be removed again. I replaced almost all of the other Bourbon mixins with the now stabilized CSS properties. In earlier commits I've added a custom mixins `clearfix`, copied from what bourbon used.
The bundle still works on Ruby 2.7.2 as well. Add webrick gem to bundle for Ruby 3.0 as it's been removed from the standard gems in Ruby 3.0. Remove bigdecimal gem as that version fails to compile on Ruby 3.0. It's not needed for either Ruby version.
Fix the `ignored_sitemap_matchers` for partials. I copied the middleman implementation of this proc and adjusted the docs exception to work with the new method. The `source_file` object is now a struct with multiple versions of the source file path. The exception needed to be checked against the full path and not the relative_path that only included the filename and not the directories. In the proxy file generation for the "latest" version of the docs, that redirects to the actual latest version of the docs, I only selected the `.html` files. This should be okay, and I tested it works. But I had to add this filter because otherwise all the `.css` and `.js` files would be parsed as CSS and JavaScript files. That would then break because those included HTML and cause syntax errors during compilation. Previously in PR rspec#154 this solution was mentioned. I don't know the background here. I think the site doesn't also need to redirect the `.css` and `.js` files. Only the `.html` files redirection should be enough, as it will load the assets from the actual versioned docs.
I can't tell why it was considered broken as per a previous commit. It seems to generate favicons when I enable it.
9bf163e to
a1076c0
Compare
|
Thanks so much for this, I've built it (I used Ruby 2.7 locally) and I've pushed the result up to the staging repo: https://github.com/RSpec-Staging/rspec-staging.github.io / https://rspec-staging.github.io/ I'm going to double check it over the weekend then deploy it to our main docs too! |
|
Incredible job, thanks a lot @tombruijn! |
|
Thanks a lot @tombruijn ! 🙌🏻 I notice few CSS tweaks but probably not related. I will open a new PR. |
PR based on #154. Commits from that PR are not listed in this description.
Upgrade middleman to 4.3
Upgrade middleman to the latest version available. It's easier to work
with for me if I know I'm using the latest version when referencing the
docs and comparing it to other upgraded middleman sites.
Fix the merge conflicts in the
Gemfile.lockto upgrade.Fix page loading by specifying extension
Fix page loading by adding file extensions to source files.
This is needed for some files in the newer middleman versions.
Fix part of the CSS
Fix CSS generation by adding file extensions to source files.
This is needed for some files in the newer middleman versions.
Also update the paths in import statements to point to the locations
of the files using a relative path.
I disabled bourbon and neat for now. Bourbon itself is hardly used.
Neat depends on bourbon, but is so far behind it can't be easily upgraded,
as all helpers have since been replaced with a new set of helpers that are
not compatible.
Implement own clearfix mixin
With bourbon disabled implement this mixin ourselves. It's a small
addition and the site don't need all of bourbon for a couple of these
mixins.
Replace size mixing with basic implementation
No need for a mixin if it's only used once.
Fix blog by adding html extension to files
The sources looks for this extension to find the blog articles.
Set page title for blog index
Add page title so that people and search engines can see the page title.
Reinstall older versions of bourbon and neat
Lock bourbon and neat on the older versions of the packages and
"install" them into the project.
I've run
bourbon install --path source/stylesheetsandneat install --path source/stylesheetsto install the files directly in the project. Which is why this commit
adds so many files.
While almost no bourbon mixins are used anymore, it exposes some
variables required by neat, like
$goldenand$georgia.Neat is no longer maintained and I suggest it is removed from the
project and another grid system or CSS grid directly is used instead.
Then both bourbon and neat can be removed.
This solution is a quick fix so that the middleman 4 upgrade can be
completed for now. If it's replaced all the added files can be removed
again.
I replaced almost all of the other Bourbon mixins with the now
stabilized CSS properties. In earlier commits I've added a custom mixins
clearfix, copied from what bourbon used.Fix Ruby 3.0 compatibility
The bundle still works on Ruby 2.7.2 as well.
Add webrick gem to bundle for Ruby 3.0 as it's been removed from the
standard gems in Ruby 3.0.
Remove bigdecimal gem as that version fails to compile on Ruby 3.0. It's
not needed for either Ruby version.
Fix build by fixing partial filtering
Fix the
ignored_sitemap_matchersfor partials.I copied the middleman implementation of this proc and adjusted the
docs exception to work with the new method.
The
source_fileobject is now a struct with multiple versions of thesource file path. The exception needed to be checked against the full
path and not the relative_path that only included the filename and not
the directories.
In the proxy file generation for the "latest" version of the docs, that
redirects to the actual latest version of the docs, I only selected the
.htmlfiles. This should be okay, and I tested it works. But I had toadd this filter because otherwise all the
.cssand.jsfiles wouldbe parsed as CSS and JavaScript files. That would then break because
those included HTML and cause syntax errors during compilation.
Previously in PR #154 this solution was mentioned. I don't know the
background here. I think the site doesn't also need to redirect the
.cssand.jsfiles. Only the.htmlfiles redirection should beenough, as it will load the assets from the actual versioned docs.
Reactivate the favicon_maker plugin
I can't tell why it was considered broken as per a previous commit.
It seems to generate favicons when I enable it.