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 --watch

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:

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. Alternatively, you can edit the avatar filepath to point to a different image name or clear the value to disable the avatar feature.

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.

Theme color (CSS)

For example, lets make a green theme. First, define custom_css = ["green.css"] in config.toml. Then we can download the example green theme and save it as static/css/green.css, relative to your website root (i.e. not in the themes directory).

Analytics

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.

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.

Upgrading

Feel free to star the project on Github and monitor the commits for updates.

Before upgrading the framework, it is recommended to make a backup of your entire website directory, or at least your themes/academic directory. You can also read about the most recent milestones (but this doesn’t necessarily reflect the latest master release).

Before upgrading for the first time, the remote origin repository should be renamed to 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 upgrading, you may wish to compare your site with the latest example site to check if any settings changed.

Feedback & Contributing

Please use the issue tracker to let me know about any bugs or feature requests, or alternatively make a pull request.