1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
# Beautiful Hugo - A port of Beautiful Jekyll Theme
## Installation
$ mkdir themes
$ cd themes
$ git submodule add https://github.com/halogenica/beautifulhugo.git beautifulhugo
See [the Hugo documentation](https://gohugo.io/themes/installing/) for more information.
## Extra Features
### Responsive
This theme is designed to look great on both large-screen and small-screen (mobile) devices.
### Syntax highlighting
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/).
#### Chroma - New server side syntax highlighting
To enable Chroma, add the following to your site parameters:
```
pygmentsCodeFences = true
pygmentsUseClasses = true
```
Then, you can generate a different style by running:
```
hugo gen chromastyles --style=trac > static/css/syntax.css
```
#### Pygments - Old server side syntax highlighting
To use this feature install Pygments (`pip install Pygments`) and add the following to your site parameters:
```
pygmentsStyle = "trac"
pygmentsUseClassic = true
```
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.
#### Highlight.js - Client side syntax highlighting
```
[Params]
useHLJS = true
```
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.
### Disqus support
To use this feature, uncomment and fill out the `disqusShortname` parameter in `config.toml`.
### Staticman support
Add *staticman* configuration section in `config.toml` or `config.yaml`
Sample `config.yaml` configuration
```
staticman:
api: https://api.staticman.net/v2/entry/<USERNAME>/<REPOSITORY-BLOGNAME>/master/comments
pulls: https://github.com/<USERNAME>/<REPOSITORY-BLOGNAME>/pulls
recaptcha:
sitekey: "6LeGeTgUAAAAAAqVrfTwox1kJQFdWl-mLzKasV0v"
secret: "hsGjWtWHR4HK4pT7cUsWTArJdZDxxE2pkdg/ArwCguqYQrhuubjj3RS9C5qa8xu4cx/Y9EwHwAMEeXPCZbLR9eW1K9LshissvNcYFfC/b8KKb4deH4V1+oqJEk/JcoK6jp6Rr2nZV4rjDP9M7nunC3WR5UGwMIYb8kKhur9pAic="
```
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}"
path: "data/comments/{options.slug}"
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="
```
### Google Analytics
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`.
### Commit SHA on the footer
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 environment variables have to be set (`GIT_COMMIT_SHA` and `GIT_COMMIT_SHA_SHORT`) and parameter `commit` has to be defined in the config file:
```
[Params]
commit = "https://github.com/<username>/<siterepo>/tree/"
```
This can be achieved by running the next command prior to calling Hugo:
```
GIT_COMMIT_SHA=`git rev-parse --verify HEAD` GIT_COMMIT_SHA_SHORT=`git rev-parse --short HEAD`
```
See at [xor-gate/xor-gate.org](https://github.com/xor-gate/xor-gate.org) an example of how to add it to a continuous integration system.
### 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:
```
{{% details "This is the details title (click to expand)" %}}
This is the content (hidden until clicked).
{{% /details %}}
```
#### 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 >}}
```
## About
This is a port 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.
## License
MIT Licensed, see [LICENSE](https://github.com/halogenica/Hugo-BeautifulHugo/blob/master/LICENSE).
|
