michaelh/hugo-academic-mirror
1
0
Fork 0
mirror of https://github.com/gcushen/hugo-academic.git synced 2025-07-26 03:00:50 +02:00
Code Issues Projects Releases Packages Wiki Activity

Update documentation

Browse source
This commit is contained in:
George Cushen 2016-05-31 18:36:43 +01:00
commit 43d24aa6d1
8 changed files with 510 additions and 194 deletions
Download patch file Download diff file Expand all files Collapse all files

131
README.md
View file

@ -14,6 +14,8 @@ Key features:
- Simple and refreshing one page design
- Easy to customize
Latest demo: [gcushen.github.io/hugo-academic-demo/](http://gcushen.github.io/hugo-academic-demo/)
## Installation
1. Install [Hugo](https://gohugo.io/overview/installing/) and create a new website:
@ -21,11 +23,11 @@ Key features:
hugo new site my_website
cd my_website
2. Install Academic theme with `git`:
2. Install Academic theme with [git](https://help.github.com/articles/set-up-git/):
git clone git@github.com:gcushen/hugo-academic.git themes/academic
Or alternatively, install by downloading from [Github](https://github.com/gcushen/hugo-academic/) into a `themes/academic` folder within your Hugo website.
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.
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.
@ -41,124 +43,7 @@ Key features:
## 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.
### Configuration
The core parameters for the website can be edited in the `config.toml` configuration file.
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.education]]` respectively. They can be duplicated or deleted as necessary.
Homepage sections will automatically disappear if you remove content (`content/`) from them. Thus, the news/blog feature can be removed simply by deleting any files in `content/post/`.
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"`.
### Introduce yourself with a biography
Place a cropped portrait photo named `portrait.jpg` into the `static/img/` folder, overwriting any defaults.
Edit your biography in the example `content/home/about.md` file. The research interests and qualifications are stored separately as `interests` and `params.education` variables in `config.toml`, as can be seen in the example config. It's possible to completely hide the interests and education lists by deleting their respective variables.
### 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:
```
+++
abstract = "An abstract..."
authors = ["First author's name", "Second author's name"]
date = "2013-07-01"
image = ""
image_preview = ""
math = false
publication = "The publishing part of the citation goes here. You may use *Markdown* for italics etc."
title = "A publication title, such as title of a paper"
url_code = ""
url_dataset = ""
url_pdf = "pdf/my-paper-name.pdf"
url_project = ""
url_slides = ""
url_video = ""
+++
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(s) within the variable preamble above, which is denoted by `+++`:
```
[[url_custom]]
name = "Custom Link"
url = "http://www.example.org"
```
Note that the `image` variables are just placeholders that may be used to reference associated images. If desired, you can modify the publication detail and list pages to show the respective images. These images should be referenced similarly to the above process for PDFs, but using the `static/img/` folder.
### Post an article
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.
You may use [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) to format the content. Furthermore, code highlighting and LaTeX math rendering are supported. To enable LaTeX math rendering for a page, you should include `math = true` in the preamble, as demonstrated in the included example site.
Images may be added to a post by placing them in your `static/img/` folder and referencing them in Markdown such as with `![alt text](img/my-image.jpg)`.
### 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.
### Add a section to home page
To add a new section to the home page:
hugo new home/my-section-name.md
Then edit the newly created file `content/home/my-section-name.md` with your section title and content. In the `+++` preamble, you should also increment the `section_id` to ensure it's unique amongst the other sections in `content/home` and you can adjust `weight` variable to change the order within the custom section of the home page.
You may also wish to add a navigation link 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
### Removing content
Generally, to remove content, simply delete the relevant file from your `content/post`, `content/publication`, `content/project`, or `content/home` folder.
Then you can re-build and view the updated website with the `hugo` and `hugo server --watch` commands, respectively.
## Advanced customization
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.
### Custom theme color (CSS) or JavaScript (JS)
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"]`.
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).
### 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.
Refer to the [documentation](http://gcushen.github.io/hugo-academic-demo/#posts) under the *Posts* section of the latest Academic theme demo.
## Upgrading
@ -180,9 +65,7 @@ To list available updates:
Upgrade by running:
$ cd themes/academic
$ git fetch upstream
$ git checkout master
$ git merge upstream/master
$ 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>`).
@ -194,6 +77,6 @@ Please use the [issue tracker](https://github.com/gcushen/hugo-academic/issues)
## License
Copyright 2016 [George Cushen](http://cushen.me).
Copyright 2016 [George Cushen](https://georgecushen.com).
Released under the [MIT](https://github.com/gcushen/hugo-academic/blob/master/LICENSE.md) license.

1
exampleSite/content/home/teaching.md
View file

@ -2,6 +2,7 @@
date = "2016-04-20T00:00:00"
draft = false
title = "teaching"
subtitle = ""
section_id = 10
weight = 10
+++

23
exampleSite/content/post/example-post.md
View file

@ -1,23 +0,0 @@
+++
date = "2016-04-20T00:00:00"
draft = false
tags = ["test", "programming"]
title = "Programming Example"
math = false
+++
**Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Duis posuere tellus ac convallis placerat. Proin tincidunt magna sed ex sollicitudin condimentum. Sed ac faucibus dolor, scelerisque sollicitudin nisi. Cras purus urna, suscipit quis sapien eu, pulvinar tempor diam. Quisque risus orci, mollis id ante sit amet, gravida egestas nisl. Sed ac tempus magna. Proin in dui enim. Donec condimentum, sem id dapibus fringilla, tellus enim condimentum arcu, nec volutpat est felis vel metus. Vestibulum sit amet erat at nulla eleifend gravida.
~~~python
# Example of code highlighting
input_string_var = input("Enter some data: ")
print("You entered: {}".format(input_string_var))
~~~
Nullam vel molestie justo. Curabitur vitae efficitur leo. In hac habitasse platea dictumst. Sed pulvinar mauris dui, eget varius purus congue ac. Nulla euismod, lorem vel elementum dapibus, nunc justo porta mi, sed tempus est est vel tellus. Nam et enim eleifend, laoreet sem sit amet, elementum sem. Morbi ut leo congue, maximus velit ut, finibus arcu. In et libero cursus, rutrum risus non, molestie leo. Nullam congue quam et volutpat malesuada. Sed risus tortor, pulvinar et dictum nec, sodales non mi. Phasellus lacinia commodo laoreet. Nam mollis, erat in feugiat consectetur, purus eros egestas tellus, in auctor urna odio at nibh. Mauris imperdiet nisi ac magna convallis, at rhoncus ligula cursus.
Cras aliquam rhoncus ipsum, in hendrerit nunc mattis vitae. Duis vitae efficitur metus, ac tempus leo. Cras nec fringilla lacus. Quisque sit amet risus at ipsum pharetra commodo. Sed aliquam mauris at consequat eleifend. Praesent porta, augue sed viverra bibendum, neque ante euismod ante, in vehicula justo lorem ac eros. Suspendisse augue libero, venenatis eget tincidunt ut, malesuada at lorem. Donec vitae bibendum arcu. Aenean maximus nulla non pretium iaculis. Quisque imperdiet, nulla in pulvinar aliquet, velit quam ultrices quam, sit amet fringilla leo sem vel nunc. Mauris in lacinia lacus.
Suspendisse a tincidunt lacus. Curabitur at urna sagittis, dictum ante sit amet, euismod magna. Sed rutrum massa id tortor commodo, vitae elementum turpis tempus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean purus turpis, venenatis a ullamcorper nec, tincidunt et massa. Integer posuere quam rutrum arcu vehicula imperdiet. Mauris ullamcorper quam vitae purus congue, quis euismod magna eleifend. Vestibulum semper vel augue eget tincidunt. Fusce eget justo sodales, dapibus odio eu, ultrices lorem. Duis condimentum lorem id eros commodo, in facilisis mauris scelerisque. Morbi sed auctor leo. Nullam volutpat a lacus quis pharetra. Nulla congue rutrum magna a ornare.
Aliquam in turpis accumsan, malesuada nibh ut, hendrerit justo. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Quisque sed erat nec justo posuere suscipit. Donec ut efficitur arcu, in malesuada neque. Nunc dignissim nisl massa, id vulputate nunc pretium nec. Quisque eget urna in risus suscipit ultricies. Pellentesque odio odio, tincidunt in eleifend sed, posuere a diam. Nam gravida nisl convallis semper elementum. Morbi vitae felis faucibus, vulputate orci placerat, aliquet nisi. Aliquam erat volutpat. Maecenas sagittis pulvinar purus, sed porta quam laoreet at.

119
exampleSite/content/post/getting-started.md Normal file
View file

@ -0,0 +1,119 @@
+++
date = "2016-04-20T12:00:00"
draft = false
tags = ["academic", "hugo"]
title = "Getting started with the Academic theme for Hugo"
math = true
+++
The Academic theme enables you to easily create a personal academic website using the [Hugo](https://gohugo.io) static site generator.
Key features:
- Designed for academic staff, students, or general personal use
- Includes Biography, Publications, Projects, News/Blog, Teaching, and Contact sections
- 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
- Academic linking (Scholar etc.), Google Analytics, and Disqus comments
- Responsive and mobile friendly
- Simple and refreshing one page design
- Easy to customize
## Installation
1. Install [Hugo](https://gohugo.io/overview/installing/) and create a new website:
hugo new site my_website
cd my_website
2. Install Academic theme with [git](https://help.github.com/articles/set-up-git/):
git clone git@github.com:gcushen/hugo-academic.git themes/academic
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.
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.
cp -av themes/academic/exampleSite/* .
4. Start the Hugo server from your website root folder:
hugo server --watch
Now you can go to [localhost:1313](http://localhost:1313) and your new Academic themed website should appear.
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.
## 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.
The core parameters for the website can be edited in the `config.toml` configuration file.
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.
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]`.
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"`.
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.
## Advanced customization
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.
### Custom theme color (CSS) or JavaScript (JS)
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"]`.
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).
### 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](https://github.com/gcushen/hugo-academic/) and monitor the commits for updates.
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).
Before upgrading 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
Upgrade by running:
$ cd themes/academic
$ 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 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.
## Contributing
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.
## License
Copyright 2016 [George Cushen](https://georgecushen.com).
Released under the [MIT](https://github.com/gcushen/hugo-academic/blob/master/LICENSE.md) license.

102
exampleSite/content/post/managing-content.md Normal file
View file

@ -0,0 +1,102 @@
+++
date = "2016-04-20T11:00:00"
draft = false
tags = ["academic", "hugo"]
title = "Managing content"
math = false
+++
This is a brief guide to managing content with the Academic theme. Content can include homepage sections, publications, projects, and news/blog articles. 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]({{< ref "post/writing-markdown-latex.md" >}}).
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 display an image in publication, post, or project page headers, you can include the `image = "my-image.jpg"` option in the page `+++` preamble. It is automatically assumed that the image is located in your `static/img/` folder. In the context of posts and projects, the image is intended to behave as a full width banner across the top of the article.
## Homepage sections
Homepage sections for publications, projects and posts will automatically hide when there is no content of the respective type. Therefore, if you do not require a particular feature, you can simply delete any associated content in the `content/` folder.
### Introduce yourself with a biography
Place a cropped portrait photo named `portrait.jpg` into the `static/img/` folder, overwriting any defaults.
Edit your biography in the example `content/home/about.md` file that you copied across from the `themes/academic/exampleSite/` folder. The research interests and qualifications are stored separately as `interests` and `education` variables under `[params.about]` in `config.toml`, as can be seen in the example config. It's possible to completely hide the interests and education lists by deleting their respective variables.
### Add a section to the homepage
To add a new section to the homepage:
hugo new home/my-section-name.md
Then edit the newly created file `content/home/my-section-name.md` with your section title and content. In the `+++` preamble, you should also increment the `section_id` to ensure it's unique amongst the other sections in `content/home` and you can adjust `weight` variable to change the order within the custom section of the home page.
You may also wish to add a navigation link pointing 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
## 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:
```
+++
abstract = "An abstract..."
authors = ["First author's name", "Second author's name"]
date = "2013-07-01"
image = ""
image_preview = ""
math = false
publication = "The publishing part of the citation goes here. You may use *Markdown* for italics etc."
title = "A publication title, such as title of a paper"
url_code = ""
url_dataset = ""
url_pdf = "pdf/my-paper-name.pdf"
url_project = ""
url_slides = ""
url_video = ""
+++
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(s) within the variable preamble above, which is denoted by `+++`:
```
[[url_custom]]
name = "Custom Link"
url = "http://www.example.org"
```
If you enabled `detailed_list` for publications in `config.toml`, 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.
## Post an article
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.
## 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.
## Removing content
Generally, to remove content, simply delete the relevant file from your `content/post`, `content/publication`, `content/project`, or `content/home` folder.
Then you can re-build and view the updated website with the `hugo` and `hugo server --watch` commands, respectively.

47
exampleSite/content/post/math-example.md
View file

@ -1,47 +0,0 @@
+++
date = "2016-04-20T00:00:00"
draft = false
tags = ["test", "math"]
title = "Math Example"
math = true
+++
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis posuere tellus ac convallis placerat. Proin tincidunt magna sed ex sollicitudin condimentum. Sed ac faucibus dolor, scelerisque sollicitudin nisi. Cras purus urna, suscipit quis sapien eu, pulvinar tempor diam. Quisque risus orci, mollis id ante sit amet, gravida egestas nisl. Sed ac tempus magna. Proin in dui enim. Donec condimentum, sem id dapibus fringilla, tellus enim condimentum arcu, nec volutpat est felis vel metus. Vestibulum sit amet erat at nulla eleifend gravida.
## An example mathematical expression rendered from $\rm \LaTeX$ math code
LaTeX:
```TeX
$$\left [ – \frac{\hbar^2}{2 m} \frac{\partial^2}{\partial x^2} + V \right ] \Psi = i \hbar \frac{\partial}{\partial t} \Psi$$
```
Result:
$$\left [ – \frac{\hbar^2}{2 m} \frac{\partial^2}{\partial x^2} + V \right ] \Psi = i \hbar \frac{\partial}{\partial t} \Psi$$
### An example of a table created using *Markdown*
Code:
```Markdown
| Command | Description |
| ------------------| ------------------------------ |
| `hugo` | Build your website. |
| `hugo serve -w` | View your website. |
```
Result:
| Command | Description |
| ------------------| ------------------------------ |
| `hugo` | Build your website. |
| `hugo serve -w` | View your website. |
Nullam vel molestie justo. Curabitur vitae efficitur leo. In hac habitasse platea dictumst. Sed pulvinar mauris dui, eget varius purus congue ac. Nulla euismod, lorem vel elementum dapibus, nunc justo porta mi, sed tempus est est vel tellus. Nam et enim eleifend, laoreet sem sit amet, elementum sem. Morbi ut leo congue, maximus velit ut, finibus arcu. In et libero cursus, rutrum risus non, molestie leo. Nullam congue quam et volutpat malesuada. Sed risus tortor, pulvinar et dictum nec, sodales non mi. Phasellus lacinia commodo laoreet. Nam mollis, erat in feugiat consectetur, purus eros egestas tellus, in auctor urna odio at nibh. Mauris imperdiet nisi ac magna convallis, at rhoncus ligula cursus.
Cras aliquam rhoncus ipsum, in hendrerit nunc mattis vitae. Duis vitae efficitur metus, ac tempus leo. Cras nec fringilla lacus. Quisque sit amet risus at ipsum pharetra commodo. Sed aliquam mauris at consequat eleifend. Praesent porta, augue sed viverra bibendum, neque ante euismod ante, in vehicula justo lorem ac eros. Suspendisse augue libero, venenatis eget tincidunt ut, malesuada at lorem. Donec vitae bibendum arcu. Aenean maximus nulla non pretium iaculis. Quisque imperdiet, nulla in pulvinar aliquet, velit quam ultrices quam, sit amet fringilla leo sem vel nunc. Mauris in lacinia lacus.
Suspendisse a tincidunt lacus. Curabitur at urna sagittis, dictum ante sit amet, euismod magna. Sed rutrum massa id tortor commodo, vitae elementum turpis tempus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean purus turpis, venenatis a ullamcorper nec, tincidunt et massa. Integer posuere quam rutrum arcu vehicula imperdiet. Mauris ullamcorper quam vitae purus congue, quis euismod magna eleifend. Vestibulum semper vel augue eget tincidunt. Fusce eget justo sodales, dapibus odio eu, ultrices lorem. Duis condimentum lorem id eros commodo, in facilisis mauris scelerisque. Morbi sed auctor leo. Nullam volutpat a lacus quis pharetra. Nulla congue rutrum magna a ornare.
Aliquam in turpis accumsan, malesuada nibh ut, hendrerit justo. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Quisque sed erat nec justo posuere suscipit. Donec ut efficitur arcu, in malesuada neque. Nunc dignissim nisl massa, id vulputate nunc pretium nec. Quisque eget urna in risus suscipit ultricies. Pellentesque odio odio, tincidunt in eleifend sed, posuere a diam. Nam gravida nisl convallis semper elementum. Morbi vitae felis faucibus, vulputate orci placerat, aliquet nisi. Aliquam erat volutpat. Maecenas sagittis pulvinar purus, sed porta quam laoreet at.

152
exampleSite/content/post/migrate-from-jekyll.md Normal file
View file

@ -0,0 +1,152 @@
+++
date = "2014-03-10T00:00:00"
draft = false
tags = []
title = "Migrate to Hugo from Jekyll"
+++
## Move static content to `static`
Jekyll has a rule that any directory not starting with `_` will be copied as-is to the `_site` output. Hugo keeps all static content under `static`. You should therefore move it all there.
With Jekyll, something that looked like
▾ <root>/
▾ images/
logo.png
should become
▾ <root>/
▾ static/
▾ images/
logo.png
Additionally, you'll want any files that should reside at the root (such as `CNAME`) to be moved to `static`.
## Create your Hugo configuration file
Hugo can read your configuration as JSON, YAML or TOML. Hugo supports parameters custom configuration too. Refer to the [Hugo configuration documentation](/overview/configuration/) for details.
## Set your configuration publish folder to `_site`
The default is for Jekyll to publish to `_site` and for Hugo to publish to `public`. If, like me, you have [`_site` mapped to a git submodule on the `gh-pages` branch](http://blog.blindgaenger.net/generate_github_pages_in_a_submodule.html), you'll want to do one of two alternatives:
1. Change your submodule to point to map `gh-pages` to public instead of `_site` (recommended).
git submodule deinit _site
git rm _site
git submodule add -b gh-pages git@github.com:your-username/your-repo.git public
2. Or, change the Hugo configuration to use `_site` instead of `public`.
{
..
"publishdir": "_site",
..
}
## Convert Jekyll templates to Hugo templates
That's the bulk of the work right here. The documentation is your friend. You should refer to [Jekyll's template documentation](http://jekyllrb.com/docs/templates/) if you need to refresh your memory on how you built your blog and [Hugo's template](/layout/templates/) to learn Hugo's way.
As a single reference data point, converting my templates for [heyitsalex.net](http://heyitsalex.net/) took me no more than a few hours.
## Convert Jekyll plugins to Hugo shortcodes
Jekyll has [plugins](http://jekyllrb.com/docs/plugins/); Hugo has [shortcodes](/doc/shortcodes/). It's fairly trivial to do a port.
### Implementation
As an example, I was using a custom [`image_tag`](https://github.com/alexandre-normand/alexandre-normand/blob/74bb12036a71334fdb7dba84e073382fc06908ec/_plugins/image_tag.rb) plugin to generate figures with caption when running Jekyll. As I read about shortcodes, I found Hugo had a nice built-in shortcode that does exactly the same thing.
Jekyll's plugin:
module Jekyll
class ImageTag < Liquid::Tag
@url = nil
@caption = nil
@class = nil
@link = nil
// Patterns
IMAGE_URL_WITH_CLASS_AND_CAPTION =
IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK = /(\w+)(\s+)((https?:\/\/|\/)(\S+))(\s+)"(.*?)"(\s+)->((https?:\/\/|\/)(\S+))(\s*)/i
IMAGE_URL_WITH_CAPTION = /((https?:\/\/|\/)(\S+))(\s+)"(.*?)"/i
IMAGE_URL_WITH_CLASS = /(\w+)(\s+)((https?:\/\/|\/)(\S+))/i
IMAGE_URL = /((https?:\/\/|\/)(\S+))/i
def initialize(tag_name, markup, tokens)
super
if markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK
@class = $1
@url = $3
@caption = $7
@link = $9
elsif markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION
@class = $1
@url = $3
@caption = $7
elsif markup =~ IMAGE_URL_WITH_CAPTION
@url = $1
@caption = $5
elsif markup =~ IMAGE_URL_WITH_CLASS
@class = $1
@url = $3
elsif markup =~ IMAGE_URL
@url = $1
end
end
def render(context)
if @class
source = "<figure class='#{@class}'>"
else
source = "<figure>"
end
if @link
source += "<a href=\"#{@link}\">"
end
source += "<img src=\"#{@url}\">"
if @link
source += "</a>"
end
source += "<figcaption>#{@caption}</figcaption>" if @caption
source += "</figure>"
source
end
end
end
Liquid::Template.register_tag('image', Jekyll::ImageTag)
is written as this Hugo shortcode:
<!-- image -->
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
{{ with .Get "link"}}<a href="{{.}}">{{ end }}
<img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />
{{ if .Get "link"}}</a>{{ end }}
{{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
<figcaption>{{ if isset .Params "title" }}
{{ .Get "title" }}{{ end }}
{{ if or (.Get "caption") (.Get "attr")}}<p>
{{ .Get "caption" }}
{{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
{{ .Get "attr" }}
{{ if .Get "attrlink"}}</a> {{ end }}
</p> {{ end }}
</figcaption>
{{ end }}
</figure>
<!-- image -->
### Usage
I simply changed:
{% image full http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg "One of my favorite touristy-type photos. I secretly waited for the good light while we were "having fun" and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." ->http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/ %}
to this (this example uses a slightly extended version named `fig`, different than the built-in `figure`):
{{%/* fig class="full" src="http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg" title="One of my favorite touristy-type photos. I secretly waited for the good light while we were having fun and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." link="http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/" */%}}
As a bonus, the shortcode named parameters are, arguably, more readable.
## Finishing touches
### Fix content
Depending on the amount of customization that was done with each post with Jekyll, this step will require more or less effort. There are no hard and fast rules here except that `hugo server --watch` is your friend. Test your changes and fix errors as needed.
### Clean up
You'll want to remove the Jekyll configuration at this point. If you have anything else that isn't used, delete it.
## A practical example in a diff
[Hey, it's Alex](http://heyitsalex.net/) was migrated in less than a _father-with-kids day_ from Jekyll to Hugo. You can see all the changes (and screw-ups) by looking at this [diff](https://github.com/alexandre-normand/alexandre-normand/compare/869d69435bd2665c3fbf5b5c78d4c22759d7613a...b7f6605b1265e83b4b81495423294208cc74d610).

129
exampleSite/content/post/writing-markdown-latex.md Normal file
View file

@ -0,0 +1,129 @@
+++
date = "2016-04-20T10:00:00"
draft = false
tags = []
title = "Writing content with Markdown, LaTeX, and Shortcodes"
math = true
+++
Content can be written using [Markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet), [Hugo Shortcodes](http://gohugo.io/extras/shortcodes/), and [LaTeX math](https://en.wikibooks.org/wiki/LaTeX/Mathematics). Additionally, HTML may be used for advanced formatting.
## Sub-headings
## H2
### H3
#### H4
##### H5
###### H6
## Emphasis
Italics with *asterisks* or _underscores_.
Bold with **asterisks** or __underscores__.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough with ~~two tildes~~.
## Ordered lists
1. First item
2. Another item
## Unordered lists
* First item
* Another item
## Images
Images may be added to a page by placing them in your `static/img/` folder and referencing them using one of the following two notations:
A general image:
![alternative text for search engines](/img/screenshot.png)
A numbered figure with caption:
{{</* figure src="/img/screenshot.png" title="Figure Caption" */>}}
## Links
[I'm a link](https://www.google.com)
[A post]({{</* ref "post/hi.md" */>}})
[A publication]({{</* ref "publication/hi.md" */>}})
[A project]({{</* ref "project/hi.md" */>}})
[Another section]({{</* relref "hi.md#who" */>}})
## Blockquote
> This is a blockquote.
> This is a blockquote.
## Code highlighting
Pass the *language* of the code, such as `python`, as a parameter after three backticks:
```python
# Example of code highlighting
input_string_var = input("Enter some data: ")
print("You entered: {}".format(input_string_var))
```
Result:
```python
# Example of code highlighting
input_string_var = input("Enter some data: ")
print("You entered: {}".format(input_string_var))
```
## Twitter tweet
To include a single tweet, pass the tweet’s ID from the tweet's URL as parameter to the shortcode:
{{</* tweet 666616452582129664 */>}}
## Youtube
{{</* youtube w7Ft2ymGmfc */>}}
## Vimeo
{{</* vimeo 146022717 */>}}
## GitHub gist
{{</* gist USERNAME GIST-ID */>}}
## Speaker Deck
{{</* speakerdeck 4e8126e72d853c0060001f97 */>}}
## $\rm \LaTeX$ math
```TeX
$$\left [ – \frac{\hbar^2}{2 m} \frac{\partial^2}{\partial x^2} + V \right ] \Psi = i \hbar \frac{\partial}{\partial t} \Psi$$
```
$$\left [ – \frac{\hbar^2}{2 m} \frac{\partial^2}{\partial x^2} + V \right ] \Psi = i \hbar \frac{\partial}{\partial t} \Psi$$
## Table
Code:
```Markdown
| Command | Description |
| ------------------| ------------------------------ |
| `hugo` | Build your website. |
| `hugo serve -w` | View your website. |
```
Result:
| Command | Description |
| ------------------| ------------------------------ |
| `hugo` | Build your website. |
| `hugo serve -w` | View your website. |