How to Blog using Overleaf: with Jekyll and Surge
Figure: The above screenshot shows an Overleaf document in making.
I have switched over to Overleaf for all my writing, starting from academic articles, memos, reports, virtually, any writing task can be easily done with Overleaf. It is web based, stable, easy and LaTeX based. As a result, I can easily separate content from logic and presentation (formatting). Write first, set up the logic of the document later, and then last of all, decide the formatting. For me, it sets up a nice, relaxed flow of writing that I enjoy.
In this series, in the past, I have explored that there are a number of ways in which you can incorporate your other writing and research with Overleaf. You can use git, and pandoc to play very nicely with Overleaf. You can also use markdown and pandoc with Overleaf. As Overleaf provides a git bridge, you can take your project directly to your hard drive and store it in a folder and can sync with Overleaf.
That is all good. One of the issues that I have been exploring with Overleaf is whether I can use Overleaf as a blogging tool. That way, I could still use Overleaf or a LaTeXor markdown as my main writing environment, and I could push the changes to my blog.
I recently discovered Surge.sh as an application (shout out to https://medium.com/surge-sh) which is a Node.js based module that you can use to host one page applications. You can also use surge to host a jekyll site. They have a great tutorial site on Surge that you can check out to see how they do it.
Jekyll is a blog aware ruby on rails module that also powers blogs that you can host in github hosted blogs and pages. You can just use a combination of jekyll, Surge, and Overleaf to easily host your own blog that you write in Overleaf and push everywhere.
The steps are not that complicated once you install Jekyll and Surge for your systems. You will find installation instructions for your systems in the respective websites (see above). Once you install Jekyll and Surge (and have a confirmed account with Surge), you are all set. Of course, this is assuming that you also have an account with Overleaf where you write your blog post. Besides Jekyll and Surge, you will need pandoc and git for this workflow to work. Please follow instructions on the Pandoc and Git pages to install Pandoc and Git for your system. Git is a great version control system and Overleaf produces a git bridge.
To access and use git from overleaf, click the share button on the top of the Overleaf document page and it will provide you with the git clone link. There are several tutorials on Git that you can read. There is even a free Git Book for learning Git.
Once you have configured those above processes, setting up a blog from Overleaf is actually quite easy. Here are the steps:
Step I: Set up the Jekyll blog. Do this first.
jekyll new myblog
Exhibit 1: Above commands worked on a Mac terminal to set up a Jekyll blog.
When you do this, Jekyll installs a minimally configured blog site on your local folder. This will create your blog locally on your chosen folder. In my case, the folder is myblog within myblogfolder (so myblogfolder/myblog). After you run jekyll build, it creates a folder _site. This is where your entire site will live and be updated on Surge. You will write your blog posts in markdown format to _posts folder.
Step II: Connect your local jekyll site to Surge.sh
You will push this entire folder to the Surge as follows:
surge _site/ mynewblogsite.surge.sh
But before you do so, check out Surge’s documentation.
That’s it. Your new blog is up and running at mynewblogsite.surge.sh. This is a Jekyll based blog, and Jekyll has its own structure. That is quite a process to learn the nitty gritty and details so I will leave that to you to read on their well documented site. You will need to change the _config.yml document on a text editor. You will find the _config.yml on the root folder of your blog and at the least, change the site title, your name, email address, etc.
Step III: Connect the content you wrote on Overleaf to your blog
Write your content in Overleaf. It’s a good idea to keep assets such as images to a folder titled images and then refer from that folder. Keeps things simple.
Here are the steps
- Go to the SHARE button on the top of Overleaf page
- Copy the “Clone with Git” box contents
- Now move to the terminal and access the root folder of your blog
- In the root folder of the blog, type
git clone <URL of the Overleaf document git share link>
Step IV: Convert the latex codes to markdown codes
For this, you will need pandoc to convert your latex formatted Overleaf document to markdown format. In the terminal while in the root folder you do:
pandoc -f latex -t markdown tutorial.tex -o ../_posts/YYYY-MM-DD-topic.md
% this format of YYYY-MM-DD-topic is important.
% So, for instance, it could be 2016-10-16-posting.md
% also note, that you are going to save the markdown formatted document to the _posts folder
Step V: Edit the markdown document
Then in a text editor you edit the markdown document and add the following codes at the head of the markdown document:
title: Title of the page
author: Your name
This should be the first few lines on the markdown document. These are the preamble you need to push the content out there. You will also need to configure the Jekyll blog. Another point that you need to note is that, if you want to include assets such as images or pdf files that you want to display on your site or want your readers to download from the blog, then, modify the markdown code to include within two pairs of curly brackets the word “site.url”.
For more information, see how to write posts in Jekyll
Note how they ask you to include images in your Jekyll powered blog. You need to indicate that with two curly brackets and inside the curly brackets site.url. That above code is important, otherwise your images will not show. You also build your blog using markdown. You can learn more about how to write in markdown here
Step VI: Push it to surge from the root of your local blog folder
surge _site/ your surge site URL`
You have to follow these six steps only for the first time. After that, it’s just a matter of
- connecting your folder of blog posts to the git,
- and pulling and pushing contents to and from that folder to your Overleaf folder,
- converting the latex posts using pandoc, and editing the markdown documents in a text editor as I shown above to work with them,
- Build jekyll by issuing
% Do this from the root of your blog folder
- then pushing it back to surge.
In this way, you can keep writing in Overleaf and building your blog in Surge through Jekyll. Of course, you can do the reverse as well. That is, write everything in markdown and then use pandoc and git to push it back to Overleaf. That way, your Overleaf and blog will play well with each other.
Originally published at academicblog.surge.sh on October 16, 2016.