2019-09-22 06:28:09 +00:00
# Beautiful Hugo - An adaptation of the Beautiful Jekyll theme
2016-03-08 10:43:08 +00:00
2017-02-18 21:06:04 +00:00
![Beautiful Hugo Theme Screenshot ](https://github.com/halogenica/beautifulhugo/blob/master/images/screenshot.png )
2016-03-08 10:43:08 +00:00
## Installation
$ mkdir themes
$ cd themes
2018-09-29 07:06:46 +00:00
$ git submodule add https://github.com/halogenica/beautifulhugo.git beautifulhugo
2016-03-08 10:43:08 +00:00
2018-02-21 10:32:28 +00:00
See [the Hugo documentation ](https://gohugo.io/themes/installing/ ) for more information.
2016-03-08 10:43:08 +00:00
## Extra Features
### Responsive
This theme is designed to look great on both large-screen and small-screen (mobile) devices.
### Syntax highlighting
2018-02-09 04:16:23 +00:00
This theme has support for either Hugo's lightning fast Chroma, or both server side and client side highlighting. See [the Hugo docs for more ](https://gohugo.io/content-management/syntax-highlighting/ ).
2017-11-10 18:29:44 +00:00
2018-02-09 04:16:23 +00:00
#### Chroma - New server side syntax highlighting
2017-11-10 18:29:44 +00:00
To enable Chroma, add the following to your site parameters:
```
2017-11-10 18:37:49 +00:00
pygmentsCodeFences = true
pygmentsUseClasses = true
2017-11-10 18:29:44 +00:00
```
2018-02-09 04:16:23 +00:00
Then, you can generate a different style by running:
2017-11-10 18:29:44 +00:00
```
2018-02-09 04:16:23 +00:00
hugo gen chromastyles --style=trac > static/css/syntax.css
2017-11-10 18:29:44 +00:00
```
2018-02-09 04:16:23 +00:00
#### Pygments - Old server side syntax highlighting
2016-03-08 10:43:08 +00:00
2018-02-09 04:16:23 +00:00
To use this feature install Pygments (`pip install Pygments`) and add the following to your site parameters:
2017-11-10 18:29:44 +00:00
```
2018-02-09 04:16:23 +00:00
pygmentsStyle = "trac"
2017-11-10 18:29:44 +00:00
pygmentsUseClassic = true
```
2018-11-08 07:17:19 +00:00
Pygments is mostly compatable with the newer Chroma. It is slower but has some additional theme options. I recommend Chroma over Pygments. Pygments will use `syntax.css` for highlighting, unless you also set the config `pygmentsUseClasses = false` which will generate the style code directly in the HTML file.
2016-03-08 10:43:08 +00:00
2018-02-09 04:16:23 +00:00
#### Highlight.js - Client side syntax highlighting
2018-02-19 15:40:46 +00:00
```
2018-02-09 04:16:23 +00:00
[Params]
useHLJS = true
2018-02-19 15:40:46 +00:00
```
2017-02-12 12:26:35 +00:00
2018-02-09 04:16:23 +00:00
Client side highlighting does not require pygments to be installed. This will use `highlight.min.css` instead of `syntax.css` for highlighting (effectively disabling Chroma). Highlight.js has a wider range of support for languages and themes, and an alternative highlighting engine.
2017-02-12 12:26:35 +00:00
2016-03-08 10:43:08 +00:00
### Disqus support
To use this feature, uncomment and fill out the `disqusShortname` parameter in `config.toml` .
2017-11-17 21:57:41 +00:00
### Staticman support
2018-12-16 03:02:54 +00:00
Add *Staticman* configuration section in `config.toml` or `config.yaml`
2017-11-17 21:57:41 +00:00
2018-12-16 03:02:54 +00:00
Sample `config.toml` configuration
2017-11-17 21:57:41 +00:00
```
2018-12-16 03:02:54 +00:00
[Params.staticman]
api = "https://< API-ENDPOINT > /v3/entry/{GIT-HOST}/< USERNAME > /< REPOSITORY-BLOGNAME > /master/comments"
[Params.staticman.recaptcha]
2017-11-17 21:57:41 +00:00
sitekey: "6LeGeTgUAAAAAAqVrfTwox1kJQFdWl-mLzKasV0v"
secret: "hsGjWtWHR4HK4pT7cUsWTArJdZDxxE2pkdg/ArwCguqYQrhuubjj3RS9C5qa8xu4cx/Y9EwHwAMEeXPCZbLR9eW1K9LshissvNcYFfC/b8KKb4deH4V1+oqJEk/JcoK6jp6Rr2nZV4rjDP9M7nunC3WR5UGwMIYb8kKhur9pAic="
```
2018-12-16 03:02:54 +00:00
Note: The public `API-ENDPOINT` https://staticman.net is currently hitting its API limit, so one may use other API instances to provide Staticman comment service.
The section `[Params.staticman.recaptcha]` is *optional* . To add reCAPTCHA to your site, you have to replace the default values with your own ones (to be obtained from Google.) The site `secret` has to be encrypted with
https://< API-ENDPOINT > /v3/encrypt/< SITE-SECRET >
2017-11-18 05:00:33 +00:00
You must also configure the `staticman.yml` in you blog website.
```
comments:
allowedFields: ["name", "email", "website", "comment"]
branch : "master"
commitMessage : "New comment in {options.slug}"
2017-11-18 06:59:53 +00:00
path: "data/comments/{options.slug}"
2017-11-18 05:00:33 +00:00
filename : "comment-{@timestamp}"
format : "yaml"
moderation : true
requiredFields : ['name', 'email', 'comment']
transforms:
email : md5
generatedFields:
date:
type : "date"
options:
format : "iso8601"
reCaptcha:
enabled: true
siteKey: "6LeGeTgUAAAAAAqVrfTwox1kJQFdWl-mLzKasV0v"
secret: "hsGjWtWHR4HK4pT7cUsWTArJdZDxxE2pkdg/ArwCguqYQrhuubjj3RS9C5qa8xu4cx/Y9EwHwAMEeXPCZbLR9eW1K9LshissvNcYFfC/b8KKb4deH4V1+oqJEk/JcoK6jp6Rr2nZV4rjDP9M7nunC3WR5UGwMIYb8kKhur9pAic="
```
2018-12-16 03:02:54 +00:00
If you *don't* have the section `[Params.staticman]` in `config.toml` , you *won't* need the section `reCaptcha` in `staticman.yml`
2017-11-18 05:00:33 +00:00
2016-03-08 10:43:08 +00:00
### Google Analytics
2018-02-21 10:32:28 +00:00
To add Google Analytics, simply sign up to [Google Analytics ](https://www.google.com/analytics/ ) to obtain your Google Tracking ID, and add this tracking ID to the `googleAnalytics` parameter in `config.toml` .
2016-03-08 10:43:08 +00:00
2017-02-06 11:15:53 +00:00
### Commit SHA on the footer
2018-12-16 09:49:37 +00:00
If the source of your site is in a Git repo, the SHA corresponding to the commit the site is built from can be shown on the footer. To do so, two site parameters `commit` has to be defined in the config file `config.toml` :
2017-02-06 11:15:53 +00:00
```
2018-12-16 09:49:37 +00:00
enableGitInfo = true
2017-02-06 11:15:53 +00:00
[Params]
commit = "https://github.com/< username > /< siterepo > /tree/"
```
2018-12-16 09:49:37 +00:00
See at [vincenttam/vincenttam.gitlab.io ](https://gitlab.com/vincenttam/vincenttam.gitlab.io ) for an example of how to add it to a continuous integration system.
2019-06-12 14:29:03 +00:00
### Multilingual
2019-06-12 14:39:28 +00:00
To allow Beautiful Hugo to go multilingual, you need to define the languages
2019-06-12 14:37:28 +00:00
you want to use inside the `languages` parameter on `config.toml` file, also
redefining the content dir for each one. Check the `i18n/` folder to see all
languages available.
2019-06-12 14:29:03 +00:00
```toml
[languages]
[languages.en]
2019-06-12 14:37:28 +00:00
contentDir = "content/en" # English
2019-06-12 14:29:03 +00:00
[languages.ja]
2019-06-12 14:37:28 +00:00
contentDir = "content/ja" # Japanese
2019-06-12 14:29:03 +00:00
[languages.br]
2019-06-12 14:37:28 +00:00
contentDir = "content/br" # Brazilian Portuguese
2019-06-12 14:29:03 +00:00
```
Now you just need to create a subdir within the `content/` folder for each
2019-06-12 14:39:28 +00:00
language and just put stuff inside `page/` and `post/` regular directories.
2019-06-12 14:29:03 +00:00
```
content/ content/ content/
2019-06-12 14:42:49 +00:00
└── en/ └── br/ └── ja/
├── page/ ├── page/ ├── page/
└── post/ └── post/ └── post/
2019-06-12 14:29:03 +00:00
```
2018-01-04 14:43:42 +00:00
### Extra shortcodes
There are two extra shortcodes provided (along with the customized figure shortcode):
#### Details
This simply adds the html5 detail attribute, supported on all *modern* browsers. Use it like this:
```
2020-01-15 01:38:57 +00:00
{{< details " This is the details title ( click to expand ) " > }}
2018-01-04 14:43:42 +00:00
This is the content (hidden until clicked).
2020-01-15 01:38:57 +00:00
{{< / details > }}
2018-01-04 14:43:42 +00:00
```
#### Split
This adds a two column side-by-side environment (will turn into 1 col for narrow devices):
```
{{< columns > }}
This is column 1.
{{< column > }}
This is column 2.
{{< endcolumn > }}
```
2016-03-08 10:43:08 +00:00
## About
2019-09-22 06:28:09 +00:00
This is an adaptation of the Jekyll theme [Beautiful Jekyll ](https://deanattali.com/beautiful-jekyll/ ) by [Dean Attali ](https://deanattali.com/aboutme#contact ). It supports most of the features of the original theme, and many new features. It has diverged from the Jekyll theme over time, with years of community updates.
2016-03-08 10:43:08 +00:00
## License
2017-02-18 21:06:04 +00:00
MIT Licensed, see [LICENSE ](https://github.com/halogenica/Hugo-BeautifulHugo/blob/master/LICENSE ).