mirror of https://github.com/theNewDynamic/gohugo-theme-ananke.git
[!WARNING]
Parts of this documentation, such as the sections related to the production environment, are currently a work in progress. This is due to recent changes and updates in the theme. We are actively working on providing complete and up-to-date guidance. Thank you for your patience.
The 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.
Features
toc: true in post parameter)Also includes examples of Hugo Features or Functions:
withfirstaftersortwherelenge (greater than or equal to).Site.Params.mainSections to avoid hard-coding "blog," etc. [release note]This 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.
Dive into our documentation on installing the theme as GoHugo Module or Git Submodule. The official setup guide of GoHugo covers the installation of the theme as Git Submodule.
After installing the theme successfully it requires a just a few more steps to get your site running.
Take a look inside the exampleSite folder of this theme. You'll find a file called config.toml. To use it, copy the config.toml in the root folder of your Hugo site. Feel free to change the strings in this theme.
To enable comments, add following to your config file:
toml [services.disqus] shortname = 'YOURSHORTNAME'
toml [params] commentoEnable = true
For any page or post you can add a featured image by including the local path in front matter (see content in the exampleSite/content/en/_readme.md file for examples): featured_image = '/images/gohugo-default-sample-hero-image.jpg'
If user is using Page Resources, the theme will try and match the featured_image from with a page resource of type image and use its relative permalink. If no featured_image is set, the theme will look for a Page Resource of type image whose filepath includes either cover or feature
If you would like to hide the header text on the featured image on a page, set omit_header_text to true. See exampleSite/content/en/contact.md for an example.
You 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 library site, and preface it with "bg-"
example: background_color_class = "bg-blue" or background_color_class = "bg-gray"
The default fitting and alignment for the featured image is cover bg-top, but can be changed using the featured_image_class. Choose a fitting and alignment style for the featured image using Tachyons classes such as "cover|contain" for fitting and "bg-top|bg-center|bg-bottom" for alignment.
example: featured_image_class = "cover bg-center" or featured_image_class = "contain bg-top"
The default cover backdrop for the featured image is bg-black-60, but can be changed using the cover_dimming_class. Choose a color dimming class for the page or site header from any on the Tachyons library site, preface it with "bg-" and add the value such as "-X0" where X is in [1,9]
example: cover_dimming_class = "bg-black-20" or cover_dimming_class = "bg-white-40"
This 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 as proxy to send the actual email. Each month, visitors can send you up to fifty emails without incurring extra charges. Visit the Formspree site to get the "action" link and add it to your shortcode like this:
{{< form-contact action="https://formspree.io/your@email.com" >}}
The homepage and other areas of the site use a read more link on the element. You can customize the copy of this link to make it more descriptive with the parameter read_more_copy available as a site and front matter parameter.
# config.toml
# Globally for all pages:
[params]
read_more_copy = "Read more about this entry"
# Just for french
[languages.fr]
name = "Français"
weight = 2
[languages.fr.params]
read_more_copy = "En savoir plus à ce sujet"
Using front matter and cascade, this can be customized for a whole section, or just for one page.
# content/posts/tower-bridge-london.md
title: The Tower Bridge of London
read_more_copy: Read more about this bridge
Read the documentation for social media follow and social share in our wiki.
This project uses Font Awesome brand icons, which are licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). For more information, visit Font Awesome.
If the theme is run in production, pages will be indexed by search engines. To prevent indexing on some given pages, add private: true to its Front Matter.
The 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:
[params]
body_classes = "avenir bg-near-white"
which will give you a body class like this:
<body class="avenir bg-near-white">
note: The body_classes parameter will not change the font used in post content. To do this, you must use the post_content_classes parameter.
You can find a list of available typefaces here.
And a list of background colors here.
n.b. in future versions we will likely separate the typeface and other body classes.
Ananke stylesheet is built with Hugo Pipes's Asset Bundling alone to maximize compatibility. The theme simply bundles its several files into one minified and fingerprinted (in production) CSS file.
Ananke uses Tachyons.io utility class library.
WARNING: Pending resolution of this discussion, Custom CSS only works with Hugo Extended
In order to complement the default CSS with your own, you can add custom css files to the project.
assets/ananke/css directory to your project and add the file(s) in it.custom_css key in your site's parameter. The path referenced in the parameter should be relative to the assets/ananke/css folder.The css files will be added in their registered order to final main.css file.
For example, if your css files are assets/ananke/css/custom.css and assets/ananke/special.css then add the following to the config file:
[params]
custom_css = ["custom.css","special.css"]
IMPORTANT: Files registered through the custom_css array, while unlimited in number, must be of the same type (Ex: all scss or all css)
Note on retrocompatibiliy for custom css: If the files registered through the custom_css setting are not found in assets/ananke/css the theme will expect them to live at the given path relative to the static directory and load them as <link> requests.
If 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.
Some 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.
You 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:
[params]
site_logo = "img/logo.svg"
You can set the font color of the main content both globally and on individual pages:
Globally:
Set the text_color param in the config.toml file.
[params]
text_color = "green"
Individual Page (prioritized over global):
Set the text_color param in a page's markdown file front matter.
note: The value of text_color must be a valid tachyons color class. A list can be found here.
Dates of blog posts and single pages are rendered with the default date format commonly used in the USA and Canada. It is possible to specify a different format.
[params]
date_format = "2. January 2006"
With hugo 0.87.0 and above, you can also use predefined layout, like :date_full, and it will output localized dates or times.
See hugo's documentation of the time.Format function for more details.
When you want to publish content that is already published on a different site. You need to reference a canonical url of the original content.
By defining the canonicalUrl in the front matter definition the canonical url is set in the headers.
canonicalUrl: https://mydomain.com/path-to-the-oringinal-content/
In order to see your site in action, run Hugo's built-in local server.
hugo server
Now enter localhost:1313 in the address bar of your browser.
If you find a bug feel free to use the issue tracker to let me know. If you are having issues setting up your site with the theme, or have an idea for a feature, please use the discussions for support.
Join me on my ananke-theme Discord channel for direct support.
Find older changelog entries in .github/changelog-old.md
Copyright (c) 2016-2024 Bud Parr
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
