Academic personal pages

This repository hosts the source code to build an academic personal page
based on the academic theme for Hugo. The pages are created
with Rmarkdown (.Rmd) files and converted to markdown (.md) with the
R package knitr.

Installation requirements

You must have Hugo installed on your system. In most Linux
distributions, it may already be available through your package manager.
If it is not, follow the instructions on the Hugo website.

You will also need the latest version of R and the latest version of
knitr, which can be installed as follows:

library(devtools)install_github("yihui/knitr")

Building from scratch

To build a site from scratch with Hugo, you can simply run:

hugo new site <mysite>

where <mysite> will be the container of the source files for your
site. Then cd mysite. By default there will be no theme preloaded, so
you will have to pick one from here. As we are using the academic
theme, the “installation” would be done by cloning the git repository of
the theme:

To have an example structure of a complete webpage, simply copy the
exampleSite folder:

cp -av themes/academic/exampleSite/* .

Then start Hugo server with

hugo server --watch

and open your browser at localhost:1313 to see the website. Every time
you edit and save a file from this structure, the pega is automaticaly
refreshed.

Forking this repository

You may jump all the steps above by forking this repository and editing
the content as you need.

Usage

If you forked this repository, go to the root of your site, start hugo
server and follow these steps do edit the content of your webpage:

Edit the contents of config.toml. This is straightforward to do
since all the fields have intuitive names.

Edit all the .Rmd files under content/home. Some files will not
need any further processing as they stand only for holding the
“widgets” to render information from other folders.

Edit or create new files (copy the TOML headers from existing files)
in folders: project/, publication/, and talk/ (if you will use
it all). If files inside this folders are properly set, then
information will be automatic rendered in the webpage.

Note that all files created are .Rmd files, since we may want to
render R source code from any page. To render all .Rmd files at once,
source and run the custom function build(). All .Rmd files in all
subfolders will be rendered to .md files.

Important:

One important modification made in config.toml is the value of
publishDir which is set to docs instead of the defauld public
folder. This was made only because to publish a website from Github
pages, the contents must lie in a folder with this name. We are not
using this scheme in this repository, but may want to use it in others,
so it was set like this.

For the reason stated above, the build() function has an argument
called ignore.path, which by default is set to "docs". This means
that .Rmd files under this path will be ignored for kni’ing since
they dont’t need (and didn’t should be) processed. So if you didn’t
specify a publishDir then you must use build(ignore.path =
"public") or any other folder you’ve specified.

Other important field in config.toml is the baseurl, which must be
set accordingly with the host address of your webpage.

Building the website

After editing the contents and running build() you still have one more
step to effectively build your site with Hugo. This is done by simply
running

hugo

from the root of your project. The command will build the site by
creating all the necessary files at the publishDir directory, which in
our case is the docs folder. This is all you need to host your webpage
somewhere.

Deploying the site

To publish your site in a personal server, you just have to move the
contents of the docs folder to the apropriate place on that server.
This can be done with rsync or any other tool.

For convenience, there is a shell script called deploy.sh which can be
properly set to build and deploy the contents of your site to a remote
server. (Edit this file before using it!).

Workflow

A tipical workflow should be like this:

cd to the root of your site

Run hugo server --watch

Edit/create new files (.Rmd)

Run build() in R to render .Rmd files

Build your site with hugo

Deploy with deploy.sh

Details when hosting on git

If you are not using Github pages to host your site, as in this case,
you may want to put the docs folder in your .gitignore, since they
are only the byproducts of a build from the source files. Therefore,
it is important only to track those source files.

If you will host your page with Github pages, then remove the docs
folder from .gitignore and properly set (in repo Github settings)
that the site must be deployed from there.

Troubleshooting

If you build the site from scratch and cloned the academic theme, then
it is a git repository inside another (if you made the root of your
site a git repository). To properly track the theme folder you may
need to do this: