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.
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:
To build a site from scratch with Hugo, you can simply run:
hugo new site <mysite>
<mysite> will be the container of the source files for your
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
git clone https://github.com/gcushen/hugo-academic.git themes/academic
To have an example structure of a complete webpage, simply copy the
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
You may jump all the steps above by forking this repository and editing the content as you need.
If you forked this repository, go to the root of your site, start
server and follow these steps do edit the content of your webpage:
config.toml. This is straightforward to do since all the fields have intuitive names.
content/home. Some files will not need any further processing as they stand only for holding the “widgets” to render information from other folders.
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
.Rmd files in all
subfolders will be rendered to
config.tomlis the value of
publishDirwhich is set to
docsinstead of the defauld
publicfolder. 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.
build()function has an argument called
ignore.path, which by default is set to
"docs". This means that
.Rmdfiles 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
publishDirthen you must use
build(ignore.path = "public")or any other folder you’ve specified.
baseurl, which must be set accordingly with the host address of your webpage.
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
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
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!).
A tipical workflow should be like this:
cdto the root of your site
hugo server --watch
build()in R to render
docsfolder 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.
.gitignoreand properly set (in repo Github settings) that the site must be deployed from there.
git rm --cached themes/academic git add themes/academic