how-to | Thought splinters

How to Register with a Hosting Service to Buy Space for your Server

Wed, 16 Dec 2020 00:00:00 +0000

With this article, I begin a new series of step-by-step instructions focused on installing and working with open source tools on your own server space. I’ve learned some of these procedures participating as an audience member in a sequence of German web talks by Guido Brombrach, organized by OERcamp.

Step 1: Go to the URL of your hosting service

Step 1: Go to the URL of Uberspace and scroll to the middle of the start page.

Go to the start page of your hosting service. This tutorial uses Uberspace.
Scroll to the middle of the page and click on the link SIGN ME UP!

Step 2: Provide your username

Step 2: Choose username and fill it in the form of the Uberspace registration page.

Think again about your chosen username. You can’t change it anymore. It will be the first part of the URL, followed by the server address.
Fill in your username and tick the check box to conform to the technical and social house rules.
Check if your username is still available.

Step 3: Provide your email address (to reset your password)

Step 3: After creating your account Uberspace asks for additional information. First part: eMail.

Uberspace comes back after some moment with this new form. Meanwhile, the program has stored your username in the Uberspace database and already logged you in. What you here see is the first part of the form.

Also, you have already gotten an email address.
But for security reasons, I recommend providing another email address. Whenever you forgot your password, you can apply for a new password sent to your email account. Otherwise, you are locked out from your webspace.

Step 4: Set your password and choose your price model

Step 4: Uberspace asking for additional information. Second part: Password and price.

After scrolling down, you will see this second part of the form.

Provide a password to enter later the admin pages of your webspace.
This password has nothing to do with the password you will use to access the server via SSH or SFTP. (I will explain Secure Shell resp. Secure File Transfer Protocol in another tutorial.)
Uberspace has an exciting price model. The first month is free in any case. After that, you have three paying options. All of them have the same services but differ in your financial contribution to the hosting service. You can always later change your decision.
Then click the “Make it so” button.
Be patient. It can take several minutes till your server space is ready for you to access.

Step 5: Success of web registration!

Step 5: Success page of the web registration process.

When you see this page, your registration process was successful. Congrats!
There are many helpful resources in the Uberspace manual and wiki. But if you are still stuck, don’t be shy and ask the people at Uberspace directly via email.

Step 6: Password for SSH access

Step 6: Uberspace start page after logged in.

The successful registration for web access only means that you can now enter your uberspace web admin page. To get the page you see on the screenshot, you have to login into Uberspace and open the tab “Logins.”
On the left side, you see your login for the Uberspace admin page (your web access). If you want, you can provide another password that will override your old one. As you can see, under 2a, I am already logged in.
What we need to do now is to provide a password for access to your server space. When you fill in this (different) password, you will get a red bar on top of the screen saying you have set an SSH password. With this password, you can now access your server with an FTP-client or via your terminal.

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!).

How to produce bibliographic metadata for your web page?

Wed, 19 Jun 2019 00:00:00 +0000

In an accompanying post I explain why to provide bibliographic metadata for your web entries could be beneficial.

Requirements

In this tutorial, I will show how to produce and embed bibliographic metadata into your web page. To follow this guide, I assume that:

you have installed the standalone version of Zotero.
you have installed the appropriate Zotero connector (plugin) for your browser.
you have a working knowledge how to use Zotero (There are many (video) instructions on the internet, see for instance the ‘official’ Zotero Quick Start Guide or the introduction by the Idaho State University).

Bibliographic metadata in 14 small steps

Start Zotero and your browser. Go to the page where you want to embed the metadata. You see the Zotero icon for web pages in the place where your web browsers shows the symbols for its installed extensions.
Figure 01: Target web page for embedding bibliographic metadata.
Click on the icon and download the rudimentary bibliographic information for the web page.
Figure 02: Download the rudimentary bibliographic information with Zotero.
Change to Zotero and inspect the new downloaded entry. You will notice that many details are still missing.
Figure 03: Zotero bilbiograpy with the new downloaed biobliographic entry.
Change the item type to an appropriate value: in my case “Blog Post”. You will see that the Zotero icon changes to reflect the new value. Different item types have different fields.
Figure 04: The standard web page entry misses many information in its bilbiographic record.
Add the relevant information as shown on the screenshot. Depending on the chosen item type, there are different fields to fill in. There is a list of item types, fields, and their meanings on a Zotero help page.
Figure 05: Adding information into the bibliographic record.
When you bibliographic entry is complete you can start the conversion and export procedure. Open the context menu (on MacOS is it a right mouse click).
Figure 06: Opening the context menu of the bibliography entry to start the export.
From the appearing drop down menu choose the “COinS” translator.
Figure 07: Choose COinS as export translator.
Save the converted data in a file on your hard disk. The place is not essential as we only need the text inside the file. After we have copied the COinS data into our web site, we will delete our intermediary file.
Figure 08: Prepare to save the converted information.
File name and file extension are also irrelevant. Just check if your export format is “COinS”.
Figure 09: MacOS Save File dialog window with export mode “COinS”.
Open the exported file with your text editor and select the COinS HTML code. You will see the text of your bibliography record URL encoded in the COinS standard format. URL Encoding replaces unsafe ASCII characters with a “%” followed by two hexadecimal digits. But don’t worry, it is not necessary to understand the code snippet.
Figure 10: Exported COinS code as it is seen after opening the file with a text editor.
Copy and paste the code in the source code of your web page. Again, the place does not matter. On a life web page visitor do not see these code but only the result – the particular Zotero icon.
Figure 11: Embed the exported COinS code into the HTML source code of the web page.
Now inspect you life web page. You will see that the Zotero icon has changed from “Web Page” to “Block Post”. Congratulation you made it!
Figure 12: Inspection the modified web page.
We need to check if everything works as intended. Save the new generated bibliographic metadata into your zotero database.
Figure 13: Download of the new generated metadata to test if everything works as intended.
Check if all the bibliographic metadata are imported correctly.
Figure 14: Inspection of the modified bibliographic record in Zotero

Wrapping up and additional information

You have learned to create, embed, and download bibliographic metadata from those web pages where you have access to the source code. There are further options in addition to what I have demonstrated in the tutorial:

You are not limited to the item type “Block Post”: You can choose from all the 34 different types of bibliographic entries. But watch out: Every item type has its (slightly) different input form and Zotero icon. You need to know what kind of information each bibliographic record type needs.
You are not limited to one COinS entry: You can generate and embed as many bibliographic entries you want. If your web page has a list of references, you can offer visitors of your web page to download the bibliographic information for the full bibliography. The Zotero icon changes to a folder if there is more than one bibliographic entry to download.
You do not need to generate a COinS entry by yourself if the bibliographic entry has a DOI: I do not know how this works, but Zotero recognizes DOI entries. See as an example, my blog post about data science education.

RStudio Snippets for Markdown

Wed, 12 Jun 2019 00:00:00 +0000

Tutorial for RStudio code snippets

Code snippets are text macros which you can insert into your programs. They are used for repetitive tasks and can boost your productivity tremendously. Here I am not going to explain how to use it. There are already several good tutorials around:

The official RStudio tutorial on code snippets
A Blog entry by Jake Daniels: How RStudio Snippets Improve My Productivity
A Blog entry by Jozef Hajnala: 4 ways to be more efficient using RStudio’s Code Snippets, with 11 ready to use examples
A Video by Sharon Machlis: R tip: Save time with RStudio code snippets (part of her video channel Do more with R)

Eight useful reminders

In this post, I want to summarize some important details, which I learned laboriously after time-consuming trials:

The Markdown section in the snippet editor works only with .Rmd and .Rmarkdown files. – So if you are going to write just text (e.g., a blog entry) and you want use RStudio snippets to insert shortcodes than you have to write into .Rmd / .Rmarkdown files.
The snippets in the R section of the snippet editor are for code chunks whereas the snippets in the Markdown section work only in markdown text of .Rmd / .Rmarkdown files.
To insert snippets in the Markdown part of .Rmd / .Rmarkdown files, you have to use SHIFT-TAB (and not just TAB as for R snippets in the code chunks).
To write your snippets, you have to use the TAB key for indenting. 4 Spaces do not work!
It is legitimate to write huge snippets for large code junks. For instance, you can write complex ggplot2 snippets as a kind of a template you are going to use frequently.
For large code chunks, it may be preferable to write the snippets with the RStudio code pane. You can load the snippet files under ~/.R/r.snippets respectively ~.R/markdown.snippets into RStudio.
You can share you snippets sending these files to your colleagues and collaborators.
Do not use names, which are difficult to type to call your snippets. For instance, to insert the markdown syntax for an image do not name it “![” but “ii” for example.

Comments in Markdown

Sun, 02 Jun 2019 00:00:00 +0000

In reworking this docdock-theme, I wanted to document the reasons for my changes and how I have done it. But I didn’t know how to write comments in markdown.

Yes, one could use a normal HTML-comment, but you still can see the comment in the source code.

<!-- 
This is a comment inside a code chunk, so that you can see it on the page.

Multiline comments are allowed as well 
-->

Look at the source code, and you will see the text example below this line.

Searching in Stack Overflow I came finally up with the following solution:

[comment]: # (This text is a comment! But written in a code junk, so that you can see how it is done.)

[comment]: # (This text is a comment! Multiline comments are allowed as far as long there is no line break. This text is a comment! Multiline comments are allowed as long as there is no line break. This text is a comment!  Multiline comments are allowed as long as there is no line break. )

You can’t see the result of this last code example not even in the source code. The comment is hidden by definition :wink: But you can inspect the original text file on my GitHub repository. Just click on the Edit page link in the top right corner of this page.

There are also other possibilities, but the above solution with comment: written in square brackets and the # - sign followed by the comment written inside round brackets is the most portable version.

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.

LaTeX installieren (Deutsch)

Sun, 07 Jan 2018 00:00:00 +0000

LaTeX installieren

Bedienung dieser Diashow

Steuerungselemente: Pfeile rechts unten
Achtung: Manchmal gibt es außer vor und zurück auch hinauf und hinunter
Folienstruktur-Überblick: ESC-Taste
Zoomen: ALT + (STRG für LINUX) KLICK in das Objekt. Noch ein Klick: Herauszoomen.
Beenden: Mit dem Browser zurück gehen

Voraussetzungen

Bevor wir komfortabel mit R arbeiten können, müssen wir einige Programme installieren

Die aktuelle Version von R
Die aktuelle Version der Entwicklungsumgebung RStudio
Die aktuelle Version von LaTeX

Alle Programme sind Open Source: Sowohl Quellcode als auch Programme sind frei und kostenlos erhältlich.

LaTeX-Installation für Mac (1)

Windows: Pfeil rechts unten nach rechts!

Mac: Weiter mit Pfeil nach unten!

LaTeX-Installation für Mac (2)

LaTeX-Installation für Mac (3)

Präsentation beenden

Sie beenden nun diese Präsentation mit (Browser Pfeil rückwärts)
ACHTUNG: Browser rückwärts – und nicht Folien Pfeil links!

LaTeX-Installation für Windows (1)

LaTeX-Installation für Windows (2)

LaTeX-Installation für Windows (3)

Präsentation beenden

Sie beenden nun diese Präsentation mit (Browser Pfeil rückwärts)
ACHTUNG: Browser rückwärts – und nicht Folien Pfeil links!

RStudio installieren (Deutsch)

Wed, 03 Jan 2018 00:00:00 +0000

Installation von RStudio

Bedienung dieser Diashow

Steuerungselemente: Pfeile rechts unten
Achtung: Manchmal gibt es außer vor und zurück auch hinauf und hinunter
Folienstruktur-Überblick: ESC-Taste
Zoomen: ALT + (STRG für LINUX) KLICK in das Objekt. Noch ein Klick: Herauszoomen.
Beenden: Mit dem Browser zurück gehen

Voraussetzungen

Bevor wir komfortabel mit R arbeiten können, müssen wir einige Programme installieren

Die aktuelle Version von R
Die aktuelle Version der Entwicklungsumgebung RStudio
Die aktuelle Version von LaTeX

Alle Programme sind Open Source: Sowohl Quellcode als auch Programme sind frei und kostenlos erhältlich.

Installation von RStudio

R noch nicht installiert? Beginnen Sie mit diesem Link
Ansonsten rufen Sie die RStudio-Downloadseite auf

Wählen Sie Mac oder Windows-Downlaod

Speichern Sie Ihre Programm-Version

Klicken Sie auf den Download-Link
Speichern Sie die Installationsdatei
Entpacken Sie RStudio
Rufen Sie RStudio dann auf

Es erscheint nun die Entwicklungsumgebung
Klicken Sie in die obere Leiste, damit Sie alle 4 Fensterbereiche sehen

Erkunden Sie Fenster und Reiter von RStudio

Hilfreich ist auch diesen Video
Mehr zu Entwicklungsumgebung dann, wenn wir mit R zu arbeiten beginnen

Zusammenfassung

Es gibt auch YouTube-Videos zum Ansehen
Die Schritte für Mac und Windows sind ähnlich:
z.B. für Mac hier und hier
und für Windows hier und hier
Ein Link, der nochmals alle Schritte zusammenfasst
Sie sollten jetzt R und RStudio installiert haben

Präsentation beenden

Sie beenden nun diese Präsentation mit (Browser Pfeil rückwärts)
ACHTUNG: Browser rückwärts – und nicht Folien Pfeil links!

R installieren (Deutsch)

Tue, 02 Jan 2018 00:00:00 +0000

R installieren

Bedienung dieser Präsentation

Steuerungselemente: Pfeile rechts unten
Achtung: Manchmal gibt es außer vor und zurück auch hinauf und hinunter
Folienstruktur-Überblick: ESC-Taste
Beenden: Mit dem Browser zurück gehen

Voraussetzungen

Bevor wir komfortabel mit R arbeiten können, müssen wir einige Programme installieren

Die aktuelle Version von R
Die aktuelle Version der Entwicklungsumgebung RStudio
Die aktuelle Version von LaTeX

Alle Programme sind Open Source: Sowohl Quellcode als auch Programme sind frei und kostenlos erhältlich.

Neuinstallation von R

Wir beginnen mit der Neu-Installation von R
Und zwar für Mac OS und für Windows

ACHTUNG: Wenn Sie bereits (eine ältere Version von) R installiert haben, dann folgen Sie statt dessen for Windows dieser Anleitung and for Mac dieser Anleitung.

Die R-Startseite

CRAN aufrufen

Wählen Sie Ihre R-Version aus

Mac: Klicken Sie auf Download-Seite für Mac OS X
Windows: gehen Sie zur nächsten Folie (Pfeil rechts)
Weiter für Mac: Pfeil nach unten wählen

1a R-Installation für MacOS X

Klicken Sie auf die neueste R-Version
(hier R-3.4.3.pkg: Stand Januar 2018)

1b Datei .pkg speichern

Es öffnet sich nun ein Fenster
Wählen Sie einen Speicherort
Sichern Sie die Datei

1c R installieren

Öffnen Sie im Betriebssystem die gespeicherte Datei
Es öffnet sich das Installationsprogramm
Befolgen Sie die Anweisungen (“Fortfahren”)

Rufen Sie R auf

Rufen Sie die R.app auf
Geben Sie 2 +2 als Test ein:

Vergleichen Sie Ihr Ergebnis

Beenden Sie Ihre Eingabe mit return
Erscheint [1] 4?
Dann haben Sie R erfolgreich installiert!

Präsentation beenden

Es kann sein, dass der Text Ihrer R-Version leicht unterschiedlich ist. So kann er z.B. komplett in Deutsch geschrieben sein.

Sie beenden nun diese Präsentation mit (Browser Pfeil rückwärts)
ACHTUNG: Browser rückwärts – und nicht Folien Pfeil links!

2. Installiere R für Windows

Gehen Sie auf die Download-Seite für Windows

Download der aktuellen R-Version

R Download für Windows

Windows-Bilschirmfotos gesucht

Ich habe leider keine weiteren Screenshots.

Installieren Sie gerade R für Windows?

Dann schicken Sie mir bitte Screenshots.

Ich baue sie dann in diese Präsentation ein!

Präsentation beenden

Sie beenden nun diese Präsentation mit (Browser Pfeil rückwärts)
ACHTUNG: Browser rückwärts – und nicht Folien Pfeil links!

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 2)

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

Creating a Github repository

Update 2021-05-19: Even if some screenshots might have changed slightly, this part of the tutorial is 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. There is a small part at the end to the integration into GitHub.

R User now can use the helpful package usethis with information how to get Git(Hub) Credentials and with Happy Git and GitHub for the useR there is also a gentle introduction to Git & GitHub.

In part 1 we have installed the hugo-academic theme on top of R, RStudio and blogdown. We will continue the installation process with creating a remote GitHub repository.

Create a GitHub repo

In case you do not have a GitHub account, sign up for it. When you have finished the registration process click the button “Start a project”. If you already have an account click at “New repository”.

Creating a new GitHub repository.

Name your GitHub repo

Both actions (“Start a project” and “New repository”) opens up a window where you can name your new repository. Leave all the other options empty resp. as they are and click the green button “Create repository”.

Name your new GitHub repository.

Quick Setup

The last click brings you to a “Quick setup” page with several options. As there already exist a repository with our hugo-academic files, we copy the two lines in the third option: “push an existing repository from the command line”.

Quick setup: push an exiting repository from the command line.

Shell commands: git init

But before we can paste these two lines into the terminal in order to link our local with the remote GitHub repository we need to download Git and install it. The best description I know of the installation procedure and its integration with RStudio is by Hadley Wickham in chapter 13 of his book about R Packages. There is a online version available. Read the two sections Initial set up and Create a local Git repository. For the mentioned shell commands you can use the Terminal tab of RStudio in the left lower pane.

Use for the shell command the new terminal tab of RStudio.

Git tab in RStudio

5After the shell command git init the local repository is under version control. After you have restarted RStudio you will now see new tabs in the RStudio panes. Click in the Git tab in the upper right pane. This reveals a bunch of folder and some files. The yellow boxes with the question marks under the status column indicate that these file are not yet under version control.

Folders and files which are not under version control.

Add files under version control

To bring these folders and files under version control you have to select all of them and click in one of the check boxes under the column “Staged”. You will see now a lot more files as all the files under the still untracked folders are explicitly shown. The A indicates that these files are new (are just added) to the repository.

New (Added) files to be set under version control.

Initial commit

A click in the Commit tab opens up a new window where you must write a message. This is necessary so that all collaborators (including the future-you!) remembers what was the change about. This first (e.g.initial) commit will bring all the files under version control.

The initial commit brings many files under version control.

Success message

After sending your message by clicking the Commit button you will see a list of all the committed files which are now in the local repository under version control. You can close this window and we can finally add our two lines copied from the GitHub page.

Files are successfully committed.

Connect local with remote repo

Insert the two copied lines from the GitHub repository into the Terminal tab (red arrow). The first line will establish the connection between the local and the remote repository. The second line will push all the committed local files to the GitHub repository.Depending of you internet connection and how many data has to be transferred this can take a couple of seconds (blue arrow).

Connecting local Git with remote GitHub repository and pushing the initial commit.

After this second step we are going to to get a live preview of your website.

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. ↩︎