1# Ananke, A theme for [Hugo](http://gohugo.io/), a framework for building websites.
2
3The intent of this theme is to provide a solid starting place for Hugo sites with basic features and include best practices for performance, accessibility, and rapid development.
4
5
6
7[DEMO](https://gohugo-ananke-theme-demo.netlify.com/)
8
9Features
10
11- Responsive
12- Accessible
13- Contact form
14- Custom Robots.txt (changes values based on environment)
15- Internal templates for meta data, google analytics, and DISQUS or COMMENTO comments
16- RSS Discovery
17- Table of Contents (must declare `toc: true` in post parameter)
18- Stackbit configuration ([Stackbit](https://www.stackbit.com))
19
20Also includes examples of Hugo Features or Functions:
21
22- Pagination (internal template)
23- Taxonomies
24- Archetypes
25- Custom shortcode
26- Related content
27- Hugo built-in menu
28- i18n
29- `with`
30- `HUGO_ENV`
31- `first`
32- `after`
33- `sort`
34- Site LanguageCode
35- `where`
36- Content Views
37- Partials
38- Template layouts (type "post" uses a special list template, single template, and a content view)
39- Tags
40- `len`
41- Conditionals
42- `ge` (greater than or equal to)
43- `.Site.Params.mainSections` to avoid hard-coding "blog," etc. [[release note](https://github.com/spf13/hugo/blob/66ec6305f6cb450ddf9c489854146bac02f7dca1/docs/content/meta/release-notes.md#enhancements)]
44
45
46This theme uses the "Tachyons" CSS library. This will allow you to manipulate the design of the theme by changing class names in HTML without touching the original CSS files. For more information see the [Tachyons website](http://tachyons.io/).
47
48
49
50## Installation
51
52Inside the folder of your Hugo site run:
53
54 $ git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
55
56For more information read the official [setup guide](//gohugo.io/overview/installing/) of Hugo.
57
58
59
60## Getting started
61
62After installing the theme successfully it requires a just a few more steps to get your site running.
63
64
65### The config file
66
67Take a look inside the [`exampleSite`](https://github.com/budparr/gohugo-theme-ananke/tree/master/exampleSite) folder of this theme. You'll find a file called [`config.toml`](https://github.com/budparr/gohugo-theme-ananke/blob/master/exampleSite/config.toml). To use it, copy the [`config.toml`](https://github.com/budparr/gohugo-theme-ananke/blob/master/exampleSite/config.toml) in the root folder of your Hugo site. Feel free to change the strings in this theme.
68
69You may need to delete the line: `themesDir = "../.."`
70
71
72### Add comments
73
74To enable comments, add following to your config file:
75
76- DISQUS: `disqusShortname = YOURSHORTNAME`
77- COMMENTO:
78 ```
79 [params]
80 commentoEnable = true
81 ```
82
83### Change the hero background
84
85For any page or post you can add a featured image by including the local path in front matter (see content in the `exampleSite/content/_readme.md` file for examples): `featured_image: '/images/gohugo-default-sample-hero-image.jpg'`
86
87If you would like to hide the header text on the featured image on a page, set `omit_header_text` to `true`. See `exampleSite/content/contact.md` for an example.
88
89You don't need an image though. The default background color is black, but you can change the color, by changing the default color class in the config.toml file. Choose a background color from any on the [Tachyons](http://tachyons.io/docs/themes/skins/) library site, and preface it with "bg-"
90
91example: `background_color_class = "bg-blue"` or `background_color_class = "bg-gray"`
92
93
94
95### Activate the contact form
96
97This theme includes a shortcode for a contact form that you can add to any page (there is an example on the contact page in the exampleSite folder). One option is to use [formspree.io](//formspree.io/) as proxy to send the actual email. Each month, visitors can send you up to one thousand emails without incurring extra charges. Visit the Formspree site to get the "action" link and add it to your shortcode like this:
98
99```
100{{< form-contact action="https://formspree.io/your@email.com" >}}
101```
102
103### Update font or body classes
104
105The theme is set, by default, to use a near-white background color and the "Avenir" or serif typeface. You can change these in your config file with the `body_classes` parameter, like this:
106
107```
108[params]
109 body_classes = "avenir bg-near-white"
110```
111
112which will give you a body class like this:
113
114```
115<body class="avenir bg-near-white">
116```
117
118note: The `body_classes` parameter will not change the font used in post content. To do this, you must use the `post_content_classes` parameter.
119
120You can find a list of available typefaces [here](https://github.com/tachyons-css/tachyons/blob/v4.7.0/src/_font-family.css).
121
122And a list of background colors [here](https://github.com/tachyons-css/tachyons/blob/v4.7.0/src/_skins.css#L96).
123
124
125_n.b. in future versions we will likely separate the typeface and other body classes._
126
127
128### Custom CSS
129
130You can override the built-in css by using your own. Just put your own css files in the `static` directory of your website (the one in the theme directory also works but is not recommended) and modify the `custom_css` parameter in your config file. The path referenced in the parameter should be relative to the `static` folder. These css files will be added through the `header` partial after the built-in css file.
131
132For example, if your css files are `static/css/custom.css` and `static/css/custom2.css` then add the following to the config file:
133
134```
135 [params]
136 custom_css = ["css/custom.css","css/custom2.css"]
137```
138
139### Show Reading Time and Word Count
140
141If you add a key of `show_reading_time` true to either the Config Params, a page or section's front matter, articles will show the reading time and word count.
142
143
144### Adding Scripts to the Page Head
145
146Some scripts need to be added within the page head. To add your own scripts to the page head, simply insert them into the `head-additions.html` partial located in the `layouts/partials` folder.
147
148
149### Logo
150
151You can replace the title of your site in the top left corner of each page with your own logo. To do that put your own logo into the `static` directory of your website, and add the `site_logo` parameter to the site params in your config file. For example:
152
153```
154[params]
155 site_logo = "img/logo.svg"
156```
157
158
159### Nearly finished
160
161In order to see your site in action, run Hugo's built-in local server.
162
163`$ hugo server`
164
165Now enter [`localhost:1313`](http://localhost:1313/) in the address bar of your browser.
166
167## Production
168
169To run in production (e.g. to have Google Analytics show up), run `HUGO_ENV=production` before your build command. For example:
170
171```
172HUGO_ENV=production hugo
173```
174
175Note: The above command will not work on Windows. If you are running a Windows OS, use the below command:
176
177```
178set HUGO_ENV=production
179hugo
180```
181
182## Contributing
183
184If you find a bug or have an idea for a feature, feel free to use the [issue tracker](https://github.com/budparr/gohugo-theme-ananke/issues) to let me know.
185
186
187
188
189TODO:
190
191- fix hard-coded link to [section](https://github.com/budparr/gohugo-theme-ananke/blob/master/layouts/index.html#L32)