From 50a748552fbfa399dcb95b98623297ea48da5e50 Mon Sep 17 00:00:00 2001
From: Patrick Kollitsch <davidsneighbourdev+gh@gmail.com>
Date: Mon, 06 Apr 2026 05:50:04 +0000
Subject: [PATCH] docs: cleanup documentation and readme files
---
/dev/null | 8 -
CONTRIBUTING.md | 84 ++++++-----
docs/getting-started.md | 211 ++++-------------------------
site/README.md | 18 ++
archetypes/default.md | 4
README.md | 87 ++++-------
6 files changed, 134 insertions(+), 278 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 864ee24..22efe92 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,57 +1,67 @@
# Contributing to Ananke
-Thank you for your interest in improving the Ananke Hugo theme! Contributions of all kinds help keep the theme useful for the community. This document explains how to get started, what kinds of contributions we welcome, and how to collaborate effectively.
+Thanks for helping improve Ananke. This document describes the current contribution workflow for this repository.
-## Types of Contributions
+## Ways to Contribute
-We welcome many forms of help, including:
+* Report bugs
+* Suggest enhancements
+* Improve documentation
+* Improve templates, styles, or assets
+* Improve translations in `i18n/*.toml`
-* **Bug reports**: Tell us about problems you encounter and steps to reproduce them.
-* **Feature requests**: Propose new capabilities or improvements to existing features.
-* **Code contributions**: Fix bugs, add features, or improve build tooling.
-* **Documentation updates**: Improve explanations, examples, or add missing details.
-* **Translations**: Enhance or correct strings in the `i18n/` directory.
+## Before You Start
-## Getting Started
+1. Use a compatible Hugo version (see [`config/_default/hugo.toml`](https://github.com/theNewDynamic/gohugo-theme-ananke/blob/main/config/_default/module.toml](https://github.com/theNewDynamic/gohugo-theme-ananke/blob/main/config/_default/module.toml)) for the current state).
+2. Install dependencies:
-1. Install [Hugo](https://gohugo.io/getting-started/installing/) extended version and ensure `hugo version` matches the version in `config/_default/hugo.toml` > `min_version`.
-2. Install Node.js dependencies for asset building: `npm install`.
-3. Run the development server with `hugo server` and open the served URL.
+ ```bash
+ npm install
+ ```
-## Contribution Process
+3. Run a local preview via `npm run` instead of just calling `hugo server`:
-### Reporting Issues and Requesting Features
+ ```bash
+ npm run server
+ ```
-* Use [GitHub Issues](https://github.com/theNewDynamic/gohugo-theme-ananke/issues) to report bugs or [GitHub Discussions](https://github.com/theNewDynamic/gohugo-theme-ananke/discussions) to suggest enhancements.
-* Include clear steps to reproduce, expected versus actual behavior, and environment details (e.g., Hugo version (the output of `hugo version`), OS, browser).
-* Share screenshots or logs when relevant, but keep in mind to avoid sensitive information in public issues places.
+ This runs the documentation site from `site/` using contents from `docs/` with local configuration.
-### Submitting Code Changes
+## Reporting Bugs and Requesting Features
-* Fork the repository and create a descriptive branch name (e.g., `fix/menu-alignment`).
-* Keep changes focused and prefer smaller, reviewable pull requests.
-* Create one pull request per logical change.
-* Follow the existing code style and structure; mirror patterns you see in `layouts/`, `assets/`, and `static/` (this will be updated with a link to coding standards as soon as we have them).
-* Add or update documentation for any user-facing change.
-* Write or update tests where applicable, then run them locally before opening a PR. Common commands:
- * `npm test` for JavaScript-related checks.
- * `hugo server` and `hugo` to verify the site builds without errors.
-* Ensure commits have clear messages describing the intent. If your PR addresses an issue, reference it in the description (e.g., "Fixes #123").
+* Open bugs in [GitHub Issues](https://github.com/theNewDynamic/gohugo-theme-ananke/issues).
+* Start feature or idea discussions in [GitHub Discussions](https://github.com/theNewDynamic/gohugo-theme-ananke/discussions).
+* Include clear reproduction steps, expected behavior, actual behavior, and versions (`hugo version`, OS, browser if relevant).
-### Documentation Contributions
+## Pull Request Workflow
-* Update markdown files in `README.md`, `config/`, or relevant component docs to reflect your changes.
-* Keep examples minimal but complete, and prefer showing the final output or screenshot references when helpful.
+1. Fork the repository and create a focused branch.
+2. Keep the change set small and cohesive (which means, DO NOT introduce multiple changes in a single PR).
+3. Update docs for all user-facing changes.
+4. Run quality checks locally:
-## Code of Conduct
+ ```bash
+ npm run lint:markdown
+ ```
-Please review and follow the principles in the project's Code of Conduct (to be implemented). If you see behavior that violates these guidelines, report it through the project issue tracker or contact a maintainer privately.
+5. If your change affects behavior, validate with Hugo locally (for example `hugo` or `hugo server` in the relevant project).
+6. Open a pull request with:
+ * a clear summary,
+ * motivation/context,
+ * screenshots when UI/visual output changes,
+ * linked issues (for example: `Fixes #123`).
-## Communication and Support
+## Documentation Contributions
-* For general questions, open a discussion or issue on the repository.
-* For security concerns, please avoid public issues and reach out to a maintainer directly when possible.
+Documentation lives in multiple places:
-## Licensing
+* Main project overview: `README.md`
+* Contributor docs: `CONTRIBUTING.md`
+* Theme docs content: `docs/`
+* Docs site wrapper: `site/`
-By contributing, you agree that your contributions will be licensed under the same terms as the project, as detailed in [LICENSE.md](LICENSE.md).
+Please keep links relative where possible and remove stale references when updating pages.
+
+## License
+
+By contributing, you agree that your contributions are provided under the repository license in [LICENSE.md](LICENSE.md).
diff --git a/README.md b/README.md
index 2ee5fbd..7ef7d41 100644
--- a/README.md
+++ b/README.md
@@ -1,71 +1,52 @@
-# Ananke, a starter theme for GoHugo
+# Ananke Theme for Hugo
-> [!WARNING]
-> If you are experiencing issues with recent Hugo versions please check the [Discussion about the layout changes](https://github.com/theNewDynamic/gohugo-theme-ananke/discussions/886) and add your issues there. Thank you!
+Ananke is a flexible, production-ready starter theme for [Hugo](https://gohugo.io/) focused on accessibility, performance, and maintainable defaults.
-The intent of this theme is to provide a solid starting place for [GoHugo](https://gohugo.io/) sites with basic features and include best practices for performance, accessibility, and rapid development.
+
-
+* Demo: [ananke-theme.netlify.app](https://ananke-theme.netlify.app/)
+* Documentation: [docs directory](https://github.com/theNewDynamic/gohugo-theme-ananke/tree/main/docs)
+* Changelog: [CHANGELOG.md](CHANGELOG.md)
-[DEMO](https://ananke-theme.netlify.app/)
+## Features
-Features
-
-* Responsive
-* Accessible
-* Contact form
-* Custom Robots.txt (changes values based on environment)
-* Internal templates for meta data, google analytics, and DISQUS or COMMENTO comments
-* RSS Discovery
-* Table of Contents (must declare `toc: true` in post parameter)
-
-Also includes examples of Hugo Features or Functions:
-
-* Pagination (internal template)
-* Taxonomies
-* Archetypes
-* Custom shortcode
-* Related content
-* Hugo built-in menu
-* i18n
-* `with`
-* `first`
-* `after`
-* `sort`
-* Site LanguageCode
-* `where`
-* Content Views
-* Partials
-* Template layouts (type "post" uses a special list template, single template, and a content view)
-* Tags
-* `len`
-* Conditionals
-* `ge` (greater than or equal to)
-* `.Site.Params.mainSections` to avoid hard-coding "blog," etc. [[release note](https://github.com/gohugoio/hugo/blob/66ec6305f6cb450ddf9c489854146bac02f7dca1/docs/content/meta/release-notes.md#enhancements)]
-
-This theme uses the [Tachyons CSS library](https://tachyons.io/). This will allow you to manipulate the design of the theme by changing class names in HTML without touching the original CSS files.
+* Responsive layouts and accessible markup
+* Configurable hero/header behavior
+* Configurable social follow/share links
+* Optional contact form shortcode
+* Localized i18n strings in many languages
+* SEO defaults with Hugo internal templates
+* Reading time/word count support
+* Robots.txt handling by environment
## Compatibility
-> [!IMPORTANT]
-> The [main](https://github.com/theNewDynamic/gohugo-theme-ananke) branch contains the latest version of Ananke that is tested and working with GoHugo v0.146.0+. If you wish to use an older version of GoHugo, use the [v2.12 branch](https://github.com/theNewDynamic/gohugo-theme-ananke/tree/release/v2.12) that is working with GoHugo v0.128.1 to v0.145.0. To get the theme working with an even older version of GoHugo feel free to peruse the [releases page](https://github.com/theNewDynamic/gohugo-theme-ananke/tags) to find a version that is working with your GoHugo version.
+> [!IMPORTANT]
+> The `main` branch is maintained for Hugo **v0.146.0+**.
+>
+> * For Hugo **v0.128.1 to v0.145.0**, use branch [`release/v2.12`](https://github.com/theNewDynamic/gohugo-theme-ananke/tree/release/v2.12).
+> * For older Hugo versions, use a matching tag from the [releases page](https://github.com/theNewDynamic/gohugo-theme-ananke/tags).
## Installation
-Dive into our [documentation on installing the theme as GoHugo Module or Git Submodule](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Installation). [The official setup guide](https://gohugo.io/getting-started/quick-start/) of GoHugo covers the installation of the theme as Git Submodule.
+Ananke supports both installation methods:
-## Getting started
+* [Install as Hugo Module (recommended)](docs/installation/gohugo-module.md)
+* [Install as Git Submodule](docs/installation/git-submodule.md)
-After installing the theme successfully it requires [a few more steps to get your site running](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Getting-Started). Read on for a quick overview of the most important steps. Or follow one of the more detailed guides following.
+If you are new to Hugo, see Hugo's official quick start: [gohugo.io/getting-started/quick-start](https://gohugo.io/getting-started/quick-start/).
-## Latest Changes
+## Getting Started
-See the [CHANGELOG](CHANGELOG.md) for details about what has changed recently. For a list of older changes, see the [changelog-old.md](.github/changelog-old.md) file.
+After installation, use these guides to configure your site:
-## Contributing
+* [Getting Started](docs/getting-started.md)
+* [Configuration](docs/configuration/_index.md)
+* [Customisation](docs/customisation/_index.md)
+* [Troubleshooting](docs/troubleshooting.md)
-If you find a bug feel free to use the [issue tracker](https://github.com/theNewDynamic/gohugo-theme-ananke/issues) 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](https://github.com/theNewDynamic/gohugo-theme-ananke/discussion) for support.
+## Support and Contributions
-Join me on my [ananke-theme Discord channel](https://discord.gg/MykHvyU5P3) for direct support, but please remember that I am doing this in my spare time.
-
-If you would like to contribute code, please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for guidelines on how to contribute.
+* Bug reports: [GitHub Issues](https://github.com/theNewDynamic/gohugo-theme-ananke/issues)
+* Questions and feature ideas: [GitHub Discussions](https://github.com/theNewDynamic/gohugo-theme-ananke/discussions)
+* Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
diff --git a/archetypes/default.md b/archetypes/default.md
index 6398a82..b6d0a18 100644
--- a/archetypes/default.md
+++ b/archetypes/default.md
@@ -1,6 +1,6 @@
---
-title: "{{ replace .File.ContentBaseName "-" " " | title }}"
-date: {{ .Date }}
+title: '{{ replace .File.ContentBaseName "-" " " | title }}'
+date: '{{ .Date }}'
tags: []
featured_image: ""
description: ""
diff --git a/docs/getting-started.md b/docs/getting-started.md
index cf26765..723b7b7 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -3,205 +3,62 @@
date: 2026-01-16T08:00:00.000+0700
---
-_**Work in Progress! **_
+This guide summarizes the first configuration steps after installing Ananke.
-## Installation
+## 1) Install the theme
-Dive into our [documentation on installing the theme as GoHugo Module or Git Submodule](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Installation). [The official setup guide](https://gohugo.io/getting-started/quick-start/) of GoHugo covers the installation of the theme as Git Submodule.
+Choose one installation method:
-## Getting started
+* [Installation as Hugo Module (recommended)](installation/gohugo-module.md)
+* [Installation as Git Submodule](installation/git-submodule.md)
-After installing the theme successfully it requires a just a few more steps to get your site running.
+## 2) Confirm Hugo version compatibility
-### The config file
+Ananke on `main` expects Hugo `0.146.0` or newer. Check with:
-Take a look inside the [`exampleSite`](https://github.com/theNewDynamic/gohugo-theme-ananke/tree/master/exampleSite) folder of this theme. You'll find a file called [`config.toml`](https://github.com/theNewDynamic/gohugo-theme-ananke/blob/master/exampleSite/config.toml). To use it, copy the [`config.toml`](https://github.com/theNewDynamic/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.
-
-### Add comments
-
-[see Wiki > Customization Comments](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Customization-Comments)
-
-### Change the hero background
-
-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'`
-
-#### Featured image as Page Resources
-
-If user is using [Page Resources](https://gohugo.io/content-management/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`
-
-#### Other hero settings
-
-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](https://tachyons.io/docs/themes/skins/) 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](https://tachyons.io/docs/themes/skins/) 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"`
-
-### Activate the contact form
-
-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](//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:
-
-```go-html-template
-{{</* form-contact action="https://formspree.io/your@email.com" */>}}
+```bash
+hugo version
```
-### Read more link
+## 3) Configure required basics
-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.
+At minimum, configure:
-```toml
-# config.toml
-# Globally for all pages:
-[params]
-read_more_copy = "Read more about this entry"
+* Site `title`
+* `baseURL`
+* Theme/module setup
+* `params` values you want to customize
-# Just for french
-[languages.fr]
-name = "Français"
-weight = 2
+See:
-[languages.fr.params]
-read_more_copy = "En savoir plus à ce sujet"
-```
+* [General Configuration](configuration/general.md)
+* [SEO Configuration](configuration/seo.md)
+* [Social Media Networks](configuration/social-media-networks.md)
-Using front matter and cascade, this can be customized for a whole section, or just for one page.
+## 4) Add content and front matter
-```yaml
-# content/posts/tower-bridge-london.md
- title: The Tower Bridge of London
- read_more_copy: Read more about this bridge
-```
+Start adding content and use front matter options supported by Ananke:
-### Social Media Follow + Share
+* [Front Matter Options](content/frontmatter.md)
+* [General Content Features](content/general.md)
+* [Reading Time](content/reading-time.md)
+* [Shortcodes](content/shortcodes.md)
-Read the documentation for [social media follow](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Social-media-network-setup#configure-social-media-follow-links) and [social share](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Social-media-network-setup#configure-social-media-share-links) in our wiki.
+## 5) Customize visual style
-> This project uses Font Awesome brand icons, which are licensed under the [Creative Commons Attribution 4.0 International License (CC BY 4.0)](https://github.com/FortAwesome/Font-Awesome/blob/6.x/LICENSE.txt). For more information, visit [Font Awesome](https://fontawesome.com/).
+For design and UI adjustments:
-### Content indexing
+* [Hero section](customisation/hero-section.md)
+* [Colors](customisation/colours.md)
+* [Styles and CSS](customisation/styles.md)
+* [Comments setup](customisation/comments.md)
-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.
+## 6) Run and verify locally
-### Update font or body classes
-
-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:
-
-```toml
-[params]
- body_classes = "avenir bg-near-white"
-```
-
-which will give you a body class like this:
-
-```html
-<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](https://github.com/tachyons-css/tachyons/blob/v4.7.0/src/_font-family.css).
-
-And a list of background colors [here](https://github.com/tachyons-css/tachyons/blob/v4.7.0/src/_skins.css#L96).
-
-_n.b. in future versions we will likely separate the typeface and other body classes._
-
-### CSS
-
-Ananke stylesheet is built with Hugo Pipes's [Asset Bundling](https://gohugo.io/hugo-pipes/bundling/#readout) alone to maximize compatibility. The theme simply bundles its several files into one minified and fingerprinted (in production) CSS file.
-
-Ananke uses [Tachyons.io](https://tachyons.io/) utility class library.
-
-#### Custom CSS
-
-WARNING: Pending resolution of this [discussion](https://github.com/theNewDynamic/gohugo-theme-ananke/discussions/452#discussioncomment-1865301), 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.
-
-1. Just add a `assets/ananke/css` directory to your project and add the file(s) in it.
-2. Register the files using the `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:
-
-```toml
-[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 retrocompatibility 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.
-
-### Show Reading Time and Word Count
-
-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.
-
-### Adding Scripts to the Page Head
-
-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.
-
-### Logo
-
-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:
-
-```toml
-[params]
-site_logo = "img/logo.svg"
-```
-
-### Set Content Font Color
-
-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.
-
-```toml
-[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](https://tachyons.io/docs/themes/skins/).
-
-### Localize date format
-
-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.
-
-```toml
-[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](https://gohugo.io/functions/dateformat/) for more details.
-
-### Using a canonical url
-
-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.
-
-```yaml
-canonicalUrl: https://mydomain.com/path-to-the-original-content/
-```
-
-### Nearly finished
-
-In order to see your site in action, run Hugo's built-in local server.
+Run Hugo locally and verify pages, menus, metadata, and social links:
```bash
hugo server
```
-Now enter [`localhost:1313`](http://localhost:1313/) in the address bar of your browser.
+If you hit issues, see [Troubleshooting](troubleshooting.md).
diff --git a/site/README.md b/site/README.md
index 74d5ae1..1a996d8 100644
--- a/site/README.md
+++ b/site/README.md
@@ -1 +1,17 @@
-This folder contains the site setup for the documentation. The content for the documentation is under the root's `/docs` directory.
+# Documentation Site
+
+This directory contains the Hugo project used to render Ananke's documentation site.
+
+## Where docs content lives
+
+Documentation pages are authored in the repository root under [`/docs`](../docs).
+
+## Run locally
+
+From repository root:
+
+```bash
+npm run server
+```
+
+This runs `hugo server` in `site/` using the local docs content.
diff --git a/site/archetypes/default.md b/site/archetypes/default.md
deleted file mode 100644
index 30720d0..0000000
--- a/site/archetypes/default.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: '{{ replace .File.ContentBaseName "-" " " | title }}'
-description: ""
-date: "{{ .Date }}"
-tags: []
-featured_image: ""
-weight: 100
----
--
Gitblit v1.10.0