hugo | Homepage

Getting started with the Academic framework for Hugo

Wed, 20 Apr 2016 00:00:00 -0400

The Academic framework enables you to easily create a beautifully simple personal or academic website using the Hugo static site generator.

Key features:

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

Installation

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/academic folder within your Hugo website.
If you are creating a new website, copy the contents of the exampleSite folder to your website root folder, overwriting existing files if necessary. The exampleSite folder 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:
```
 hugo server
```
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 hugo command. 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).

Getting Started

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.

Core parameters

The core parameters for the website can be edited in the config.toml configuration file:

Set baseurl to your website URL (we recommend GitHub Pages for free hosting)
Set title to 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 portrait.jpg into the static/img/ folder, overwriting any defaults. Note that you can edit the avatar filepath to point to a different image name or clear the value to disable the avatar feature. Alternatively, set gravatar to true to use the Gravatar/Wordpress avatar associated with your email address.
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.

Introduce yourself

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 interests and 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

How to remove unused widgets and content pages.

Themes

The following color themes are available and can be set by the color_theme option in config.toml:

`default`	`ocean`

`forest`	`coffee` + `playfair` font

`dark`

The following font styles are available and can be set by the font option in config.toml:

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.

Advanced customization

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.

The [[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.

Website icon

Save your main icon and mobile icon as square PNG images named icon.png and apple-touch-icon.png, respectively. Place them in your root static/img/ folder.

Analytics

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 config.toml using 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 themes/academic/i18n/en.yaml to 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 i18n/X.yaml where 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 [[menu.main]] to [[Languages.X.menu.main]], where 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.X.md where 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

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 config.toml (before [params] settings):

[permalinks]
    post = "/:year/:month/:day/:slug"

Where :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 post/ to blog/. First, add the following parameters right above the [params] section of your config.toml:

[permalinks]
    post = "/blog/:slug"

Then add 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 config.toml using 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.

Updating

Feel free to star the project on Github to help keep track of updates and check out the release notes prior to updating your site.

Before updating the framework, it is recommended to make a backup of your entire website directory, or at least your themes/academic directory.

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.

License

Released under the MIT license.

Customizing the homepage with widgets

Tue, 19 Apr 2016 00:00:00 -0400

Homepage widgets display as sections on the homepage. They can be enabled/disabled and configured as desired. Academic has the following widgets available to use:

About/biography
Selected publications
Recent publications
Recent news/blog posts
Projects
Selected talks
Recent talks
Contact
Tag cloud
Hero (introduction)
Custom widget (demonstrated with the teaching example)

The example site that you copied to create your site uses all the different types of widget (except talks), so you can generally just delete the widgets you don’t need and customize the parameters of the widgets you wish to keep.

The parameters for each widget vary. They can be found in the preamble/frontmatter (between the pair of +++) for each widget installed in the content/home/ folder.

By default, publications will be displayed in a simple list. If you prefer a more detailed list with abstract and image, you can enable the detailed publication list on the homepage by setting list_format = 2 in content/home/publications.md.

To add a widget manually, copy the relevant widget from themes/academic/exampleSite/content/home/ to your content/home/ folder.

Widget identifiers are set to their respective filenames, so a content/home/about.md widget can be linked from the navigation bar by setting the relevant URL as "#about" in config.toml.

This means that if you want to use multiple instances of a widget, each widget will be assigned a unique ID based on the filename that you set. You can then use that ID for linking, like in the above example.

You can use the custom widget to create your own home page sections.

Simply duplicate (copy/paste) and rename the example teaching file at content/home/teaching.md. Then edit the section title, weight (refer to Ordering sections below), and content as desired.

You may also wish to add a navigation link to the top of the page that points to the new section. This can be achieved by adding something similar to the following lines to your config.toml, where the URL will consist of the first title word in lowercase:

[[menu.main]]
    name = "Research"
    url = "#research"
    weight = 10

If you do not require a particular widget, you can simply delete any associated files from the content/home/ folder.

To remove a navigation link from the top of the page, remove the associated [[menu.main]] entry in config.toml.

Ordering widgets

The order that the homepage widgets are displayed in is defined by the weight parameter in each of the files in the content/home/ directory. The widgets are displayed in ascending order of their weight, so you can simply edit the weight parameters as desired.

Managing content

Mon, 18 Apr 2016 00:00:00 -0400

This is a brief guide to managing content with the Academic framework. Content can include publications, projects, talks, news/blog articles, and widget pages. After you have read this guide about creating and managing content, you may also be interested to learn about writing content with Markdown, LaTeX, and Shortcodes.

To enable LaTeX math rendering for a page, you should include math = true in the page’s +++ preamble, as demonstrated in the included example site. Otherwise, to enable math on the homepage or for all pages, you must globally set math = true in config.toml.

To disable source code highlighting by default for all pages, set highlight = false in config.toml. You can then enable source code highlighting only on pages that need it by setting highlight = true in that page’s preamble. See the code-highlighting docs for more details.

To display a featured image in content page headers, the parameters below can be inserted towards the end of a page’s +++ preamble. It is assumed that the image is located in your static/img/ folder, so the full path in the example below will be static/img/headers/getting-started.png. The caption parameter can be used to write an image caption or credit.

[header]
image = "headers/getting-started.png"
caption = "Image credit: [**Academic**](https://github.com/gcushen/hugo-academic/)"

If you wish to prevent a featured image automatically being used for a post’s thumbnail on the homepage, the preview = false parameter can be added to [header].

Create a publication

To create a new publication:

hugo new publication/my-paper-name.md

Then edit the default variables at the top of content/publication/my-paper-name.md to include the details of your publication. The url_ variables are used to generate links associated with your publication, such as for viewing PDFs of papers. Here is an example:

+++
title = "A publication title, such as title of a paper"

# Date first published.
date = "2013-07-01"

# Authors. Comma separated list, e.g. `["Bob Smith", "David Jones"]`.
authors = ["First author's name", "Second author's name"]

# Publication type.
# Legend:
# 0 = Uncategorized
# 1 = Conference proceedings
# 2 = Journal
# 3 = Work in progress
# 4 = Technical report
# 5 = Book
# 6 = Book chapter
publication_types = ["1"]

# Publication name and optional abbreviated version.
publication = "In *International Conference on Academic*. You may use *Markdown* for italics etc."
publication_short = "In *ICA*"

# Abstract and optional shortened version.
abstract = "The abstract. Markdown and math can be used (note that math may require escaping as detailed in the red alert box below)."
abstract_short = "A short version of the abstract."

# Featured image thumbnail (optional)
image_preview = ""

# Is this a selected publication? (true/false)
selected = true

# Projects (optional).
#   Associate this publication with one or more of your projects.
#   Simply enter the filename (excluding '.md') of your project file in `content/project/`.
#   E.g. `projects = ["deep-learning"]` references `content/project/deep-learning.md`.
projects = []

# Links (optional).
url_pdf = "pdf/my-paper-name.pdf"
url_preprint = ""
url_code = ""
url_dataset = ""
url_project = ""
url_slides = ""
url_video = ""
url_poster = ""
url_source = ""

# Custom links (optional).
#   Uncomment line below to enable. For multiple links, use the form `[{...}, {...}, {...}]`.
# url_custom = [{name = "Custom Link", url = "http://example.org"}]

# Does the content use math formatting?
math = true

# Does the content use source code highlighting?
highlight = true

# Featured image
# Place your image in the `static/img/` folder and reference its filename below, e.g. `image = "example.jpg"`.
[header]
image = "headers/bubbles-wide.jpg"
caption = "My caption 😄"

+++

Further details on your publication can be written here using *Markdown* for formatting. This text will be displayed on the Publication Detail page.

The url_ links can either point to local or web content. Associated local publication content, such as PDFs, may be copied to a static/pdf/ folder and referenced like url_pdf = "pdf/my-paper-name.pdf".

You can also associate custom link buttons with the publication by adding the following block within the variable preamble above, which is denoted by +++:

url_custom = [{name = "Custom Link 1", url = "http://example.org"},
              {name = "Custom Link 2", url = "http://example.org"}]

If you set list_format=2 to enable a detailed listing of publications in the Publication Widget (home/publications.md) or Publication Archive (publication/_index.md), then there are a few more optional variables that you can include in the publication page preamble. You may use abstract_short = "friendly summary of abstract" and publication_short = "abbreviated publication details" to display a friendly summary of the abstract and abbreviate the publication details, respectively. Furthermore, there is the option to display a different image on the homepage to the publication detail page by setting image_preview = "my-image.jpg". This can be useful if you wish to scale down the image for the homepage or simply if you just wish to show a different image for the preview.

Any double quotes (") or backslashes (e.g. LaTeX \times) occurring within the value of any frontmatter parameter (such as the abstract) should be escaped with a backslash (\). For example, the symbol " and LaTeX text \times become \" and \\times, respectively. Refer to the TOML documentation for more info.

Create a blog post

To create a blog/news article:

hugo new post/my-article-name.md

Then edit the newly created file content/post/my-article-name.md with your full title and content.

Hugo will automatically generate summaries of posts that appear on the homepage. If you are dissatisfied with an automated summary, you can either limit the summary length by appropriately placing  in the article body, or completely override the automated summary by adding a summary parameter to the +++ preamble such that:

summary = "Summary of my post."

To disable commenting for a specific post, you can add disable_comments = true to the post +++ preamble. Or to disable commenting for all posts, you can either set disqusShortname = "" or disable_comments = true in config.toml.

Create a project

To create a project:

hugo new project/my-project-name.md

Then edit the newly created file content/project/my-project-name.md. Either you can link the project to an external project website by setting the external_link = "http://external-project.com" variable at the top of the file, or you can add content (below the final +++) in order to render a project page on your website.

Create a talk

To create a talk:

hugo new talk/my-talk-name.md

Then edit the newly created file content/talk/my-talk-name.md with your full talk title and details. Note that many of the talk parameters are similar to the publication parameters.

So you would like to create a page which utilizes Academic’s widget system, similar to the homepage?

Create a new folder in your content folder, naming it with your new page name. In this example, we will create a courses page by creating a content/courses/ folder.

Within your new content/courses/ folder, create a file named _index.md containing the following parameters:

+++
title = "Courses"
date = 2017-01-01
widgets = true
+++

Install widgets into your content/courses/ folder. To achieve this, widgets can be copied from your content/home/ folder or downloaded from Github.

Create other pages (e.g. CV)

For other types of content, it is possible to create your own custom pages. For example, let’s create a cv.md page for your Curriculum Vitae in your content folder. Copy across the frontmatter from the top of one of your post files, adapting it as necessary, and editing your Markdown content below. You can then link to your new page by adding the code [My CV]{{< ref "cv.md" >}} to any of your existing content.

Alternatively, for the above example, we could use a PDF of your Curriculum Vitae. For this purpose, create a folder called files within your static folder and move a PDF file named cv.pdf to that location, so we have a static/files/cv.pdf file path. The PDF can then be linked to from any content by using the code: {{% staticref "files/cv.pdf" %}}Download my CV{{% /staticref %}}.

Manage archive pages

The archive (or node index) pages (e.g. /post/) are the special pages which list all of your content. They can exist for blog posts, publications, and talks. The homepage widgets will automatically link to the archive pages when you have more items of content than can be displayed in the widget. Therefore, if you don’t have much content, you may not see the automatic links yet - but you can also manually link to them using a normal Markdown formatted link in your content.

You can edit the title and add your own content, such as an introduction, by copying the following content _index.md files from the example site to the same structure within your content/ folder:

/themes/academic/exampleSite/content/post/_index.md
/themes/academic/exampleSite/content/publication/_index.md
/themes/academic/exampleSite/content/talk/_index.md

Then edit the title parameter in each _index.md as desired and add any content after the +++ preamble/frontmatter ends. You will notice that the _index.md files differ slightly, with some having special options available for the associated content type. For example, publication/_index.md contains an option for setting the citation style of the listings which appear on the publication archive page.

Removing content

Generally, to remove content, simply delete the relevant file from your content/post, content/publication, content/project, or content/talk folder.

View your updated site

After you have made changes to your site, you can view it by running the hugo server command and then opening localhost:1313 in your web browser.

Deploy your site

Finally, you can build the static website to a public/ folder ready for deployment using the hugo command.

You may then deploy your site by copying the public/ directory (by FTP, SFTP, WebDAV, Rsync, git push, etc.) to your production web server.

Note that running hugo does not remove any previously generated files before building. Therefore, it’s best practice to delete your public/ directory prior to running hugo to ensure no old or interim files are deployed to your server.