|
| 1 | +# Beautiful Hugo - An adaptation of the Beautiful Jekyll theme |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | +## Live demo |
| 6 | + |
| 7 | +See https://hugo-theme-beautifulhugo.netlify.app/ |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +Install Hugo and create a new site. See [the Hugo documentation](https://gohugo.io/getting-started/quick-start/) for details. |
| 12 | + |
| 13 | +### Git Submodule |
| 14 | + |
| 15 | +Add Beautifulhugo as git submodule: |
| 16 | + |
| 17 | + $ git submodule add https://github.com/halogenica/beautifulhugo.git themes/beautifulhugo |
| 18 | + |
| 19 | +### Hugo module |
| 20 | + |
| 21 | +Initialize your site as hugo module: |
| 22 | + |
| 23 | + $ hugo mod init github.com/USERNAME/SITENAME |
| 24 | + |
| 25 | +Add Beautifulhugo module as a dependency of your site: |
| 26 | + |
| 27 | + $ hugo mod get github.com/halogenica/beautifulhugo |
| 28 | + |
| 29 | +### Site preview |
| 30 | + |
| 31 | +Copy the content of `exampleSite` at the root of your project: |
| 32 | + |
| 33 | + cp -r themes/beautifulhugo/exampleSite/* . -iv |
| 34 | + |
| 35 | +If you installed Beautifulhugo as hugo module, set your theme in your config file (hugo.toml): |
| 36 | + |
| 37 | + [[module.imports]] |
| 38 | + path = "github.com/halogenica/beautifulhugo" |
| 39 | + |
| 40 | +Start Hugo: |
| 41 | + |
| 42 | + hugo serve |
| 43 | + |
| 44 | +## Extra Features |
| 45 | + |
| 46 | +### Responsive |
| 47 | + |
| 48 | +This theme is designed to look great on both large-screen and small-screen (mobile) devices. |
| 49 | + |
| 50 | +### Syntax highlighting |
| 51 | + |
| 52 | +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/). |
| 53 | + |
| 54 | +#### Chroma - New server side syntax highlighting |
| 55 | + |
| 56 | +To enable Chroma, add the following to your site parameters: |
| 57 | + |
| 58 | +``` |
| 59 | +pygmentsCodeFences = true |
| 60 | +pygmentsUseClasses = true |
| 61 | +``` |
| 62 | + |
| 63 | +Then, you can generate a different style by running: |
| 64 | + |
| 65 | +``` |
| 66 | +hugo gen chromastyles --style=trac > static/css/syntax.css |
| 67 | +``` |
| 68 | + |
| 69 | +#### Pygments - Old server side syntax highlighting |
| 70 | + |
| 71 | +To use this feature install Pygments (`pip install Pygments`) and add the following to your site parameters: |
| 72 | + |
| 73 | +``` |
| 74 | +pygmentsStyle = "trac" |
| 75 | +pygmentsUseClassic = true |
| 76 | +``` |
| 77 | + |
| 78 | +Pygments is mostly compatible 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. |
| 79 | + |
| 80 | +#### Highlight.js - Client side syntax highlighting |
| 81 | +``` |
| 82 | +[Params] |
| 83 | + useHLJS = true |
| 84 | +``` |
| 85 | + |
| 86 | +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. |
| 87 | + |
| 88 | +### Disqus support |
| 89 | + |
| 90 | +To use this feature add your disqus shortname to the hugo.toml file like this: |
| 91 | + |
| 92 | +```toml |
| 93 | +[services] |
| 94 | + [services.disqus] |
| 95 | + shortname = '' |
| 96 | +``` |
| 97 | + |
| 98 | +For further reference see [hugo config](https://gohugo.io/methods/site/config/) |
| 99 | + |
| 100 | +### Staticman support |
| 101 | + |
| 102 | +Add *Staticman* configuration section in `hugo.toml` or `hugo.yaml` |
| 103 | + |
| 104 | +Sample `hugo.toml` configuration |
| 105 | + |
| 106 | +``` |
| 107 | +[Params.staticman] |
| 108 | + api = "https://<API-ENDPOINT>/v3/entry/{GIT-HOST}/<USERNAME>/<REPOSITORY-BLOGNAME>/master/comments" |
| 109 | +[Params.staticman.recaptcha] |
| 110 | + sitekey: "6LeGeTgUAAAAAAqVrfTwox1kJQFdWl-mLzKasV0v" |
| 111 | + secret: "hsGjWtWHR4HK4pT7cUsWTArJdZDxxE2pkdg/ArwCguqYQrhuubjj3RS9C5qa8xu4cx/Y9EwHwAMEeXPCZbLR9eW1K9LshissvNcYFfC/b8KKb4deH4V1+oqJEk/JcoK6jp6Rr2nZV4rjDP9M7nunC3WR5UGwMIYb8kKhur9pAic=" |
| 112 | +``` |
| 113 | + |
| 114 | +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. |
| 115 | + |
| 116 | +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 |
| 117 | + |
| 118 | + https://<API-ENDPOINT>/v3/encrypt/<SITE-SECRET> |
| 119 | + |
| 120 | +You must also configure the `staticman.yml` in you blog website. |
| 121 | + |
| 122 | +``` |
| 123 | +comments: |
| 124 | + allowedFields: ["name", "email", "website", "comment"] |
| 125 | + branch : "master" |
| 126 | + commitMessage : "New comment in {options.slug}" |
| 127 | + path: "data/comments/{options.slug}" |
| 128 | + filename : "comment-{@timestamp}" |
| 129 | + format : "yaml" |
| 130 | + moderation : true |
| 131 | + requiredFields : ['name', 'email', 'comment'] |
| 132 | + transforms: |
| 133 | + email : md5 |
| 134 | + generatedFields: |
| 135 | + date: |
| 136 | + type : "date" |
| 137 | + options: |
| 138 | + format : "iso8601" |
| 139 | + reCaptcha: |
| 140 | + enabled: true |
| 141 | + siteKey: "6LeGeTgUAAAAAAqVrfTwox1kJQFdWl-mLzKasV0v" |
| 142 | + secret: "hsGjWtWHR4HK4pT7cUsWTArJdZDxxE2pkdg/ArwCguqYQrhuubjj3RS9C5qa8xu4cx/Y9EwHwAMEeXPCZbLR9eW1K9LshissvNcYFfC/b8KKb4deH4V1+oqJEk/JcoK6jp6Rr2nZV4rjDP9M7nunC3WR5UGwMIYb8kKhur9pAic=" |
| 143 | +``` |
| 144 | + |
| 145 | +If you *don't* have the section `[Params.staticman]` in `hugo.toml`, you *won't* need the section `reCaptcha` in `staticman.yml` |
| 146 | + |
| 147 | +### Site Disclaimer |
| 148 | + |
| 149 | +If you need to put a Disclaimer on your website (e.g. "My views are my own and not my employer's"), you can do so via the following: |
| 150 | + |
| 151 | +* Uncomment and edit the `disclaimerText` parameter in `hugo.toml`. |
| 152 | +* If you need to adjust the disclaimer's styling, modify the declarations within the `footer div.disclaimer` selector in `static/css/main.css`. |
| 153 | + |
| 154 | +> The code for the disclaimer text is in `layouts/partials/footer.html`. Moving this code block to another partial file (or relocating it within `footer.html`) will require changes to the css selector in `main.css` as well. |
| 155 | +
|
| 156 | +### Google Analytics |
| 157 | + |
| 158 | +Sign up to [Google Analytics](https://www.google.com/analytics/) to obtain your Google Tracking ID. |
| 159 | + |
| 160 | +To use this feature add your Google Analytics ID to the hugo.toml file like this: |
| 161 | + |
| 162 | +``` |
| 163 | +[services] |
| 164 | + [services.googleAnalytics] |
| 165 | + id = '' |
| 166 | +``` |
| 167 | + |
| 168 | +Note that the Google Analytics tracking code will only be inserted into the page when the site isn't served on Hugo's built-in server, to prevent tracking from local testing environments. |
| 169 | + |
| 170 | +### Commit SHA on the footer |
| 171 | + |
| 172 | +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 `hugo.toml`: |
| 173 | + |
| 174 | +``` |
| 175 | +enableGitInfo = true |
| 176 | +[Params] |
| 177 | + commit = "https://github.com/<username>/<siterepo>/tree/" |
| 178 | +``` |
| 179 | + |
| 180 | +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. |
| 181 | + |
| 182 | +### Multilingual |
| 183 | + |
| 184 | +To allow Beautiful Hugo to go multilingual, you need to define the languages |
| 185 | +you want to use inside the `languages` parameter on `hugo.toml` file, also |
| 186 | +redefining the content dir for each one. Check the `i18n/` folder to see all |
| 187 | +languages available. |
| 188 | + |
| 189 | +```toml |
| 190 | +[languages] |
| 191 | + [languages.en] |
| 192 | + contentDir = "content/en" # English |
| 193 | + [languages.ja] |
| 194 | + contentDir = "content/ja" # Japanese |
| 195 | + [languages.br] |
| 196 | + contentDir = "content/br" # Brazilian Portuguese |
| 197 | +``` |
| 198 | + |
| 199 | +Now you just need to create a subdir within the `content/` folder for each |
| 200 | +language and just put stuff inside `page/` and `post/` regular directories. |
| 201 | +``` |
| 202 | +content/ content/ content/ |
| 203 | +└── en/ └── br/ └── ja/ |
| 204 | + ├── page/ ├── page/ ├── page/ |
| 205 | + └── post/ └── post/ └── post/ |
| 206 | +
|
| 207 | +``` |
| 208 | + |
| 209 | +### Self Hosted assets for GDPR / EU-DSGVO compliance |
| 210 | + |
| 211 | +With default settings, visiting to a website using Beautifulhugo connects also to remote services like google fonts or jsdelivr to embed fonts, js and other assets. |
| 212 | + |
| 213 | +To avoid this, set the following param in hugo.toml: |
| 214 | + |
| 215 | +``` |
| 216 | +[Params] |
| 217 | + selfHosted = true |
| 218 | +``` |
| 219 | + |
| 220 | +### Extra shortcodes |
| 221 | + |
| 222 | +There are two extra shortcodes provided (along with the customized figure shortcode): |
| 223 | + |
| 224 | +#### Details |
| 225 | + |
| 226 | +This simply adds the html5 detail attribute, supported on all *modern* browsers. Use it like this: |
| 227 | + |
| 228 | +``` |
| 229 | +{{< details "This is the details title (click to expand)" >}} |
| 230 | +This is the content (hidden until clicked). |
| 231 | +{{< /details >}} |
| 232 | +``` |
| 233 | + |
| 234 | +#### Split |
| 235 | + |
| 236 | +This adds a two column side-by-side environment (will turn into 1 col for narrow devices): |
| 237 | + |
| 238 | +``` |
| 239 | +{{< columns >}} |
| 240 | +This is column 1. |
| 241 | +{{< column >}} |
| 242 | +This is column 2. |
| 243 | +{{< endcolumns >}} |
| 244 | +``` |
| 245 | + |
| 246 | +### Social Media Icons |
| 247 | + |
| 248 | +In order to show social media icons in the footer, add a section like this to your `hugo.yaml` or `hugo.toml`. You can see the full list of supported social media sites in `data/beautifulhugo/social.toml`. |
| 249 | + |
| 250 | +```yaml |
| 251 | +author: |
| 252 | + name: "Author Name" |
| 253 | + website: "https://example.com" |
| 254 | + github: halogenica/beautifulhugo |
| 255 | + twitter: username |
| 256 | + discord: 96VAXXvjCB |
| 257 | + ... |
| 258 | +``` |
| 259 | + |
| 260 | +```toml |
| 261 | +[Params.author] |
| 262 | + name = "Author Name" |
| 263 | + website = "https://example.com" |
| 264 | + github = "halogenica/beautifulhugo" |
| 265 | + twitter = "username" |
| 266 | + discord = "96VAXXvjCB" |
| 267 | + ... |
| 268 | +``` |
| 269 | + |
| 270 | +## About |
| 271 | + |
| 272 | +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. |
| 273 | + |
| 274 | +## License |
| 275 | + |
| 276 | +MIT Licensed, see [LICENSE](https://github.com/halogenica/Hugo-BeautifulHugo/blob/master/LICENSE). |
0 commit comments