Why you should start your own blog?

Before we dive into the technical details, a question should be asked first: why you need your own blog?

We are living in a world where everyone wants to seize your attention in a second. People are absorbed in short videos or timeline feeds with provoking headlines, and if a passage is more than 280 characters, a tl;dr is expected.

So in 2019, a blog, especially a blog with self domain, looks like a kind of quixotic behavior. But as an indigenous resident of digital world and a disciple of open web, I do believe you should have your own blog if you are a creator. Some benefits are obvious:

• Take back your own data. Don’t let tech giants tell you what to read or what to say. Keep faith in the open web.
• Writing is a fantastic “output” form. It helps you to deepen your understanding and review your knowledge in a more systemic way.
• Like a pensieve, your blog provides a place to deposit your thoughts. It will pay you back in the future.
• You may build a personal brand from this.

And why blogdown/RMarkdown?

I’ve tried many writing tools or blog services, they all have pros and cons. The last one is jekyll with GitHub pages. The markdown format and git workflow is very convenient and flexible. However, since I know nothing about Ruby, the Gem dependency often drove me crazy. The render speed is not a major concern until I experienced Hugo.

Therefore, the blogdown framework provides an excellent choice, combining the power of RMarkdown and Hugo:

• Clean and more powerful markdown syntax (thanks to Pandoc).
• Literate programming with knitr. You can show and run your reproducible R/Python/C++/Julia code inside the document, and render the result, diagrams, interactive widgets along with the article, even in an inline expressions form.
• \(\LaTeX\) and code highlights support.
• Plain text gives your freedom.² You don’t have to bear the git mess of jupyter notebook anymore.
• Powerful static site generator, easy to configure and customize.

Even if blogdown is written in R, you can use it without learning R programming. Xie Yihui, the author of blogdown, published a very nice online book. You can read it and learn blogdown within a couple of hours.

Pick a hugo theme

I have to confess that I spent too much time on the choice of suitable blog themes, since I have several sites to migrate. I highly recommend you to follow Yihui’s advice on themes. And don’t panic, you can always change it later if you’re discontent. Hugo’s project structure makes this very easy.

After you pick a beloved style, you can start your blog with just one line code:

# change the `theme` argument to any other one you like
blogdown::new_site(theme = "kakawait/hugo-tranquilpeak-theme")

Customize your blog

It’s not a joke:

Nearly all of my front-end knowledge come from my impulse to modify a static page blog theme. No, no js yet, css has already made me crazy.

Almost every time you choose a theme, there are some aesthetic details you don’t like. My (rational) suggestion is always put writing prior to the appearance. However, if you’re not afraid to html/css, you can customize them as you like.

My situation was a little tricky: I was planning to have two post sections to write both English and Chinese articles. So I copied layouts/section/post.html to zh.html and en.html. I also created a new layouts/partials/li_list.html since I didn’t like the default post list style. Academic theme provides a nice tag cloud widget, however, I still want some kind of standalone pages for tags and categories, like the taxonomy style of my old jekyll theme codinfox-lanyon. So I handcrafted a layouts/_default/terms.html as well.

There are some other small modification like rss links, fonts, color, icons, etc. I list some tips I’ve learned from my recent struggle with hugo-academic theme below. Hope they will save you one minute of time.

• Upgrade both blogdown and hugo theme to the latest version. I once thought I catch a new bug of blogdown, but when I was going to create a minimal reproducible example, I found out it has already been fixed in blogdown’s newest version.
• Do read this chapter on Hugo templates, it helps you understand some fundamental structures.
• Keep tracking of upstream theme via git submodule, and do all your customization in separate directories under your repo’s root path. For example, layouts for html template, static or assets for css and images.
• If you’re puzzled with some expressions, or want more functionality, check out Hugo’s documents.
• Modern browsers are shipped with developer tools. Make use of them to catch a glimpse on why some customization didn’t work.

Migrate from jekyll

Jekyll and many other static site generator use markdown as their default format. It should be not difficult to translate those .md files into .Rmd ones. If your old blog contains only a few posts, you could just manually modify them; otherwise, you may consider writing some scripts to do this job.

Buy a domain and deploy your blog

There are many places to deploy a static page site, some of which are even free. But I still encourage you to buy your own domain name. Sadly, url is not as important as before since mobile apps took the dominance, but it is still a core part of open web. Services raise and fall, while domain name is always an identity of your own brand.

My old solution is to use GitHub page for jekyll deploying, and to customize DNS via Cloudflare. Because back then, GitHub didn’t support https for custom domain page.

A new solution is through Netlify. The whole process will be more smooth. I will not list every steps, since all the configurations may change in the future. I just show you an outline:

• Create a Netlify account and add your new domain to it.
• Follow the domain verification steps, add DNS information to your domain register’s nameserver list.
• Push your blogdown git repo to GitHub. (GitLab and Bitbucket are also supported)
• Install Netlify app in your GitHub applications.
• Give access to only selected repositories³, like the one you just pushed.
• Add a netlify.toml in your repo.
• Create a “New site from git”, and link it to your repo and domain, also remember to enable https.

After all of these steps, you should head to your domain address and see your site is online.

Custom domain emails

With a custom domain name, you can also set up personal emails with that address. I used mailgun to do the email forwarding before. Its free plan are enough for me. However, mailgun’s service looks like a little rough. I’m also considering other alternatives, like Fastmail or Protonmail.