blogdown | Thought splinters

Announcing the R package coinsR

Fri, 02 Aug 2019 00:00:00 +0000

Update 2021-05-21: Because of some breaking changes in the Hugo site structure and management in the last three years, coinsR works at the moment only with individual pages.

This blog entry announces the R program coinsR to produce bibliographic metadata automatically for websites within the Hugo framework. The dominant use case at the moment is with the blogdown package.

In a previous blog entry I wrote about the advantages of providing bibliographic metadata for your web pages producing COinS. COinS is the abbreviation of Context Objects in Spans. It refers to a microformat standard to embed bibliographic metadata as HTML.

A COinS string includes HTML code for all the information necessary to cite a publication correctly. It works for every type of writing (books, papers, web pages). COinS embedded in your HTML pages help your blog readers or website visitors to cite your posts and pages correctly.

I wrote also a detailed tuorial how to produce COinS with the help of the free bibliographical research tool Zotero. But this is a quite complicated procedure with several steps. Besides, it works only for every page individually and not automatically for all blog entries of your website.

To produce COinS for every web page quickly was my motivation to write the R package coinsR.

Use cases of `coinsR` and its limitations

The package requires:

Hugo with the R package blogdown
Config file in the TOML format (config.toml)
Blog entries with YAML frontmatter

I plan for a future version to loosen the last two limitations and allow config.yaml and TOML frontmatter (but not for .json).

Update 2021-05-21: This plan is still relevant: I would like to loosen some restrictions and improve the user interface.

You can call coinsR via an RStudio Addin for every page individually. But you can also produce COinS automatically for all files under a specific directory.

Where to find `coinsR` and how to install it?

You can download the package from Github with

remotes::install_github('petzi53/coinsR', build_vignettes = TRUE)

I am trying to prepare coinsR as an R package distributed via the CRAN repository. But as I am still not very experienced in R programming, I am not sure if I will succeed.

You will find a detailed description in the help file and the vignette description of how to invoke the two functions coins_this() and coins_all().

Wayback Machine Tutorial

Sun, 21 Jul 2019 00:00:00 +0000

How to use

Wayback Machine (Slides)

Use the controls on the right bottom of the screen.
Watch out: sometimes there is not only left & right, but also top & down.
Press ALT key (CTRL in Linux) and click on any element to zoom towards it. Click again to zoom back out.
For an overview about the slide structure press ESC.
To end the presentation go back with the browser.

1. Wayback Machine

Start Page

2. Choose

Save Page Now

3. Saving Page (without Outlinks)

4. Saving page (with Outlinks)

5. Captured page

6. Retrieving archived page

Search for archived page

8. Calender view of archived page(s)

9. Collections of archived page(s)

10. Select captures to compare

11. Compare two captures

12. Capture(s) in Site Map view

13. Install browser extension

14. Web page not available

15. Retrieved web page

16. Access personal web archive

17. Personal web archive

Close presentation

Press back button of your browser.

(not back button of the slide!).

Blog writing barriers to overcome

Fri, 31 May 2019 00:00:00 +0000

Another year has elapsed since I wrote my last blog entry. At first, I thought the problem is only my English. But in the meanwhile, I see several other reasons why I do not blog for the new static website(s).

I will elaborate later on the following thoughts. At the moment, I want to list the possible reasons for my blogging abstinence:

I am still not comfortable with the new community I want to address with these blog entries.
The topics I want to cover are still relatively new for me so that I often believe that my reflections and discussions of these subjects are trivial and not worth reporting.
I am doubtful which of my different upcoming ideas belongs to my German weblog “Gedankensplitter” and which is better suited for the English community.
I am still struggling to get the focus right for my English blogging. In the last few months, I get a better feeling on which two topics I would like to concentrate: Open Science and Data Science. (More on these two topics and their relationship will follow in another blog entry.)
From my professional point of view, I still generate most of the experiences and material in German such Interviews, Reviews, Talks, Lectures, etc..
It is much more exciting for me to learn new things in R or about strategies for Open Science than to continue to blog frequently for my German weblog.
There is not enough time to write for both weblogs. I wonder how other people like Andrew Gelman write at least one blog entry every day, sometimes even 2 or three.
Coming closer to my retirement the necessity to foster my professional online presence is not so vital anymore.
The English language is also a barrier. I am not so comfortable and skilled to write in a witty and informal style as I am used to it in German.
And finally there are these enormous complexities with blogdown and Hugo. There are so many software layers to watch out with all their difficulties arising for updates, incompatibilities, and bugs. As I have not used these technological infrastructures on a daily bases, it happened that I either forgotten many details. Instead of writing down my thoughts, I had to waste my time to re-learn the software tools.

As you can see: A considerable bulk of difficulties and barriers to overcome! Some of the points of this list, I will reflect more in detail at a later time.

Xaringan presentations with blogdown

Sat, 21 Jul 2018 00:00:00 +0000

How to integrate Xaringan in blogdown?

I am following in this short post the detailed description by Tim Mastny in his blog entry Embed Slides in Your Blog. Please read his article — especially the second half of it, where he is explaining the installation procedure.

Refer to an external slideshow

knitr::include_url('https://timmastny.rbind.io/slides/first_presentation')

Refer to an internal slideshow

knitr::include_url('/slide/xaringan-demo.html', height = "505px")

Summary

Both examples above are the same as in Tim’s article.

Two observations:

There is no need to load the Xaringan package with library(xaringan). At the moment, I do not understand why this is not necessary.
In the second example, the gray left and right margin have disappeared. The parameter height = "505px" does this. To tweak this, I had to experiment with the optimal pixel value. (Maybe there is a better way to tweak this parameter with the valid value, e.g., taking the value from the CSS.)

The height parameter solves one of the problems mentioned by Tim:

I’m also investigating to see if I can trim the iframe, so I only see the slides and not the gray bars on the side.

How to present slides in full-screen view?

Here I wanted to address his second issue:

I’d like to be able to use a relative reference to the slideshow’s HTML file in the static/ directory, but I think knitr::include_url() requires a live URL. I’ll have to do more research.

My first try: Using Markdown image links

My first try was: ![](/slide/xaringan-demo.html/#5)

It generates a kind of thumbnail. Maybe this is theme dependent. I once tried it out in another theme and got other sizes, e.g., over the whole width of the text column. Presumably, this has to be done in one of the CSS files of the corresponding template.

A kind of a thumbnail was not the result I was looking for, but it could become handy anyway. For instance, as a reference in an article. With the slide number behind the URL, one can reference easy every slide frame directly.

My second try: Using Markdown with absolute links

The second try is a link in standard Markdown to the file. It opens up the full-screen presentation. The code:

The second try is a [link in standard markdown](https://portfolio.peter-baumgartner.net/slide/xaringan-demo#1) to the file.

This is not ideal one always needs an internet connection for the presentation.

My third try: Using Markdown with relative links

The third try is a relative link in Markdown to the file. It opens up the full-screen presentation. The code:

The third try is a [relative link in Markdown](/slide/xaringan-demo.html) to the file.

Summary

This is the solution Tim was looking for. I tried several approaches in vain. Then I remembered that there is a demo blogdown-static website by Yihui Xie. There I found the solution!

Summary and conclusion

This third approach solves the second question mentioned by Tim. And this is an excellent solution: With a simple relative link in Markdown can everyone present (Xaringan) slideshows without an internet connection in full-screen view.

Sure there would have always been the possibility to go via the operating system to the file on the hard disk directly. But this is not very elegant and would complicate to present an integrated presentation via browser with other (multimedia) elements. One reason out of 11 why Xihui Yui hotly favors remark.js is the feature that you can press the back button in the browser, and you will go back to the page from which you visited the slides, instead of reading the slides in the reverse order again.

The next thing on my agenda is to learn how to apply Xaringan for everyday use. I have to read and try out:

the example slides (Xaringan and remark),
the readme file at the remark GitHub site and
the documentation in the remark wiki.

Then I will transfer — as a first real live application — my slideshows written with reveal.js stored at my abandoned site at https://notes.peter-baumgartner.net/slide/ to this new site here.

To inspect the full code of this post follow this link to my GitHub repo.

Using themes with blogdown: Lesson learned

Thu, 19 Jul 2018 00:00:00 +0000

Report from an Odyssean Journey

After a long interruption …

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 blogdown and Hugo.

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.

I had problems with my old theme

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 blogdown and Hugo.

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.

DocDock theme still maintained?

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.😡 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.

Problems finding another suitable theme

From docdock to ghostwriter

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, blogdown, bookdown, 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.

From ghostwriter to Xmin and Academic

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!

Crazy Hair GIF from Crazyhair GIFs

Figure 1: Crazy Hair

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 Git and 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.

Lesson learned from my own experience

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.

How to choose a theme?

Most important: In choosing a theme do not only focus on functionality and pleasing design.

Additionally:

Advice 01: Look if the theme author is currently active. If there are no updates for several months or later, reconsider to choose this theme.

Advice 02: Look at the repo to decide if the author is responsive to reported issues or pull requests.

Advice 03: Look if the author provides releases from time to time. Unexperienced users like me are still not comfortable with Git/Github. Instead of forking and synchronizing repositories, I prefer to install updates via ZIP files.

Advice 04: Look into the documentation to see if the explanations are comprehensive and up-to-date

Advice 05: Investigate the popularity of the theme. This check is not easily done but improves the changes for support through other users. Look not only at the number of stars and forks in the repo because that could be misleading for your purpose and community.

Advice 06: Recherche also if people often write in blogs and forums about the theme and what kind of community is using this theme.

… keep in mind that a more complicated and fancier theme may require you to learn more about all the underlying technologies like the Hugo templating language, HTML, CSS, and JavaScript. (Blogdown Book)

How to start working with a theme?

Most important: Do not begin with adapting the design of the theme.

Instead:

Advice 07: Start a test site with a test repository and test deployment with Netlify.

Advice 08: Copy the content of themes/<your-theme-name>/exampleSite to your project directory. Not the folder itself, but just the content inside (e.g., the folders static, content and the config.toml). Overwrite these files in your project directory — it is only a site for testing.

Advice 09: Read accompanying instructions and go line by line through the 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.

Advice 10: Now start writing text in your test site. I recommend working on real posts you want to publish. Choose predominantly use cases which will be typical for your everyday work. This advice seems strange as you are working still on a test site. It is important to test the theme under real working conditions. Besides, writing real posts are not lost work: You are producing standard text files which you can transfer to other sites or themes if the need arises.

Advice 11: Establish a common workflow and get used to it.

I use the following workflow

I start my daily routine with blogdown::serve_site() using the RStudio addins plugin (CTRL-S on my machine) provided by the blogdown package.

Update 2021-05-19: Due to significant changes starting with blogdown version 1.0 my workflow has changed slightly: It is not necessary anymore to use Build -> More -> Clean All because you can render and publish just one page.

Then I start writing. After saving the file (which automatically updates the local website), I look over the result locally in my browser. (I prefer my Google Chrome browser for detailed inspection and use the RStudio viewer pane only for a general overview or to look up a specific change.)
From time to time — or whenever something seems wrong or not updated — I use Build -> More -> Clean All followed by restarting R. And again blogdown::serve_site() to update locally.
After I have finished my work, I commit and pull the changes to my repo, and after some seconds, when Netlify has deployed the site, I inspect the live result.

Advice 12: After some time with your daily working routine, you get accustomed to all the other features of the theme. Even if there are functions you will not need to use: It is nice to have an overview of what could be possible and what not. This knowledge is also important to understand future updates of the theme.

Advice 13: Not until you feel comfortable with the functionality of the theme and your working habit, you should start to adopt the theme. Here it is important to do all your work on your side of the project; meaning not under the themes directory. Copy those files you are going to change or add under the same structure in your home folder of the RStudio project. 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.

Advice 14: Only when you have finally arrived at a status where you work could be publicly launched, change to the real website. Prepare a fresh installation with your theme, with a new repo and a new deployment by Netlify.

Advice 15: Before you copy your work into a new RStudio project, create a new Git branch 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: config for bigger changes (new version of the theme, changing the configuration or the structure of my site) and blog for my daily (writing) work. If you decide to merge your branch with master you will have an additional security level: Netlify will check if anything went smoothly before your branch is merged with master. If something went wrong, you would abstain from merging your branch.

Problem-solving strategies

Most important: Keep calm and RTFM!

Advice 16: Use Google (or other search engines) to see if other users experienced the same problem. Start your search inquiry with 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.

Advice 17: If you cannot find appropriate problem/solution pairs, I would now — after my Odyssean experience — not yet starting to bother people at discussion fora. Start instead of a new reference (test) site with the XMin theme 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.

Advice 18: If the problem persists in your theme, then there are still two possibilities: Either you did something wrong, or it really is a bug in one of the pieces in the R Markdown machinery. Produce a REProducible EXample ( aka Reprex). Read Reprex do’s and don’ts and report the problem at Stack Overflow or to the RStudio Community[(https://community.rstudio.com/). 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.

Tom Cruise Help GIF from Tomcruise GIFs

Figure 1: Tom Cruise: Help me, help you!

Several updates

This post has enjoyed several updates already!

Back to docdock

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.

Not docdock but Pandoc was the problem

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.

Voila! Back to Academic theme again!

Update 2021-05-19: As you can see from the footer, I am back at the Academic theme again!!! The desired stability of the theme development became an unsupportable disadvantage: I couldn’t use the new features of Hugo any more. With some breaking changes (Content organization via Page Bundles and Goldmark as the new default Hugo markdown library) I became with the docdock theme sidelined.

Why Academic (now Wowchemy web page builder) and not a more simple theme?

After four years of learning and (sometimes bad) experiences, I am feeling more comfortable with the whole production chain and have more confidence to master the complex theme now.
Some changes in blogdown (several checking functions and the possibility to fix the Hugo version) addressed the problem of Hugo as a moving target where users had to follow every revision and update.
Both parts of the community (blogdown and Academic) have grown essentially, so help from other users is much more likely.

Install Blogdown (Part 1)

Tue, 19 Sep 2017 00:00:00 +0000

How to use this presentation?

Use the controls on the right bottom of the screen.
Watch out: sometimes there is not only left & right, but also top & down.
Press ALT key (CTRL in Linux) and click on any element to zoom towards it. Click again to zoom back out.
For an overview about the slide structure press ESC.
To end the presentation go back with the browser.

LATEX Installation: Requirements

At first you have to install

R latest version and
RStudio (Preview > v.1.1).

Then start RStudio: You will see the following window…

1. Create new project

2. Choose new directory

3. Select website using blogdown

4. Choose directory name & location

4a Pick your

preferred theme

4b Select theme & get URL

4c Finish form and install

4d Click “Create Project” button

Click “Create Project” Button and wait some seconds. RStudio will install

Hugo
your selected theme and
blogdown with all dependencies

5 Installation is finished!

Close presentation

Press back button of your browser.

(not back button of the slide!).

How to install Disqus on Hugo?

Sun, 10 Sep 2017 00:00:00 +0000

First of all you have to sign up for Disqus.

Create an account on Disqus.

2. Install Disqus

You are offered two choices after the registration process. Select ‘I want to install Disqus on my site’.

Choose ‘Install Disqus’

3. Fill in the form

Disqus needs some information for adding a forum to your website. I will add just two remarks as the form is mostly self-explaining. Firstly, the website name is a text snippet that will appear in the head of every forum section. It does not have to be related to you website name. Secondly, make a note of your Disqus short name as you are going to use it in step 5 and 6.

Configure Disqus for your site

4. Find discussion template

With the next two steps we are going to fix the problem of a faulty Hugo template. Look for the file ‘single.html’ and open it in the editor to inspect the content. single.html should be under /themes/<your-theme-nam>/layouts/_default. At the end of the file – just before the footer –, you should find the name of the partial template for your discussion forum (= ‘comments-html’ in my case).

Configure Disqus for your site.

5. Replace content

Now go and edit this file, which should be found under /themes/<your-theme-nam>/layouts/partials. You have to replace the whole content with the code snippet provided by Yihui Xie (Thanks a lot by the way!!). To help you, you can compare my changes at GitHub. But don’t forget to change the URL to your Disqus account [as I did :blush:]!

Replace content of your partial template as explained

6. Add shortname

To finish the installation you have finally to add the line disqusShortname = "<your-disqus-shortname>" to your config.toml.

Add your Disqus short name into the config.toml

7. Congratulation!

You have integrated Disqus into your static website. Go to one of your posts and check it. Your end of the page should look similar as in the following graphic.

Disqus forum successfully integrated

Critical remark to Disqus

I should mention that there is growing skepticism in the community about Disqus. People are not only criticizing slowness (load-time behavior) but above all they are concerned about data integrity. It seems that there are lots of irrelevant requests to track the data traffic for whatever purpose nobody knows.

Four years later I have changed to utteranc.es.

Blogdown tutorial (Part 4)

Sat, 09 Sep 2017 00:00:00 +0000

Bring your website online: From blogdown via GitHub to Netlify

Update 2021-05-19: Because of breaking changes in Hugo and new features in blogdown this post is partly outdated. Starting with blogdown version 1.0 you do not build the website always from scratch.

Complement this sequence of the tutorial with reading Up & running with blogdown in 2021 by Allison Hill, co-author of the blogdown book.

We start this last part of the tutorial where we have finished last time.

Ignore public folder

One benefit of using Netlify is that that there is no need to upload your large public folder to get your website. Netlify will compile the source files and build by its own the Hugo site. You should take advantage of this feature by telling RStudio that the public-folder does not need version control, committed and uploaded. Select the public folder under the Git tab on the right upper pane and select from the configuration menu ignore….

Ignore public folder

Confirm .gitignore

This will bring up a window where you can specify which files are to be ignored. Confirm the inclusion of the public folder with clicking ‘Save’.

Confirm the exclusion of the public folder.

This saved file (.gitignore) will be added as modified to the version control.

.gitignore file added

Clean up

Before we are going to rebuild the complete site, I recommend to take some precaution. To rebuild from a clean slate I restart R (Under the RStudio menu ‘Session’ or CMD-Shift-F10 on MacOS.) and clean up all unnecessary files (‘Clean All’ in the ‘Build’ tab under the ‘More’ menu in the upper right pane.)

Rebuild website from a clean status.

Build website

Now you can safely (re-)build the website by clicking into ‘Build Website’. You get a message of all the activities done, the time necessary for the build and were the output was created. [Personal comment: Frankly I do not know if the last two steps are really necessary when Netlify is running its own scripts.]

Rendering website content.

Commit changes

The next step is to select all changed files under the Git tab and to choose “Commit”, write a commit message and to confirm these changes.

Select (stage) content for next commit.

Bring all changes under version control and check if everything went smoothly.

Push changes

Now you can transfer all your committed changes to GitHub. After clicking on the push button a window opens and you can see if the changed files are transferred successfully.

Push the committed files to GitHub.

Inspect repo

If you don’t trust this process, you can direct your browser to your GitHub repository and check if really the last commit “First post” has safely arrived.

Inspect your repo on GitHub to confirm the procedure.

Get Netlify account

The last task we are going to solve is the connection the GitHub repository to the Netlifly service. Go to https://www.netlify.com/ and create a free new account (“Get started for free”).

Inspect your repo on GitHub to confirm the procedure.

Let Netlify access your repo

After the registration procedure you get a page where you can choose ‘New Site from Git’.

New Site from Git

There are essential three step to create the new website: (A) Choose GitHub as your Git repository. This will bring up a window where you have to confirm that you will allow Netlify access to your GitHub account.

Autorize Netlify

(B) Then you have to specify to which repository Netlify should connect.

Choose your website repository.

Deploy settings

In the third and last step (C in my former notation) on Netlify to create your website you have to specify the details (parameters) to let Netlify know which type of website it has to build. In the example in the screenshot I said that Netlify should watch my master branch, build a Hugo website from the public repository with the newest version of Hugo at the time of writing this tutorial (version 0.26).

Specify the deploy settings.

Deploy website

After clicking “Deploy website” you can lean back and watch Netlify busy working on building the website. This may take for this initial step some time but later on Netlify will finish work almost immediately as it only builds the new/changed files incrementally. When the rolling down of the messages stops you should see as last line: “Site is live”!

Wait — and watch Netlify working until it is finished.

Preview deploy

Scroll back to the beginning of the log messages. You will see that Netlify has giving you a random URL but you can change this later on to your liking. Click “Preview deploy” to go to the URL of your new website.

Inspect your random URL.

Website is online!

Congratulations! Your website is now online.

Your website is online.

Final comments

This was a very quick tour where I have covered just the things I believed to be essential. If you are (like me) new to static website generators then the different steps together seem overwhelmingly complex. But with patience and some trial and errors you should succeed — as I have. There are many other (better) tutorials and How-Tos around. You should definitely read carefully the book blogdown: Creating websites with R Markdown and the reports of different experiences from the new rbind community.

Blogdown tutorial (Part 3)

Fri, 08 Sep 2017 00:00:00 +0000

Live preview of your website

Update 2021-05-19: Because of breaking changes in Hugo and new features in blogdown this post is partly outdated.

Complement this sequence of the tutorial with reading Up & running with blogdown in 2021 by Allison Hill, co-author of the blogdown book. With some knowledge the explanation of the changes of blogdown version 1.0 could also be useful.

In this third part of the blogdown tutorial I will explain the necessary steps to get a live preview of your website. The main advantage to bring up your website locally is that you can view and test your website during working on your post without the need of an internet connection. You have not even to reload the page as this is done automatically through a technology called LiveReload.

Warning after installation

After we have finishing the installation we have gotten a red warning. It is a reminder not to transfer files which are not used displaying the website. At that time we didn’t bother about it. I have replicated the picture of step number 8 of the first part of this tutorial as a starting point for this third part of the tutorial.

RStudio’s four pane view immediately after installation.

Ignore some file types

After the installation config.toml is opened automatically by RStudio. We add the recommended line ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"] in an upper place. On this occasion we also change the base URL (first line) to /. After saving theses changes the version control (Git tab right upper pane) will display config.toml with a blue M (modified).

Some changes in the config.toml

Demonize server

Before we start posting our website locally we should arrange that the local server runs as a background process (= aka to demonize the server). You can run the command options(servr.daemon = TRUE) on the console (lower left pane), but – as I am using this process all the time – I prefer to write this line into my start up file. On this occasion I also add some other convenient commands to facilitate the generation of new posts. See the blogdown page on global options for more details.

Set Options in Rprofile.

Start local server

We can now start the local servers: Choose from the “Addins” menu the “Serve Site” option. This will run the command blogdown::serve_site() to build the site to get a live preview of the website locally.

Choose ‘Serve Site’ to get a live preview of the website locally.

Building the website

Blogdown is building the site and will give you the local server address. It is normally http://127.0.0.1:4321/. While the server is demonized you can still use the console, otherwise a small red stop sign will appear in the right corner of left lower pane and no command can be run in the console window. The best way to stop the server is to restart R (shortcut = CMD + SHIFT + F10).

Set Options in Rprofile.

First preview locally

We can now inspect our website in a browser with the web address http://127.0.0.1:4321/. Whenever we type something in one of our files and save the changes blogdown will rebuild the site and we can immediately see the changes in the browser via the local address.

First view of live preview locally.

Adapt personal information

Until now all the information this tutorial has provided was the same whatever theme you are going to choose from the Hugo theme wsebsite. But from here now comes your specified theme into play we will look into some necessary adaptions before we going to publish our new website. You can now adapt the personal information in your config.toml file. Read the documentation which comes included as posts of the sample site http://127.0.0.1/#post or go directly to the demo site. I have for instance changed the title of the website from ‘Academic’ to ‘Blogdown Test’.

Changed title from ‘Academic’ to ‘Blogdown Test’

Create first post

To write posts choose ‘New Post’ from the Addins menu.

Create a new post.

Add metadata

This will open up a window to fill in metadata. This form is already populated with the variable from our .Rprofile, so that you only have to add the post title. File name and slug will be generated automatically from the post title. Categories and tags can be filled now — or later written in the file header or via the Addins menu ‘Update Metadata’ added.

Fill in the prepopulated post form.

Start editing text

The ‘New Post’ form creates a new file for the post. The first few lines are filled with metadata of the post. You start with the post text under the second three dashes of the post header. To format your text nicely learn the Markdown

First post entry.

Inspect post locally

After saving your text, you can finally inspect your first post locally! Posts in the hugo-academic theme can be found in post section of the website.

Your first post!

It may be the case that the generation of you first post produces a warning. After Hugo version 0.24 a prototype for new generated files is necessary. In that case create a file with the command file.edit("archetype/default.md") and add the example text written in the warning message.

A warning informs you to create a file with a specified text.

Finally: Visit the final part of this tutorial to bring you website online.

Blogdown tutorial (Part 1)

Mon, 04 Sep 2017 00:00:00 +0000

Update 2021-05-19: Even if some screenshots might have changed slightly, this part of the tutorial is – with one exception (header 4) – still up to date. But there are now many other resources with the same content available.

Especially I would like to recommend Up & running with blogdown in 2021 by Allison Hill, co-author of the blogdown book.

In this tutorial I will show how to install the R package blogdown with the help of the new version of RStudio and how to link your local blogdown-directory to a remote repository on GitHub. But before we actually start with the installation procedure let us define the different ingredients (tools) we are going to use:

Tools we are going to use

Blogdown is an R package for creating static websites with R Markdown.
R is an integrated suite of open source software facilities for statistical computing and includes tools for data manipulation, calculation and graphical display.
RStudio is an integrated development environment (IDE) which sits on top of R and facilitates the use of R tremendously.
R Markdown is a file format for making dynamic documents with R. It is based on Markdown (a lightweight markup language with plain text formatting syntax), but it also can contain chunks of embedded R code.
Hugo is a popular open-source static website generator.
hugo-academic is a theme designed for Hugo to create an academic or personal website. Besides special academic features like sections for publications, projects, teaching it also includes a blog section and supports multilingual usage.
GitHub is an Internet hosting service for distributed version control repositories. Is is mainly used for source code management, but it works also with plain text markup languages. GitHub offers all the functionality of Git as well adding its own features.
Git is a distributed version control system for tracking changes in computer files and coordinating work on those files among multiple people.

All these tools are open source and free available.

Preliminary preparations: Installing R and RStudio

There are many tutorials to install R and RStudio. See for instance the video Installing R and RStudio. But at the moment the new version of RStudio which facilitates the installation procedure of blogdown is still not released as standard version. But you can use all these new features by downloading the preview release. As these features will be soon the standard version of RStudio I will explain the installation procedure using this upcoming version.¹

Create a blogdown website

Create a new project

After installing RStudio version greater than v.1.1.28 open the project menu and choose “New Project”.

Create a new project

Create a new directory

A new window opens up: We are going to create a new local directory for our static blogdown website. Choose “New directory”.

Create a new directory

Create a website using blogdown

The selection in the following window is self-explaining: “Website using blogdown”. Here it is the last line in the window. But in the future there may added other project types, so that you have to scroll down to see the blogdown-choice.

Create a website using blogdown

Create a website using Hugo and blogdown

Update 2021-05-19: The Academic theme is now modularized into different specialized templates and integrated into the development of the web builder software wowchemy. To get the complete Academic theme, you have now to write into the Hugo theme field “wowchemy/starter-academic” (instead of “gcushen/hugo-academic”).

Lastly we arrive at the final window we have to answer. Here you can choose the name and location of your local directory which will eventually collect all files of your static website. I recommend to leave all check boxes ticked, as this default value will give you the most support to generate the new website. The program for the static website generator Hugo will be installed automatically as well as sample blog posts will be added. Especially important is the possibility to look into the example site of the theme, because this will provide you with clues about the functionality of the theme.

Create a website using Hugo and blogdown

Choose theme

I have chosen the hugo-academic theme. You can pick your own preferred webdesign via the Hugo Themes page.

Huge variety of Hugo themes to choose from.

Choose Academic (now Wowchemy)

In the “Hugo theme” field you have to insert the URL of the GitHub repository of the theme you would like to use. You will see the address when you click at the thumbnail of the theme and hover your cursor over the “Download”-button.

hugo-academic is as special theme for personal websites in academia.

GitHub repor of Academic theme

Clicking on the download button will bring up the developer’s repository. This is useful even for beginner as you can have a look of the ongoing discussion under the “issue” tab or to ask your own questions. Experienced users can fork the repository in order to adapt the functionality of the theme and/or to suggest code changes to the developer via the push mechanism.

GitHub code repository of the hugo-academic theme.

Create project

When you finally click the “Create Project” button you have to wait few seconds until the selected theme is downloaded and Hugo installed. After the installation is finished RStudio opens up a four pane view. We will go more into the details of these different windows in the third part of this tutorial.

RStudio’s four pane view immediately after installation.

Summary

We have successfully installed the hugo-academic theme in a version controlled local directory. Essentially we could now start to personalize the website and/or write articles resp. posts. But we will continue the installation process with creating a remote GitHub repository which has to be linked to the just created local repository. The remote repository not only operates as backup and as distributed version control (allowing collaboration) but also enables – beside a manual transfer via ftp – additional ways of publishing your website. We will cover these possibilities in the following parts of this tutorial.

Go and visit the second part Creating a GitHub Repository of this tutorial.

To use features supporting blogdown websites the RStudio version has to be higher than v1.1.28: As today (2017-09-04) the actual preview version is v1.1.353. ↩︎

blogdown | Thought splinters

Announcing the R package coinsR

Use cases of coinsR and its limitations

Where to find coinsR and how to install it?

Wayback Machine Tutorial

Wayback Machine (Slides)

Start Page

Save Page Now

3. Saving Page (without Outlinks)

4. Saving page (with Outlinks)

5. Captured page

6. Retrieving archived page

Search for archived page

8. Calender view of archived page(s)

9. Collections of archived page(s)

10. Select captures to compare

11. Compare two captures

12. Capture(s) in Site Map view

13. Install browser extension

14. Web page not available

15. Retrieved web page

16. Access personal web archive

17. Personal web archive

Close presentation

Blog writing barriers to overcome

Xaringan presentations with blogdown

How to integrate Xaringan in blogdown?

Refer to an external slideshow

Refer to an internal slideshow

Summary

How to present slides in full-screen view?

My first try: Using Markdown image links

My second try: Using Markdown with absolute links

My third try: Using Markdown with relative links

Summary

Summary and conclusion

Using themes with blogdown: Lesson learned

Report from an Odyssean Journey

After a long interruption …

I had problems with my old theme

DocDock theme still maintained?

Problems finding another suitable theme

From docdock to ghostwriter

From ghostwriter to Xmin and Academic

Lesson learned from my own experience

How to choose a theme?

How to start working with a theme?

Problem-solving strategies

Several updates

Back to docdock

Not docdock but Pandoc was the problem

Voila! Back to Academic theme again!

Install Blogdown (Part 1)

How to use this presentation?

LATEX Installation: Requirements

1. Create new project

2. Choose new directory

3. Select website using blogdown

4. Choose directory name & location

preferred theme

4b Select theme & get URL

4c Finish form and install

4d Click “Create Project” button

5 Installation is finished!

Close presentation

How to install Disqus on Hugo?

1. Sign up

2. Install Disqus

3. Fill in the form

4. Find discussion template

5. Replace content

6. Add shortname

7. Congratulation!

Critical remark to Disqus

Blogdown tutorial (Part 4)

Bring your website online: From blogdown via GitHub to Netlify

Ignore public folder

Confirm .gitignore

Clean up

Build website

Use cases of `coinsR` and its limitations

Where to find `coinsR` and how to install it?