After almost one year of interruption, I started re-using blogdown again. But instead of writing new content, I had to struggle once again using the sophisticated machinery of Hugo and my academic-theme. With painful experiences, I learned that one has to be cautious with updates to prevent breaking changes. In this post, I will report on my Odyssean experience and — more important — I will suggest guidelines on how to start, explore, and use themes in blogdown.
Finally — after almost one year of interruption — I could reorganize my working responsibilities to spend more time working with
But (re-)starting blogging using these tools was not easy after such a long period. I did not only forget many procedures but also ran into compatibility problems with the necessary updates. It turned out for me that the R Markdown ecosphere produces not only valuable and powerful tools but is a continuously changing complex still stricken with some fragilities.
After reporting on these difficulties, I will summarize the lessons I learned.
Last year I was intrigued by the potent docdock theme. It has many dynamic features (aka
shortcodes) and is uniquely good suited for complex structured information. I have learned in my posting career with WordPress on Gedankensplitter that over time, new subjects emerge and require a change of the content structure. I was especially delighted that
docdock could produce dynamic HTML slides with the reveal.js framework, which I planned to use for tutorials and teaching.
After updating my software machinery (R, R packages, Hugo), I also installed a new release of the
docdock theme. And here the odyssey started! I got many error messages which I could not solve. One problem was that I tweaked the theme (sacrificing several days of my summer holiday last year) without the necessary profound knowledge of the way
Hugo works. Another problem was that after not using blogdown such a long time, I had forgotten many procedures of the interplay between
After several days of work, I did not manage to get a functional website. Worse! Meanwhile, I had destroyed my old (functioning) website as well. 😰 This disaster was for me an involuntary learning occasion to dive into Git and GitHub to save my work and restore my repo. I had not worked on a sub-branch and had carelessly committed changes that destroyed my web presence.
To avoid similar issues, I started a clean installation of
blogdown with the
docdock theme. This time I did not get error messages, but experienced another surprise! The theme style I preferred had other (new) problems: The display of code snippets was not correct anymore and destroyed the page layout. I reported this issue to the theme author. Only now I noticed that the author does not respond to questions. On the issue page of the
docdock repo, I found the following message from another user:
Is this theme still maintained? Issues and PR’s seem to indicate not. I’m looking to add a documentation theme, but I’m not interested in adding one that’s been abandoned. (Issue 151)
This question is now unanswered for more than 20 days. :angry: I do not blame the theme author. People have to work for a living; they donate their work and experiences to us whenever it is possible. But how could I be so naive only to judge my theme selection by the functionality of the theme? Not taking into account the sustainability of the theme, e.g., its complexity related with its life cycle (updates, bugs), the responsiveness of the author, the community of people using this theme and helping each other!
At that moment, I abandoned the
docdock theme heavy-heatedly. I had put so much work into its adaption! And I like its functionality and design! Yes, I could still use my working version, but then I will lose future
Hugo features. I didn’t trust this theme anymore.
Now I decided to choose a more simple theme and started with the recommended theme list in the blogdown book. The only theme I liked from its design was ghostwriter. I installed it without problems and began using it. My first project was to learn the Xaringan package in combination with
blogdown. I stumbled about it reading the new R Markdown book. It could be a way to replace my beloved html5 slide functionality from the
docdock theme. Instead of producing slides using reveal.js, I had now to learn with remark.js another tool. But Yihui Xie — the author behind all this fantastic stuff in the
R Markdown ecosphere like knitr,
xaringan, etc. — explained convincingly why remark is preferable to other slide frameworks (e.g., slidy.
To shorten a long story: After several hours trying to bring
Xaringan to work — I followed the simple synopsis by Tim Mastny in his blog entry Embed Slides in Your Blog — it turned out that in the
ghostwriter theme files in the static folder are not rendered and uploaded. This insight came as a big surprise for me! I thought that it is a standard procedure that all files under the
static/ directory are copied to
public/ when Hugo renders a website. Only when I found an entry by Amber Thomas on Stack Overflow — one of the co-authors of the blogdown book — I learned that this could be possible.
The problem was — at least for me — a tricky one. The website worked locally but not when I deployed it with Netlify. Even when I noticed that there were no static files uploaded in my repository, I still thought it was me, who did something wrong. As a novice user, I always believe that the problem is on my side. But after many fruitless trials, I came up with the idea to try it out with another theme. So I installed the Xmin theme and learned that everything I did was done correctly.
I abandoned the
ghostwriter theme much more relaxed than before the
docdock theme. I was not yet emotionally linked to the theme and had (thankfully) not started with adaption work. I learned from this experience that it is an excellent strategy to test things out with the two minimal themes
Xmin or Lithium, which provides a stable reference point.
But how to proceed now? Should I stick with
Xmin to be on the secure side? But I do not like this theme from its appearance. Also, my CSS knowledge is feeble, and I do not want to spend much learning and working time to adapt its design.
So my next choice was the academic theme. Last year I had already experimented with it, and it is one of the (more complex) recommendations in the
blogdown book. It is a very elaborated theme with fantastic features designed for academic usage. But precisely or targeting the academic community, was the reason why I decided last year against this theme.
I am looking forward to my retirement, and I am fed up from all the administrative university business: The thought of (re)presenting all details of my scientific work and especially to transfer more than 120 publications from my
WordPress blog to the blogdown academic framework made me furious. All I was looking for was a decent blog framework open for all the helpful tools from the R Markdown ecosphere.
But incidentally, just at the same time, I noticed problems with some of the
WordPress plugins dynamically serving my list of publications. Besides, I understood that I am not forced to use all sections of the academic framework: I could focus on the posts section — and maybe add later on some other parts.
So I returned to my abandoned experiments with the
academic-theme as I already did some configuration and had even written some content. First of all, I updated it to the new version and … — Yes, again I ran into troubles! After some trials, I noticed a wired problem: It took me two days to narrow down the error. It turned out that with one of the last update, the
academic theme was not compatible with blogdown anymore! I reported this issue to the RStudio community, to George Cushen and Yihui Xie.
Can you imagine my emotional state? I changed between desperation and depression. All in all, it took me already two weeks with the result that I had accomplished nothing!
After taking a short nap to calm down, I reconsidered my situation: Yes, it took me much time, but at the same time, I learned a lot. I am not referring primarily to my speed generating a new
blogdown website from scratch with a
GitHub repo and deployed by
Netlify (It takes my now only 60 seconds 🚀). But hopefully, I will not need this skill so frequently in the future. 😊 In addition to being more comfortable with
Github, I had learned general strategies to avoid similar problems in the future!
And there also came some encouraging signals from the community: Both — Georg Cushen and Yihui Xie — responded almost immediately to my posts. Even the problem was not solved at that time; I decided to stick with the
academic-theme. From some other interactions (issues and questions to the theme), I had built up trust to the theme author. George is committed to his theme and very busy to deliver the best product possible. So after a roll back to an older version, I began with this article. As it stands now, this was the right decision. George and Yihui solved the issue together within two days.
The following list is an attempt to turn my Odyssean experience into constructive advises for other users. I am sure it is not complete and maybe in some points faulty. If you disagree or have other, better tips: please comment on this post!
I am not going into details, and I take for granted some basic knowledge/experience with
RStudio / blogdown / Git / Github and Netlify. To have read the blogdown book is another requirement.
Most important: In choosing a theme do not only focus on functionality and pleasing design.
Git/Github. Instead of forking and synchronizing repositories, I prefer to install updates via ZIP files.
Most important: Do not begin with adapting the design of the theme.
themes/<your-theme-name>/exampleSiteto your project directory. Not the folder itself, but just the content inside (e.g., the folders
config.toml). Overwrite these files in your project directory — it is only a site for testing.
config.toml. Adapt this configuration file to your needs. Make notes not only how but also why you did which setting. Documenting these changes could be helpful later when you have already forgotten you initially considerations and the procedures to follow.
RStudioaddins plugin (CTRL-S on my machine) provided by the
Google Chromebrowser for detailed inspection and use the
RStudioviewer pane only for a general overview or to look up a specific change.)
Build -> More -> Clean Allfollowed by restarting
R. And again
blogdown::serve_site()to update locally.
Netlifyhas deployed the site, I inspect the live result.
RStudioproject. Changes on these files will overwrite the virgin theme. One the one hand, your changes are all collected in one place and separated from the original theme. On the other hand, new versions of the theme will not override your changes.
RStudioproject, create a new
Gitbranch and check it out (= change to it). If anything goes irreparably wrong (and believe me: eventually in the long term this will be the case!) you have not destroyed your current web presence. After my odyssey, I worked with two branches besides master:
configfor bigger changes (new version of the theme, changing the configuration or the structure of my site) and
blogfor my daily (writing) work. If you decide to merge your branch with
masteryou will have an additional security level:
Netlifywill check if anything went smoothly before your branch is merged with master. If something went wrong, you would abstain from merging your branch.
Most important: Keep calm and RTFM!
blogdown <name of your theme> <error message>or different appropriate combination of content. Most of the time, you will get results linked to questions in Stack Overflow or blog posts where other users reported about the same or similar problems.
XMintheme and try to reproduce the problem. If it works there, then the problem has to do with your theme or the changes you have made.
repex,) and report the problem at Stack Overflow. Your replication on the otherwise empty reference site will help you to focus on the essential question and will also provide an excellent reproducible example.
Update (2019-06-03): As you can see from the footer, this website is using the
docdock- and not the
academic theme I wrote above. I started with the
docdock and abandoned it for reasons I mentioned above. After another year of creative abstinence of blog writing, in May 2019, I fired up the
blogdown machinery again. But because of a combination of many updates of
Hugo (from 0.27 to 0.55.6!) and the
academic theme (from 2.4 to 4.3), I not only ran into a bunch of error messages, but I have also lost track of different breaking changes and couldn’t recover. —😳
So I changed to
docdock back, but this time with somewhat more knowledge. Hopefully, my activities were not a circle but a helix movement where I managed some advances. Thinking positively, hopefully, I can stick with this theme in the future. I do not want writing another complaining article next year, addressing the same problems again.
Update (2019-06-07): The reason for my problems mentioned above was an old version of pandoc. I had installed “pandoc-1.19.2-29-jan-2017”, but the latest release of the date of this writing is “pandoc-2.7.2-5-april-2019”. Now I could successfully update Hugo to “v0.55.6” By this occasion I also updated jQuery v2.2.3 to v.3.4.1.
Now there wouldn’t be any reason not to return to the
academic theme. But I had worked hard the last week and learned so much about my
docdock theme, that I am feeling now very comfortable and will stick with it.
This work by Peter Baumgartner is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
Permissions beyond the scope of this license may be available at http://notes.peter-baumgartner.net/contact. Powered by the docdock theme for Hugo.
Privacy | Disclaimer