Getting started with the Academic framework for Hugo
The Academic framework enables you to easily create a beautifully simple personal or academic website using the Hugo static site generator.
- Easily manage your homepage, blog posts, publications, talks, and projects
- Configurable widgets available for Biography, Publications, Projects, News/Blog, Talks, and Contact
- Need a different section? Just use the Custom widget!
- Write in Markdown for easy formatting and code highlighting, with LaTeX for mathematical expressions
- Social/academic network linking, Google Analytics, and Disqus comments
- Responsive and mobile friendly
- Simple and refreshing one page design
- Multilingual and easy to customize
Table of Contents
Install Hugo and create a new website by typing the following commands in your Terminal or Command Prompt app:
hugo new site my_website cd my_website
Install Academic with git:
git clone https://github.com/gcushen/hugo-academic.git themes/academic
Or alternatively, download Academic and extract it into a
themes/academicfolder within your Hugo website.
If you are creating a new website, copy the contents of the
exampleSitefolder to your website root folder, overwriting existing files if necessary. The
exampleSitefolder contains an example config file and content to help you get started.
cp -av themes/academic/exampleSite/* .
Start the Hugo server from your website root folder:
Now you can go to localhost:1313 and your new Academic powered website should appear.
Customize your website - refer to the Getting Started section below
Build your site by running the
hugocommand. Then host it for free using Github Pages. Or alternatively, copy the generated
public/directory (by FTP, Rsync, etc.) to your production web server (such as your university’s hosting service).
Assuming you created a new website with the example content following the installation steps above, this section explores just a few more steps in order to customize it.
The core parameters for the website can be edited in the
config.toml configuration file:
baseurlto your website URL (we recommend GitHub Pages for free hosting)
titleto your desired website title such as your name
- The example Disqus commenting variable should be cleared (e.g.
disqusShortname = "") or set to your own Disqus shortname to enable commenting
- Edit your details under
[params]; these will be displayed mainly in the homepage about and contact widgets (if used). To disable a contact field, simply clear the value to
- Place a square cropped portrait photo named
static/img/folder, overwriting any defaults. Note that you can edit the
avatarfilepath to point to a different image name or clear the value to disable the avatar feature. Alternatively, set
trueto use the Gravatar/Wordpress avatar associated with your
- To enable LaTeX math for your site, set
math = true
- Social/academic networking links are defined as multiples of
[[params.social]]. They can be created or deleted as necessary.
Edit your biography in the about widget
content/home/about.md that you copied across from the
themes/academic/exampleSite/ folder. The research interests and qualifications are stored as
education variables. The academic qualifications are defined as multiples of
[[education.courses]] and can be created or deleted as necessary. It’s possible to completely hide the interests and education lists by deleting their respective variables.
Customize the homepage
Refer to our guide on using widgets to customize your homepage.
Add your content
Refer to our guide on managing content to create your own publications, blog posts, talks, and projects.
Remove unused widgets and pages
The following color themes are available and can be set by the
color_theme option in
The following font styles are available and can be set by the
font option in
- default (modern)
- classic (original Academic v1 style)
- playfair (serif)
Customization & updating
Continue reading below for advanced customization tips and instructions for keeping the framework up-to-date with any improvements that become available.
It is possible to carry out many customizations without touching any files in
themes/academic, making it easier to update the framework in the future.
[[menu.main]] entries towards the bottom of
config.toml define the navigation links at the top of the website. They can be added or removed as desired.
To create a dropdown sub-menu, add
identifier = "something" to the parent item and
parent = "something" to the child item.
Save your main icon and mobile icon as square PNG images named
apple-touch-icon.png, respectively. Place them in your root
To enable Google Analytics, add your tracking code in
config.toml similarly to
googleAnalytics = "UA-12345678-9".
Third party and local scripts (JS)
To add a third party script, create a file named
head_custom.html in a
layouts/partials/ folder at the root of your website (not in the
themes folder). Any HTML code added to this file will be included within your website’s
<head>. Therefore, it’s suitable for adding custom metadata or third party scripts specified with the async attribute.
Whereas for your own local scripts, you can link your local JS assets (relative to your root
static/js) from your
custom_js = ["custom.js"].
Language and translation
The interface text (e.g. buttons) is stored in language files which are collected from Academic’s
themes/academic/i18n/ folder, as well as an
i18n/ folder at the root of your project.
To edit the interface text, copy
i18n/en.yaml (relative to the root of your website). Open the new file and make any desired changes to the text appearing after
translation:. Note that the language files are formatted in YAML syntax.
To translate the interface text to another language, follow the above instructions, but name the new file in the form
X is the appropriate ISO/RFC5646 language identifier for the translation. Then follow the brief instructions in the Language section at the bottom of your
config.toml. To change the default language used by Academic, set
defaultContentLanguage to the desired language identifier in your configuration file.
To translate the navigation bar, you can edit the default
[[menu.main]] instances in
config.toml. However, for a multilingual site, you will need to duplicate all of the
[[menu.main]] instances and rename the new instances from
X is the language identifier (e.g.
[[Languages.zh.menu.main]] for Simplified Chinese). Thus, the navigation bar can be displayed in multiple languages.
To translate a content file in your
content/ folder into another language, copy the file to
filename is your existing filename and
X is the appropriate ISO/RFC5646 language identifier for the translation. Then translate the content in the new file to the specified language.
For further details on Hugo’s internationalization and multilingual features, refer to the associated Hugo documentation.
Permalinks, or permanent links, are URLs to individual pages and posts on your website. They are permanent web addresses which can be used to link to your content. Using Hugo’s permalinks option these can be easily customized. For example, the blog post URL can be changed to the form yourURL/2016/05/01/my-post-slug by adding the following near the top of your
[permalinks] post = "/:year/:month/:day/:slug"
:slug defaults to the filename of the post, excluding the file extension. However, slug may be overridden on a per post basis if desired, simply by setting
slug = "my-short-post-title" in your post preamble.
Example 2: let’s consider changing the URL path of posts from
blog/. First, add the following parameters right above the
[params] section of your
[permalinks] post = "/blog/:slug"
aliases = ["/blog/"] to your post archive page
post/_index.md so that it can be accessed from the /blog/ URL.
Advanced style customization (CSS)
For advanced customization of the style, you can link custom CSS assets (relative to your root
static/css) from your
custom_css = ["custom.css"].
For example, let’s override some of Academic’s default styles. First, define
custom_css = ["override.css"] in
config.toml. Then we can create the file
static/css/override.css, relative to your website root (i.e. not in the
themes directory). Add your custom CSS to this file.
Before updating the framework, it is recommended to make a backup of your entire website directory, or at least your
Before updating for the first time, the remote origin repository should be renamed to upstream:
$ cd themes/academic $ git remote rename origin upstream
To list available updates:
$ cd themes/academic $ git fetch upstream $ git log --pretty=oneline --abbrev-commit --decorate HEAD..upstream/master
Then, update by running:
$ git pull upstream
If you have modified files in
themes/academic, git will attempt to auto-merge changes. If conflicts are reported, you will need to manually edit the files with conflicts and add them back (
git add <filename>).
If there are any issues after updating, you may wish to compare your site with the latest example site to check if any settings changed in
config.toml or the
+++ frontmatter of content files.
Feedback & Contributing
Please use the issue tracker to let me know about any bugs or feature requests, or alternatively make a pull request.
For general questions about Hugo, there is a Hugo discussion forum.
Copyright 2017 George Cushen.
Released under the MIT license.