Code folding with blogdown + Academic theme

Important

2024-06-08 I have ported my website to Quarto, which has native support for code folding. I’m leaving this post up despite the fact that the functionality is no longer relevant for this website.

2020-05-03 This post describes an implementation of code folding for an older version of the Academic Theme. It does not work with Academic 4.+. See my updated instructions to get it working with newer versions of Academic.

Rmarkdown documents now have a very nifty code folding option, which allows the reader of a compiled html document to toggle whether to view or hide code chunks. However, the feature is not supported in blogdown, the popular Rmarkdown-based website/blog creation package. I recently ran across an implementation of codefolding for blogdown, developed by Sébastien Rochette. I have been putzing around, trying to get it to work with my blog, which uses the Hugo Academic theme—alas, to no avail. To my amazement and good fortune, Sébastien swooped in with a pull request that cleaned up my blundering attempts at implementation. Now all of my posts have working code folding!

In this post, I’ll lay out how to make Sébastien’s code folding feature work with the Academic theme. To be totally clear, all of the hard bits of this were solved by Sébastien. I don’t know javascript to save my life, and my only contribution is to write down the instructions in what I hope is a coherent fashion, so that you too can soon be doing the happy code folding dance if you so desire.

1 Code folding with the Academic theme

1. You’ll first need to pull in some javascript assets. Create a folder called js under the \static directory of your site. Add the files transition.js, collapse.js, and dropdown.js from bootstrap.

2. Also add Sébastien’s codefolding javascript, codefolding.js.

3. Create a folder called css under the \static directory of your site. Add the file codefolding.css. This is the css for the buttons that will appear on your posts.

4. Add the file article_footer_js.html to the \layouts\partials directory of your site.

5. Add the file header_maincodefolding.html to the \layouts\partials directory of your site.

6. If you do not already have a file head_custom.html in the \layouts\partials directory, create it. Add the following lines of code to the file:

   {{ if not .Site.Params.disable_codefolding }}
     <script src="{{ "js/collapse.js" | relURL }}"></script>
     <script src="{{ "js/dropdown.js" | relURL }}"></script>
     <script src="{{ "js/transition.js" | relURL }}"></script>
   {{ end }}

7. If you do not already have a file footer.html in the \layouts\partials directory, copy it over from \themes\hugo-academic\layouts\partials. Add the following lines of code to it, somewhere towards the bottom:

   <!-- Init code folding -->
   {{ partial "article_footer_js.html" . }}

8. If you do not already have the file single.html in the directory \layouts\_default, copy it over from \themes\hugo-academic\layouts\_default. Add the following line of code at an appropriate point so that your posts will include the “Show/hide code” button (I put it after the title, before the meta-data):

    {{ partial "header_maincodefolding" . }}

9. Modify your config.toml file (in the base directory of your site) to include the following lines:

   # Set to true to disable code folding
   disable_codefolding = false
   # Set to "hide" or "show" all codes by default
   codefolding_show = "show"
   # Set to true to exclude the "Show/hide all" button
   codefolding_nobutton = false

   Also edit the custom_css parameter so that the codefolding.css file will get loaded:

   custom_css = ["codefolding.css"]

2 Using the codefolding parameters

The config.toml file now has three parameters that control code folding:

• disable_codefolding controls whether to load the code folding scripts on your site. Set it to true to disable code folding globally.
• codefolding_show controls whether code blocks will be shown or hidden by default. If your previous posts have lots of code in them, set the default to show to minimize changes in the appearance of your site.
• codefolding_nobutton controls whether the “Show/hide code” button will appear at the top of posts that include code blocks. Set it to true to disable the button but keep the other code folding functionality.

The above parameters are defaults for your entire site. To over-ride the defaults, you can also set the parameters in the YAML header of any post:

• Set disable_codefolding: true to turn off code folding for the post.
• Set codefolding_show: hide to hide the code blocks in the post (as in this post).
• Set codefolding_nobutton: true to turn off the “Show/hide code” button at the top of the post (as in the present post).

I hope these instructions work for you. If not, questions, corrections, and clarifications are welcome. Thanks again to Sébastien Rochette for working out this solution and for graciously troubleshooting my attempt at implementation. Happy blogging, y’all!