|
| 1 | ++++ |
| 2 | +date = "2016-04-20T12:00:00" |
| 3 | +draft = false |
| 4 | +image = "banners/getting-started.png" |
| 5 | +tags = ["academic", "hugo"] |
| 6 | +title = "Getting started with the Academic theme for Hugo" |
| 7 | +math = true |
| 8 | ++++ |
| 9 | + |
| 10 | +The Academic theme enables you to easily create a personal academic website using the [Hugo](https://gohugo.io) static site generator. |
| 11 | + |
| 12 | +Key features: |
| 13 | + |
| 14 | +- Designed for academic staff, students, or general personal use |
| 15 | +- Includes Biography, Publications, Projects, News/Blog, Teaching, and Contact sections |
| 16 | +- Write in [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for easy formatting and code highlighting, with [LaTeX](https://en.wikibooks.org/wiki/LaTeX/Mathematics) for mathematical expressions |
| 17 | +- Academic linking (Scholar etc.), Google Analytics, and Disqus comments |
| 18 | +- Responsive and mobile friendly |
| 19 | +- Simple and refreshing one page design |
| 20 | +- Easy to customize |
| 21 | + |
| 22 | + |
| 23 | +## Installation |
| 24 | + |
| 25 | +1. Install [Hugo](https://gohugo.io/overview/installing/) and create a new website: |
| 26 | + |
| 27 | + hugo new site my_website |
| 28 | + cd my_website |
| 29 | + |
| 30 | +2. Install Academic theme with [git](https://help.github.com/articles/set-up-git/): |
| 31 | + |
| 32 | + git clone https://github.com/gcushen/hugo-academic.git themes/academic |
| 33 | + |
| 34 | + Or alternatively, [download Academic](https://github.com/gcushen/hugo-academic/archive/master.zip) and extract it into a `themes/academic` folder within your Hugo website. |
| 35 | + |
| 36 | +3. 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. |
| 37 | + |
| 38 | + cp -av themes/academic/exampleSite/* . |
| 39 | + |
| 40 | +4. Start the Hugo server from your website root folder: |
| 41 | + |
| 42 | + hugo server --watch |
| 43 | + |
| 44 | + Now you can go to [localhost:1313](http://localhost:1313) and your new Academic themed website should appear. |
| 45 | + |
| 46 | +5. Customize your website (see next section), build it by running `hugo`, and deploy it by copying the `public/` directory (by FTP, Rsync, git push, etc.) to your production web server. |
| 47 | + |
| 48 | + |
| 49 | +## Getting Started |
| 50 | + |
| 51 | +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. |
| 52 | + |
| 53 | +The core parameters for the website can be edited in the `config.toml` configuration file. |
| 54 | + |
| 55 | +As can be seen in the example `config.toml`, the social/academic networking icons and education qualifications are defined as multiples of `[[params.social]]` and `[[params.about.education]]` respectively. They can be duplicated or deleted as necessary. |
| 56 | + |
| 57 | +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 `detailed_list = true` under `[params.publications]`. |
| 58 | + |
| 59 | +For deployment, the `baseURL` variable should be changed to match your website URL such as `baseURL = "http://your-site.org/"`. The example Disqus commenting variable should be cleared (e.g. `disqusShortname = ""`) or set to your own Disqus shortname to enable commenting. To enable Google Analytics, add your tracking code in `config.toml` similarly to `googleAnalytics = "UA-12345678-9"`. |
| 60 | + |
| 61 | +Next, you may be interested to read the guide about [managing content]({{< ref "post/managing-content.md" >}}), or continue reading below for advanced customization tips and instructions for keeping the theme up-to-date with any improvements that become available. |
| 62 | + |
| 63 | + |
| 64 | +## Advanced customization |
| 65 | + |
| 66 | +It is possible to carry out many customizations without touching any files in `themes/academic`, making it easier to upgrade the theme in the future. |
| 67 | + |
| 68 | +### Custom theme color (CSS) or JavaScript (JS) |
| 69 | + |
| 70 | +You can link custom CSS and JS assets (relative to your root `static/css` and `static/js` respectively) from your `config.toml` using `custom_css = ["custom.css"]` or `custom_js = ["custom.js"]`. |
| 71 | + |
| 72 | +For example, lets make a green theme. First, define `custom_css = ["green.css"]` in `config.toml`. Then we can download the example [green theme](https://gist.github.com/gcushen/d5525a4506b9ccf83f2bce592a895495) and save it as `static/css/green.css`, relative to your website root (i.e. **not** in the `themes` directory). |
| 73 | + |
| 74 | +### Permalinks |
| 75 | + |
| 76 | +*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): |
| 77 | + |
| 78 | + [permalinks] |
| 79 | + post = "/:year/:month/:day/:slug" |
| 80 | + |
| 81 | +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. |
| 82 | + |
| 83 | + |
| 84 | +## Upgrading |
| 85 | + |
| 86 | +Feel free to *star* the project on [Github](https://github.com/gcushen/hugo-academic/) and monitor the commits for updates. |
| 87 | + |
| 88 | +Before upgrading the theme, 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](https://github.com/gcushen/hugo-academic/releases) (but this doesn't necessarily reflect the latest *master* release). |
| 89 | + |
| 90 | +Before upgrading for the first time, the remote *origin* repository should be renamed to *upstream*: |
| 91 | + |
| 92 | + $ cd themes/academic |
| 93 | + $ git remote rename origin upstream |
| 94 | + |
| 95 | +To list available updates: |
| 96 | + |
| 97 | + $ cd themes/academic |
| 98 | + $ git fetch upstream |
| 99 | + $ git log --pretty=oneline --abbrev-commit --decorate HEAD..upstream/master |
| 100 | + |
| 101 | +Upgrade by running: |
| 102 | + |
| 103 | + $ cd themes/academic |
| 104 | + $ git pull upstream |
| 105 | + |
| 106 | +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>`). |
| 107 | + |
| 108 | +If there are any issues after upgrading, you may wish to compare your site with the latest [example site](https://github.com/gcushen/hugo-academic/tree/master/exampleSite) to check if any settings changed. |
| 109 | + |
| 110 | + |
| 111 | +## Contributing |
| 112 | + |
| 113 | +Please use the [issue tracker](https://github.com/gcushen/hugo-academic/issues) to let me know about any bugs or feature requests, or alternatively make a pull request. |
| 114 | + |
| 115 | + |
| 116 | +## License |
| 117 | + |
| 118 | +Copyright 2016 [George Cushen](https://georgecushen.com). |
| 119 | + |
| 120 | +Released under the [MIT](https://github.com/gcushen/hugo-academic/blob/master/LICENSE.md) license. |
0 commit comments