Upgrading to Jekyll 3.x

i2000s commented 8 years ago

Hi Carl and fellows,

I am not sure if anyone is interested in upgrading Jekyll to 3.x. I did have a trial for testing some new features of the jekyll-scholar plugin, but got some errors. I can fix most of those errors, but I believe something related to the plugins of retrieving git commit history on the post sidebar couldn't go through. My repo is here on the Jekyll3 branch (need to switch Jekyll version to 3.x in Gemfile to reproduce my error), and the error can be found as below when I run jekyll serve:

Storing raw md versions as post metadata with raw_content.rb
Time elapsed 1.7986e-05 seconds

  Populating LSI... 
Rebuilding index... 
                      Liquid Exception: git '--git-dir=/media/E/SoftwareRep/GitHub/i2000s.github.io/.git' '--work-tree=/media/E/SoftwareRep/GitHub/i2000s.github.io' log '-1' '--no-color' '--pretty=raw' '_posts/_posts/2011-05-29-how-do-shocks-behave-in-inhomogeneous.html' 2>&1:fatal: ambiguous argument '_posts/_posts/2011-05-29-how-do-shocks-behave-in-inhomogeneous.html': unknown revision or path not in the working tree. Use '--' to separate paths from revisions, like this: 'git <command> [<revision>...] -- [<file>...]' in _includes/sidebar.html, included in _layouts/post.html
jekyll 3.1.6 | Error:  git '--git-dir=/media/E/SoftwareRep/GitHub/i2000s.github.io/.git' '--work-tree=/media/E/SoftwareRep/GitHub/i2000s.github.io' log '-1' '--no-color' '--pretty=raw' '_posts/_posts/2011-05-29-how-do-shocks-behave-in-inhomogeneous.html'  2>&1:fatal: ambiguous argument '_posts/_posts/2011-05-29-how-do-shocks-behave-in-inhomogeneous.html': unknown revision or path not in the working tree.
Use '--' to separate paths from revisions, like this:
'git <command> [<revision>...] -- [<file>...]'

Obviously, the filename/directory of the post has two _postses appeared. I have checked the way base_name.rb and other plugins to generate a filename (the PagePathGenerator is not working), but it seems those plugins do not matter to the error. Could anyone shadow a light on this error? I could be able to make it compatible with both Jekyll 2.x and 3.x if this problem is solved.

Thanks!

cboettig commented 8 years ago

Please note this repo is not current. The configuration in cboettig/2015 and in cboettig.github.io have been using Jekyll 3.x for some time.

i2000s commented 8 years ago

Really? I checked your cboettig.github.io repo before, but the plugins are the same. I don't see why Jekyll 2.x styled codes like

site.posts.each do |post|
      post.data['path'] = post.name
end

in the base_name.rb will work at all. In Jekyll 3.0, posts.each has been depreciated and should use collections to make it work, that is to use posts.docs.each. I know you have switched to docker, do you build the image based on Jekyll 2.x? Or, there are things I have missed?

cboettig commented 8 years ago

whoops, my mistake, I noticed that jekyll 3.x is on the docker image, but of course the jekyll version is still locked by the Gemfile (at 1.5 it looks, gosh but I remember transitioning to 1.0, haven't had time to keep up with the latest versions!)

Ideally I'd like to get away from most of my custom plugin scripts, since Jekyll is much more feature-rich than it used to be I suspect many of them aren't needed any more, and are more liabilities than assets with changing versions. Do those plugins do anything useful for you or can you build without them?

i2000s commented 8 years ago

Good question! I have indeed get rid of/replaced/no-need some plugins in practice (like the Google analytics and trying better citation tools with bibtex files). There are only a few plugins I don't know if there are any alternatives or implement their functionality using other plugins in Jekyll. I point out some on my top list:

base_name.rb: I believe it is only used to make the page.path only output the original markdown filenames of posts and pages. The new Jekyll 3.x has got rid of post.name method and redefined post.url and page.path to point to the relative url/directory to the post/base directory. I haven't figured out if we can do it easily in the new Jekyll base, and not sure if this plugin will affect the functionality to retrieve git commit histories for posts and pages. I have asked you on Stackexchange and posted a feature request to Jekyll.
raw_content.rb: I believe it is used to generate the raw code content for posts. Is it only used in post exception template and the base_name.rb plugin? The exception summary may not need the plugin at all now. Confirm?
Plugins related to git commit history/sha info retrieval. This will affect the sidebar of post pages heavily, and may be related to the error above. I have indeed found one alternative for Jekyll post revision, but I am not sure if it can completely replace git_sha.rb and git_mod.rb and the sidebar template is the only place to use these plugins.

cboettig commented 8 years ago

Okay, just took a quick look and the 2015 notebook it appears I did make some changes a while back that at least my git log claims made things compatible with Jekyll 3.0: https://github.com/cboettig/2015/commit/e82ab19f1070584f4012fe2b04a882523b9f9043

Note this included removing both raw_content and base_name. So maybe the 2015 repo setup will work with 3.0 for you? IIRC, those were being used for the previews on the lab-notebook pages, e.g. http://www.carlboettiger.info/2015/lab-notebook, from _includes/post_excerpt.html, which I think I could avoid now that post.content has been built in.

Right, the sha/git mod stuff is kinda nice for that metadata and not likely to ever be something built into Jekyll. I still kinda like my plugins for a simple static twitter / github / rss feeds, but they are admittedly crude.

i2000s commented 8 years ago

@cboettig Thank you for the quick followup. My overlook on the 2015 repo. It seems working now by a small tweak on the sidebar.html template:

On the first line to retrieve the true_path information, it actually generates a string of direction relative to the base url in Jekyll 2 and 3. Therefore, in the lines where the true_path is used to generate a URL to the hash tag, I deleted the _posts/ string before true_path and then everything works in Jekyll 3.1.6 on my computer :)

Feel free to test and upgrade. Thanks.

cboettig commented 8 years ago

great. Yup, looks that's the same change I had to make: https://github.com/cboettig/2015/commit/e82ab19f1070584f4012fe2b04a882523b9f9043#diff-88116a8ad5517e8b9bfd0e9911642382L51

i2000s commented 8 years ago

Actually I have to delete another _posts/ in the url line. So, line 51 in your commit will become

... SHA Hash: <a href="https://github.com/{{site.author.github}}{{ site.baseurl }}/commit/{{ true_path | git_sha }}/{{ true_path }}"> {{ true_path | git_sha }}</a>

Same to line 28 to delete the _posts/.

cboettig commented 8 years ago

ah, thanks for clarifying. so now all the references to _posts are gone instead of just one of them. Maybe that changed between 3.1 and 3.0. Thanks for catching that.

i2000s commented 8 years ago

Sorry, just found another related error and didn't bother to make a PR. In the sidebar code again, the section to show the modification time should also be updated accordingly. Here is my code to make it work.

{% capture page_modified %}{{ true_path | git_mod }}{% endcapture %}
 {% if page_modified %}
  <p><small> Updated: <time
            datetime="{{ true_path | git_mod }}"
            property="dc:modified">{{ true_path | git_mod | date_to_string }}</time></small></p>
  {% endif %}

cboettig commented 8 years ago

Nice, thanks!

cboettig / labnotebook

Upgrading to Jekyll 3.x #125