docs: add documentation pages (#897)

Patrick Kollitsch

3 days ago db854384305e8ff3f54400631e8787af30aafd98

docs: add documentation pages (#897)

# Changes

This adds a rudimentary documentation site for the theme based on the
theme.

- Add `docs/` content with the contents of the wiki
- Add a demo site under `site/` 
- Keeps the theme and site separate so the site uses the theme via Hugo
modules with a local replacement for development.

# Usage 

Run `npm run server` to build and serve the documentation from within
the repo.

---------

Signed-off-by: Patrick Kollitsch <83281+davidsneighbour@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

 .frontmatter/database/pinnedItemsDb.json

New file
@@ -0,0 +1 @@
{}

 .frontmatter/database/taxonomyDb.json

New file
@@ -0,0 +1 @@
{"taxonomy":{"tags":[],"categories":[]}}

 .vscode/settings.json

New file
@@ -0,0 +1,6 @@
{
    "cSpell.words": [
        "Ananke",
        "Kitchensink"
    ]
}

 docs/_index.md

New file
@@ -0,0 +1,6 @@
---
title: GoHugo Theme Ananke
date: 2026-01-16T08:00:00.000+0700
---

{{< page-index >}}

 docs/configuration/_index.md

New file
@@ -0,0 +1,5 @@
---
title: Configuration
date: 2026-01-16T08:00:00.000+0700
weight: 200
---

 docs/configuration/general.md

New file
@@ -0,0 +1,40 @@
---
title: General Configuration
date: 2026-01-16T08:00:00.000+0700
---

> [!IMPORTANT]
> Please note that GoHugo is extensible configurable with more generic or more specific configuration. Please read the documentation about [configuration files](https://gohugo.io/configuration/introduction/#configuration-file) and [configuration directories](https://gohugo.io/configuration/introduction/#configuration-directory) to learn more about this topic. Whenever Ananke's documentation refers to the configuration file it refers to any of these possible locations.
>
> Ananke's sample repositories are using configuration directories and you can find all referred configuration parameters in `config/_default/hugo.toml` and `config/_default/params.toml`.

> [!NOTE]
> Work in progress. The information on this page is a copy paste result from old notes and documentation. Needs rewrite.

### 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
{{/*< form-contact action="https://formspree.io/your@email.com" >*/}}
```

### 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"
```

### 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 date layouts, 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.

 docs/configuration/seo.md

New file
@@ -0,0 +1,11 @@
---
title: SEO
date: 2026-01-16T08:00:00.000+0700
---

> [!NOTE]
> Work in progress. The information on this page is a copy paste result from old notes and documentation. Needs rewrite.

### Content indexing

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.

 docs/configuration/social-media-networks.md

New file
@@ -0,0 +1,305 @@
---
title: Social Media Networks
date: 2026-01-16T08:00:00.000+0700
---

Ananke automatically adds "follow" link icons to the header and footer and "Share" link icons to pages unless the `disable_share` parameter is set to true either on the site level (site params) or page level (front matter). Each services can show a label, an icon, and be formatted in a custom color.

> MIGRATION: Read about how to migrate below in the Section [Migrate from versions before v2.11](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Social-media-network-setup#migrate-from-versions-before-v211)

## Configuration

All configuration of Ananke's social media features is located under the `ananke.social` section in your websites `params` section. This can be found at one of the following locations:

* in `hugo.toml` or `config.toml` in your website root under `params.ananke.social`
* in `config/_default/hugo.toml` or `config/_default/config.toml` under `params.ananke.social`
* in `config/_default/params.toml` under `ananke.social` or
* in `config/$ENVIRONMENTNAME/*` --- you know what you are doing

All samples in this documentation will refer to configuration in `config/_default/params.toml` and use the TOML format. If you have problems translating that into your configuration situation and format (JSON, YAML) [please join us in the Discussion Forum](https://github.com/theNewDynamic/gohugo-theme-ananke/discussions).

* `ananke.social.share` configures share buttons/links on single pages/posts
* `ananke.social.follow` configures social network links in "follow us on social media" widgets
* `ananke.social.networks` configures single networks. if user wants to extend, they add a new item to their local param section
* `ananke.social.$slugname` is individual configuration for the networks defined in `ananke.social.networks` that is to be set for the implementing site in the individual configuration

### Configure social media follow links

#### Set up global options

You can setup the display of your follow links with these options:

```toml
[ananke.social.follow]
new_window_icon = false
networks = [
  "facebook",
  "bluesky",
  "linkedin"
]
```

* `new_window_icon` (default is `false`): add a small indicator of an outgoing link to the icon if this is set to `true`.
* `networks` (required, no default): a list of `slug` parameters of the networks you wish to link to. You can either choose one or more of [the included pre-configured networks](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Social-media-network-setup#available-networks) or [configure your own networks](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Social-media-network-setup#setup-individual-new-networks).

#### Set your profile or user name

In the simplest case, add a slug for the network, and below that, add your username in that network:

```toml
[params.ananke.social.linkedin]
username = "patrickkollitsch"
```

The theme will then create a profile link without intervention.

#### Override the profile link

If you wish to override the profile link for the follow link then set the parameter `profilelink`:

```toml
[params.ananke.social.linkedin]
username = "patrickkollitsch"
profilelink = "https://th.linkedin.com/in/patrickkollitsch/"
```

Setting the username in that case might make sense if you want to use the username with the share link (for instance in networks that link to your user profile).

#### Override the label of the social network

Each social network is already set up with a proper label. If the user wishes to override the profiles network name they can do this via the label attribute:

```toml
[params.ananke.social.linkedin]
label = "Linked In"
```

This will override the globally set up label.

#### `rel` attributes on follow links

All social follow links use by default the attribute `rel="noopener"` to keep the privacy of people clicking on it. In some cases you wish to add other items to these links (like `me` to verify your ownership of the social media profile or your website). In that case you may add a `rel` parameter to this setup:

```toml
[params.ananke.social.linkedin]
username = "patrickkollitsch"
profilelink = "https://th.linkedin.com/in/patrickkollitsch/"
rel = "me"
```

Having multiple `rel` parameter separated by space is valid usage of this attribute. This will be extended by the noopener attribute in any case.

### Configure social media share links

#### Set up sharing networks

Setup sharing  the `ananke.social.share` section:

```toml
[ananke.social.share]
icons = true
sharetext = true
networks = [
  "email",
  "facebook",
  "bluesky",
  "linkedin"
]
```

* networks (required): To set your preferred networks and their order you define them in the `networks` parameter
* icons (optional, default `true`): show icons for each network
* sharetext (optional, default `false`): show share text for each network

#### Disable sharing partially or globally

By default sharing links on each single page are enabled. To disable this behaviour set `disable_share` in your pages front matter to `true`:

```yaml
---
disable_share: true
---
```

You can disable this feature completely by setting `ananke.social.share.disable_share` to `true` in your configuration:

```toml
[ananke.social.share]
disable_share: true
```

### Setup individual new networks

> [NOTE]
> The information in this section is for developer that want to extend the capabilities of Ananke above the pre-configured networks. Ignore this if you work only with the available networks.

It is fairly easy to extend the pre-configured networks with the following setup (for example for LinkedIn, which is already pre-configured):

```toml
[ananke.social.linkedin]
username = "patrick.kollitsch"

[ananke.social.networks.linkedin]
slug = "linkedin"
label = "LinkedIn"
color = "#0077b5"
profile = "http://linkedin.com/in/%s"
icon = "linkedin" # font awesome brand icon name
link = "https://www.linkedin.com/shareArticle"
#separator = "&"
[ananke.social.networks.linkedin.particles]
url = "permalink"
title = "title"
summary = "description"
source = "permalink"
params = "mini=true"
```

Every new network requires an entry in the `[ananke.social.networks.$NETWORK_SLUG]` table. The entries below that can be:

* slug (required): lower case alphanumerical string naming the network. use the networks name. if you want to add two profiles for one single network, you can achieve that by adding a slug like `linkedin2` and configure the profile in your local config with this slug.
* label (required): Title of the network (will be printed out in strings)
* color (optional): Color for the icon of this network
* profile (required): Either false, to disable the listing of this network in the follow section, or a string containing the link to the network profile. A `%s` marks the place that will be replaced with the users set up `username` under `ananke.social.$SLUGNAME` (in our case `ananke.social.linkedin`).
* icon (required): icon name under `assets/ananke/socials/` without `.svg`. The icon is part of [Fontawesome Brand Icons](https://fontawesome.com/search?o=r&f=brands) and you can find it more convenient on their page.
* share (optional, default is `true`): marks if this network functionality.
* link (required, if `share` is `true`): The start of the share link for this network

Then in `ananke.social.networks.$NETWORK_SLUG.particles` you can add as much as required parts that will be rendered as parameters in the share URL. The format for this system is this:

```toml
[ananke.social.networks.$NETWORK_SLUG.particles]
url = "permalink"
title = "title"
summary = "description"
source = "permalink"
params = "mini=true"
```

This will result in the following share link:

```plaintext
https://www.linkedin.com/shareArticle?url=%PERMALINK&title=%TITLE&summary=%DESCRIPTION&source=%PERMALINK&mini=true
```

Long story short: on the the label on the left is included as is, followed by `=` and the replaced value of the setting you name in the particle. This works pretty much like the page variables in GoHugo:

* `permalink` is replaced with the permalink of the page (urlencoded)
* `title` is replaced with the title of the page (urlencoded)
* `description` is replaced with the frontmatter description
* `username` is replaced with the configured `username` for that network (under the `ananke.social.$NETWORKSLUG` section)

Adding to that everything in `params` is added blindly to the resulting link.

This way you can create a share for nearly any network.

I am writing "nearly" because some networks do not like adding parameters the "normal" way. This is where the `separator` parameter comes into play:

```toml
separator = ";"
```

Using this parameter in the configuration above would result in our example URL looking like this:

```plaintext
https://www.linkedin.com/shareArticle?url=%PERMALINK;title=%TITLE;summary=%DESCRIPTION;source=%PERMALINK;mini=true
```

To override any of the existing networks add the **full** configuration row (including it's particles) into your local configuration and override the values you want to change.

To override the icon for a network add your own copy to your local `assets/ananke/socials/` directory.

## Available networks

This is a list of slugs for already configured networks in the theme. You can add missing networks without much hassle (see [Configure social media follow links](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Social-media-network-setup#configure-social-media-follow-links)). If you experience issue doing that [feel free to reach out in our Forum](https://github.com/theNewDynamic/gohugo-theme-ananke/discussions).

| Slug | profile | share | Notes |
| --- | :---: | :---: | --- |
| bluesky | ✅ | ✅ | Read notes about [configuring networks with multiple hosts](#configuring-networks-with-multiple-hosts) |
| email | ❌ |✅ | |
| facebook | ✅ | ✅ | |
| github | ✅ | ❌ |  |
| gitlab | ✅ | ❌ |  |
| hackernews | ✅ | ✅ | |
| instagram | ✅ | ❔ |  |
| keybase | ✅ | ❌ |  |
| linkedin | ✅ | ✅ | |
| medium | ✅ | ❔ |  |
| mastodon | ✅ | ❌ | Read notes about [configuring networks with multiple hosts](#configuring-networks-with-multiple-hosts) |
| pinterest | ✅ | ✅ | |
| reddit | ✅ | ✅ | |
| rss | ✅ | ❌ | add `profilelink` to link to your RSS feed |
| slack | ✅ | ❔ | add `profilelink` to your slack channel |
| stackoverflow | ✅ | ❌ | your `username` is your profile's ID |
| telegram | ✅ | ✅ | |
| tiktok | ✅ | ✅ | |
| tumblr | ✅ | ✅ | |
| twitter | ✅ | ✅ | |
| whatsapp | ❌ | ✅ | |
| xing | ✅ | ✅ | |
| x-twitter | ✅ | ✅ |  |
| youtube | ✅ | ❔ |  |

Legend:
✅ --- feature configured
❌ --- feature not configured and not available
❔ --- feature not configured, but might be available

---

## Migrate from versions before v2.11

Take your existing configuration under `params.ananke_social` and apply them to the new structure under `params.ananke.social` (note that `ananke` and `social` are two subsections now, not one combined label).

Follow the instructions under [Configure social media follow links](https://github.com/theNewDynamic/gohugo-theme-ananke/wiki/Social-media-network-setup#configure-social-media-follow-links) to configure your social media links.

`params.ananke_social` (the *old* configuration with the underscore) can then be removed from your configuration.

TLDR:

**Old config:**

```toml
[[ananke_socials]]
name = "twitter"
url = "https://twitter.com/theNewDynamic"
```

**New config:**

```toml
[[ananke.social.twitter]]
username = "theNewDynamic"
profilelink = "https://twitter.com/theNewDynamic" # (optional, this would be covered by the username above)
```

### Development changes

* all functions in `partial/func/socials` are removed
* If you were using the following partials anywhere:

  ```go
  {{ partial "social-follow.html" . }}
  {{ partial "social-share.html" . }}
  ```

  you should be able to replace the functionality with this change

  ```go
  {{ partial "social/follow.html" . }}
  {{ partial "social/share.html" . }}
  ```

## Notes

### Font Awesome

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/).

### Customize Icons

This theme comes with Font Awesome brand icons. If you wish to use your own icon set you can override all icons by copying them into your own repository under `assets/ananke/socials`. Icons need to be in the SVG format with a `.svg` extension. Their name needs to match the `slug` parameter in the `ananke.social.networks` setup for the selected network.

### Configuring networks with multiple hosts

Due to the nature of Mastodon and Bluesky instances there is no way to configure all networks without too much noise. Configuration, for now, requires a `profilelink` parameter with the full URL to your profile. `username` can be ignored in that case.

 docs/content/_index.md

New file
@@ -0,0 +1,5 @@
---
title: Content
date: 2026-01-16T08:00:00.000+0700
weight: 300
---

 docs/content/frontmatter.md

New file
@@ -0,0 +1,71 @@
---
title: Frontmatter
date: 2026-01-16T08:00:00.000+0700
---

> [!NOTE]
> Work in progress. The information on this page is a copy paste result from old notes and documentation. Needs rewrite.

## Using a canonical url

If 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/
```

## Common Options

| Key              | Type    | Description                                                                 | Default             |
|------------------|---------|-----------------------------------------------------------------------------|---------------------|
| `title`          | string  | The title shown on the page and in metadata                                 | Required            |
| `linktitle`      | string  | Overrides the page title in menus and breadcrumbs                          | Uses `title`        |
| `summary`        | string  | Custom page summary shown in list views                                    | Auto-generated      |
| `description`    | string  | Meta description for SEO and previews                                      | Empty               |

## Example: Disabling Breadcrumbs

```toml
disableBreadcrumbs = true
```

This removes the breadcrumb trail from a single page layout.

---

## Example: Custom Layout

```toml
layout = "project"
```

This loads `layouts/_default/project.html` or a corresponding type fallback.

---

## Example: Using `linktitle`

```toml
title = "My Long Page Title"
linktitle = "Short Name"
```

This helps keep breadcrumbs and menus short while using a full title on the page.

---

## Defaults & Fallbacks

Most fields are optional. When not set:

* `linktitle` falls back to `title`
* `layout` is inferred from `type` or content section
* `summary` is generated from the first paragraph
* `description` may be empty unless manually added
* `disableBreadcrumbs` is `false` unless set

---

## Notes

These values apply to all content types and can be overridden per page. Consider using Archetypes for pre-filled front matter in your content structure.

 docs/content/general.md

New file
@@ -0,0 +1,38 @@
---
title: General
date: 2026-01-16T08:00:00.000+0700
---

> [!NOTE]
> Work in progress. The information on this page is a copy paste result from old notes and documentation. Needs rewrite.

### Read more link

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.

```toml
# 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.

```yaml
# content/posts/tower-bridge-london.md
  title: The Tower Bridge of London
  read_more_copy: Read more about this bridge
```

### 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.

 docs/content/shortcodes.md

New file
@@ -0,0 +1,128 @@
---
title: Shortcodes
date: 2026-01-16T08:00:00.000+0700
---

> [!NOTE]
> Work in progress. The information on this page is a copy paste result from old notes and documentation. Needs rewrite.

### 📄 `shortcodes-index.md`

```md
# Shortcodes

Shortcodes are reusable content snippets that simplify complex HTML structures in Markdown files.

Use shortcodes with the `{{/*< >*/}}` or `{{/*% %*/}}` syntax in your content files.

---

## Available Shortcodes

| Name      | Purpose                       | Example Usage                             |
|-----------|-------------------------------|--------------------------------------------|
| `figure`  | Responsive image with caption | `{{/*< figure src="/img/example.jpg" caption="An image" >*/}}` |
| `button`  | Renders a styled button       | `{{/*< button href="/contact" */>}}Say Hello{{/*< /button >*/}}` |
| `highlight` | Syntax highlighting (fallback) | `{{/*< highlight html >*/}}...{{/*< /highlight >*/}}` |

> 💡 These shortcodes can be extended or replaced in your own project. Place overrides under `layouts/shortcodes/`.

---

## Example: `figure` Shortcode

### Markdown

```md
{{< figure src="/images/cat.jpg" caption="This is a cat" >}}
```

### Output

```html
<figure>
  <img src="/images/cat.jpg" alt="This is a cat">
  <figcaption>This is a cat</figcaption>
</figure>
```

---

## Notes

* You can override or create new shortcodes by placing them in your project’s `layouts/shortcodes/` folder.
* Always prefer shortcodes over raw HTML in content files for portability.

```

---

### 📄 `partials-index.md`

```md
# Partials and Components

Partials are reusable template blocks used in layouts and components. They simplify common rendering tasks.

---

## Breadcrumbs Partial

Location: `partials/content/components/breadcrumbs.html`

### Purpose

Renders a breadcrumb trail with microdata support. Automatically pulls from page hierarchy and supports overrides.

### Features

* Uses `linktitle` if present.
* Configurable separator via SCSS variable.
* Adds SEO microdata for search engines.
* Can be disabled per page.



## Debug Toggle Partial

Location: `partials/components/debug-toggle.html`

### Purpose

Toggles developer overlays like spacing grids and outline borders via Alpine.js.

### Example

Add this partial in your base layout (only in development):

```gohtml
{{ partial "components/debug-toggle.html" . }}
```

Includes toggles for:
* Grid overlay
* Outline borders
* Spacing rulers

---

## Notes

* All partials can be overridden in your own theme or site by copying them to the same path under `layouts/partials/`.
* Avoid directly modifying theme partials unless you control the upstream theme.

```

---

### ✅ Removed from `Readme.md`:

* Refs to the breadcrumbs partial.
* Refs to debug-toggle.
* General mentions of shortcodes/components.

Cleaned out from `Readme.md`.

---

Let me know when you're ready to move on — or if you want to split off the debug-toggle docs into their own file instead.

 docs/customisation/_index.md

New file
@@ -0,0 +1,5 @@
---
title: Customization
date: 2026-01-16T08:00:00.000+0700
weight: 400
---

 docs/customisation/colours.md

New file
@@ -0,0 +1,24 @@
---
title: Colours
date: 2026-01-16T08:00:00.000+0700
---

> [!NOTE]
> Work in progress. The information on this page is a copy paste result from old notes and documentation. Needs rewrite.

## 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/).

 docs/customisation/comments.md

New file
@@ -0,0 +1,28 @@
---
title: Comments
date: 2026-01-16T08:00:00.000+0700
---

Ananke currently supports two commenting systems: Disqus and [Commento](https://commento.io/).

## Disqus

Using [Disqus](https://disqus.com/) as a comment system for your website is an internal feature of Hugo. For more information see the official [Hugo documentation](http://gohugo.io/content-management/comments/). 

```toml
[services.disqus]
shortname = 'YOURSHORTNAME'
```

Note that the setup for Disqus is _NOT_ done inside of the `params` section, but with in the `services` section of your config file. To turn off Disqus, remove, or comment out the preceding lines.

## Commento.io

```toml
[params]
commentoEnable = true
# if you use a selfhosted version of commento, uncomment the next line and set your path
# commentoPath = "https://commento.io/YOURPATH" 
```

By default it uses the public Commento instance at `https://commento.io`. If you are using a [self-hosted version of Commento](https://docs.commento.io/installation/self-hosting/), uncomment the `commentoPath` line and set it to your Commento instance URL.

 docs/customisation/hero-section.md

New file
@@ -0,0 +1,31 @@
---
title: Hero Section
date: 2026-01-16T08:00:00.000+0700
---

> [!NOTE]
> Work in progress. The information on this page is a copy paste result from old notes and documentation. Needs rewrite.

## 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"`

 docs/customisation/styles.md

New file
@@ -0,0 +1,56 @@
---
title: Styles
date: 2026-01-16T08:00:00.000+0700
---

> [!NOTE]
> Work in progress. The information on this page is a copy paste result from old notes and documentation. Needs rewrite.

## 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:

```go
<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).

## 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.

 docs/getting-started.md

New file
@@ -0,0 +1,207 @@
---
title: Getting Started
date: 2026-01-16T08:00:00.000+0700
---

_**Work in Progress! **_

## 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.

## Getting started

After installing the theme successfully it requires a just a few more steps to get your site running.

### The config file

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
{{/*< form-contact action="https://formspree.io/your@email.com" >*/}}
```

### Read more link

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.

```toml
# 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.

```yaml
# content/posts/tower-bridge-london.md
  title: The Tower Bridge of London
  read_more_copy: Read more about this bridge
```

### Social Media Follow + Share

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.

> 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/).

### Content indexing

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.

### 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:

```go
<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.

```bash
hugo server
```

Now enter [`localhost:1313`](http://localhost:1313/) in the address bar of your browser.

 docs/installation/_index.md

New file
@@ -0,0 +1,5 @@
---
title: Installation
date: 2026-01-16T08:00:00.000+0700
weight: 100
---

 docs/installation/git-submodule.md

New file
@@ -0,0 +1,68 @@
---
title: Installation as Git Submodule
date: 2026-01-16T08:00:00.000+0700
---

# Installation as a Git Submodule (outdated)

Git Submodule based installation for the [Ananke theme](https://github.com/theNewDynamic/gohugo-theme-ananke) for [GoHugo](https://gohugo.io/).

## Methods

* [Install Ananke as GoHugo Module](Installation-as-GoHugo-Module)
* **[Install Ananke as Git Submodule](Installation-as-Git-Submodule) - this page**

## Requirements

1. [Install Hugo](https://gohugo.io/installation/linux/) (extended or extended/deploy edition, 0.128.0 or later)
2. [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)

## Installation

To install or create a GoHugo website from scratch with the Ananke theme using the submodule method, follow these steps:

Verify that you have installed Hugo 0.128.0 or later.

```bash
hugo version
```

Create the project structure `quickstart` directory:

```bash
hugo new site quickstart
```

Change into the newly created directory:

```bash
cd quickstart
```

Initialize Git in the current directory:

```bash
git init
```

Clone the theme into the `themes` directory, adding it to your project as a [Git submodule].

```bash
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
```

Append a line to the site configuration file, indicating the current theme.

```bash
echo "theme = 'ananke'" >> hugo.toml
```

Start Hugo's development server to view the site.

```bash
hugo server
```

Running this command will start the development server and you can see your website at <http://localhost:1313/>. To stop the development server press `Ctrl + C`.

To set up details like the comment system, follow the steps in the [Ananke theme's getting started guide](https://github.com/theNewDynamic/gohugo-theme-ananke#getting-started).

 docs/installation/gohugo-module.md

New file
@@ -0,0 +1,89 @@
---
title: Installation as GoHugo Module
date: 2026-01-16T08:00:00.000+0700
---

# Installation as a Hugo Module (recommended)

Hugo Module based installation for the [Ananke theme](https://github.com/theNewDynamic/gohugo-theme-ananke) for [GoHugo](https://gohugo.io/).

## Methods

* **[Install Ananke as GoHugo Module](Installation-as-GoHugo-Module) - this page**
* [Install Ananke as Git Submodule](Installation-as-Git-Submodule)

## Requirements

1. [Install Hugo](https://gohugo.io/installation/linux/) (extended or extended/deploy edition, 0.128.0 or later)
2. [Install Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
3. [Install Golang](https://golang.org/doc/install)

## Installation

To install or create a GoHugo website from scratch with the Ananke theme using the *GoHugo Module* method, follow these steps:

Verify that you have installed Hugo 0.128.0 or later.

```bash
hugo version
```

Create the project structure `quickstart` directory:

```bash
hugo new site quickstart
```

Change into the newly created directory:

```bash
cd quickstart
```

Initialize Git in the current directory:

```bash
git init
```

Initialize your repository as a Hugo Module:

```bash
hugo mod init github.com/username/reponame
```

Note: replace username and reponame with the path to your repository. This is a convention that is not enforced, of course your module can be named anything you like, but it is recommended to use the same path as your repository.

Add the Ananke theme as a Hugo Module:

```toml
[module]
[[module.imports]]
disable = false
ignoreConfig = false
ignoreImports = false
path = 'github.com/theNewDynamic/gohugo-theme-ananke/v2'
```

Note: Hugo configuration can have various formats and locations. The previous lines are written in the `hugo.toml` or `config.toml` file at the root of the project. If you have a different configuration file or format it could be that you need to add the module configuration in a different way.

Note: `v2` is required to use the latest published version of Ananke.

Now update the module configuration by running:

```bash
hugo mod get -u ./...
hugo mod tidy
```

This will load the module into the cache and create/update the `go.mod` and `go.sum` files. These two files should be added to your repository.

Start Hugo's development server to view the site.

```bash
hugo server
```

Running this command will start the development server and you can see your website at <http://localhost:1313/>. To stop the development server press `Ctrl + C`.

To set up details like the comment system, follow the steps in the [Ananke theme's getting started guide](https://github.com/theNewDynamic/gohugo-theme-ananke#getting-started).

 docs/installation/installation.md

New file
@@ -0,0 +1,29 @@
---
title: Installation
date: 2026-01-16T08:00:00.000+0700
---

## Installing the Ananke Theme for Hugo

<!-- > [!NOTE]
> This post was published and might have updates at [kollitsch.dev](https://kollitsch.dev/posts/installing-ananke-theme-hugo/) -->

If you're following the [Hugo Quickstart guide](https://gohugo.io/getting-started/quick-start/), you'll notice that it currently recommends installing the Ananke theme as a **Git submodule**. While this is a valid approach, Hugo also offers a more powerful alternative: **Hugo Modules**, which leverage Go's module system for better dependency management.

There are two primary ways to install Ananke:

1. **Hugo Module** --- Uses Hugo's built-in Go module system to fetch and manage the theme as a package.
2. **Git Submodule** *(Legacy Method)* --- Links the theme repository as a submodule inside your Hugo project.

### Comparison: Hugo Module vs. Git Submodule

| Method           | Pros | Cons |
|-----------------|------|------|
| [**Hugo Module**](Installation-as-GoHugo-Module) *(Preferred)* | Easier version management, automatic updates, better integration | Requires Go installed and initial setup |
| [**Git Submodule**](Installation-as-Git-Submodule) *(Legacy Method)* | Simple if you're already using Git | Requires manual updates, can be tricky with Git workflows |

**Recommendation:** The **Hugo Module approach is preferred**, as it provides a more flexible and future-proof way to manage themes.

For step-by-step installation instructions, refer to these **work-in-progress** sample repositories:
* **Hugo Module installation (preferred):** [gohugo-theme-ananke-template-mod](https://github.com/davidsneighbour/gohugo-theme-ananke-template-mod)
* **Git Submodule installation (Legacy Method):** [gohugo-theme-ananke-template-submod](https://github.com/davidsneighbour/gohugo-theme-ananke-template-submod)

 docs/kitchensink.md

New file
@@ -0,0 +1,484 @@
---
title: Kitchensink
date: 2026-01-16T08:00:00.000+0700
---

## Reusable Snippets

> [!IMPORTANT]
> Please note that GoHugo is extensible configurable with more generic or more specific configuration. Please read the documentation about [configuration files](https://gohugo.io/configuration/introduction/#configuration-file) and [configuration directories](https://gohugo.io/configuration/introduction/#configuration-directory) to learn more about this topic. Whenever Ananke's documentation refers to the configuration file it refers to any of these posible locations.
>
> Ananke's sample repositories are using configuration directories and you can find all referred configuration parameters in `config/_default/hugo.toml` and `config/_default/params.toml`.

> [!TIP]
> We offer two sample repositories for Ananke's use. Feel free to clone them and play around to test out features described here:
>
> * [gohugo-theme-ananke-template-mod](https://github.com/davidsneighbour/gohugo-theme-ananke-template-mod) --- Hugo Module installation (preferred)
> * [gohugo-theme-ananke-template-submod](https://github.com/davidsneighbour/gohugo-theme-ananke-template-submod) --- Git Submodule installation (legacy method)

> [!NOTE]
> Work in progress. The information on this page is a copy paste result from old notes and documentation. Needs rewrite.

# Official Github Markdown Docs - just a copy

See [here](https://github.com/github/docs/blob/main/content/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax.md)

## Headings

To create a heading, add one to six <kbd>#</kbd> symbols before your heading text. The number of <kbd>#</kbd> you use will determine the hierarchy level and typeface size of the heading.

```markdown
# A first-level heading
## A second-level heading
### A third-level heading
```

![Screenshot of rendered GitHub Markdown showing sample h1, h2, and h3 headers, which descend in type size and visual weight to show hierarchy level.](/assets/images/help/writing/headings-rendered.png)

When you use two or more headings, GitHub automatically generates a table of contents that you can access by clicking {% octicon "list-unordered" aria-label="The unordered list icon" %} within the file header. Each heading title is listed in the table of contents and you can click a title to navigate to the selected section.

![Screenshot of a README file with the drop-down menu for the table of contents exposed. The table of contents icon is outlined in dark orange.](/assets/images/help/repository/headings-toc.png)

## Styling text

You can indicate emphasis with bold, italic, strikethrough, subscript, or superscript text in comment fields and `.md` files.

| Style | Syntax | Keyboard shortcut | Example | Output |
| --- | --- | --- | --- | --- |
| Bold | `** **` or `__ __`| <kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux) | `**This is bold text**` | **This is bold text** |
| Italic | `* *` or `_ _`     | <kbd>Command</kbd>+<kbd>I</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>I</kbd> (Windows/Linux) | `_This text is italicized_` | _This text is italicized_ |
| Strikethrough | `~~ ~~` or `~ ~` | None | `~~This was mistaken text~~` | ~~This was mistaken text~~ |
| Bold and nested italic | `** **` and `_ _` | None | `**This text is _extremely_ important**` | **This text is _extremely_ important** |
| All bold and italic | `*** ***` | None | `***All this text is important***` | ***All this text is important*** | <!-- markdownlint-disable-line emphasis-style -->
| Subscript | `<sub> </sub>` | None | `This is a <sub>subscript</sub> text` | This is a <sub>subscript</sub> text |
| Superscript | `<sup> </sup>` | None | `This is a <sup>superscript</sup> text` | This is a <sup>superscript</sup> text |
| Underline | `<ins> </ins>` | None | `This is an <ins>underlined</ins> text` | This is an <ins>underlined</ins> text |

## Quoting text

You can quote text with a <kbd>></kbd>.

```markdown
Text that is not a quote

> Text that is a quote
```

Quoted text is indented with a vertical line on the left and displayed using gray type.

![Screenshot of rendered GitHub Markdown showing the difference between normal and quoted text.](/assets/images/help/writing/quoted-text-rendered.png)

> [!NOTE]
> When viewing a conversation, you can automatically quote text in a comment by highlighting the text, then typing <kbd>R</kbd>. You can quote an entire comment by clicking {% octicon "kebab-horizontal" aria-label="The horizontal kebab icon" %}, then **Quote reply**. For more information about keyboard shortcuts, see [AUTOTITLE](/get-started/accessibility/keyboard-shortcuts).

## Quoting code

You can call out code or a command within a sentence with single backticks. The text within the backticks will not be formatted. You can also press the <kbd>Command</kbd>+<kbd>E</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>E</kbd> (Windows/Linux) keyboard shortcut to insert the backticks for a code block within a line of Markdown.

```markdown
Use `git status` to list all new or modified files that haven't yet been committed.
```

![Screenshot of rendered GitHub Markdown showing that characters surrounded by backticks are shown in a fixed-width typeface, highlighted in light gray.](/assets/images/help/writing/inline-code-rendered.png)

To format code or text into its own distinct block, use triple backticks.

````markdown
Some basic Git commands are:
```
git status
git add
git commit
```
````

![Screenshot of rendered GitHub Markdown showing a simple code block without syntax highlighting.](/assets/images/help/writing/code-block-rendered.png)

For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks).

{% data reusables.user-settings.enabling-fixed-width-fonts %}

## Supported color models

In issues, pull requests, and discussions, you can call out colors within a sentence by using backticks. A supported color model within backticks will display a visualization of the color.

```markdown
The background color is `#ffffff` for light mode and `#000000` for dark mode.
```

![Screenshot of rendered GitHub Markdown showing how HEX values within backticks create small circles of color, here white and then black.](/assets/images/help/writing/supported-color-models-rendered.png)

Here are the currently supported color models.

| Color | Syntax | Example | Output |
| --- | --- | --- | --- |
| HEX | <code>\`#RRGGBB\`</code> | <code>\`#0969DA\`</code> | ![Screenshot of rendered GitHub Markdown showing how HEX value #0969DA appears with a blue circle.](/assets/images/help/writing/supported-color-models-hex-rendered.png) |
| RGB | <code>\`rgb(R,G,B)\`</code> | <code>\`rgb(9, 105, 218)\`</code> | ![Screenshot of rendered GitHub Markdown showing how RGB value 9, 105, 218 appears with a blue circle.](/assets/images/help/writing/supported-color-models-rgb-rendered.png) |
| HSL | <code>\`hsl(H,S,L)\`</code> | <code>\`hsl(212, 92%, 45%)\`</code> | ![Screenshot of rendered GitHub Markdown showing how HSL value 212, 92%, 45% appears with a blue circle.](/assets/images/help/writing/supported-color-models-hsl-rendered.png) |

> [!NOTE]
> * A supported color model cannot have any leading or trailing spaces within the backticks.
> * The visualization of the color is only supported in issues, pull requests, and discussions.

## Links

You can create an inline link by wrapping link text in brackets `[ ]`, and then wrapping the URL in parentheses `( )`. You can also use the keyboard shortcut <kbd>Command</kbd>+<kbd>K</kbd> to create a link. When you have text selected, you can paste a URL from your clipboard to automatically create a link from the selection.

You can also create a Markdown hyperlink by highlighting the text and using the keyboard shortcut <kbd>Command</kbd>+<kbd>V</kbd>. If you'd like to replace the text with the link, use the keyboard shortcut <kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>V</kbd>.

`This site was built using [GitHub Pages](https://pages.github.com/).`

![Screenshot of rendered GitHub Markdown showing how text within brackets, "GitHub Pages," appears as a blue hyperlink.](/assets/images/help/writing/link-rendered.png)

> [!NOTE]
> {% data variables.product.github %} automatically creates links when valid URLs are written in a comment. For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls).

## Section links

{% data reusables.repositories.section-links %}

If you need to determine the anchor for a heading in a file you are editing, you can use the following basic rules:

* Letters are converted to lower-case.
* Spaces are replaced by hyphens (`-`). Any other whitespace or punctuation characters are removed.
* Leading and trailing whitespace are removed.
* Markup formatting is removed, leaving only the contents (for example, `_italics_` becomes `italics`).
* If the automatically generated anchor for a heading is identical to an earlier anchor in the same document, a unique identifier is generated by appending a hyphen and an auto-incrementing integer.

For more detailed information on the requirements of URI fragments, see [RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 3.5](https://www.rfc-editor.org/rfc/rfc3986#section-3.5).

The code block below demonstrates the basic rules used to generate anchors from headings in rendered content.

```markdown
# Example headings

## Sample Section

## This'll be a _Helpful_ Section About the Greek Letter Θ!
A heading containing characters not allowed in fragments, UTF-8 characters, two consecutive spaces between the first and second words, and formatting.

## This heading is not unique in the file

TEXT 1

## This heading is not unique in the file

TEXT 2

# Links to the example headings above

Link to the sample section: [Link Text](#sample-section).

Link to the helpful section: [Link Text](#thisll-be-a-helpful-section-about-the-greek-letter-Θ).

Link to the first non-unique section: [Link Text](#this-heading-is-not-unique-in-the-file).

Link to the second non-unique section: [Link Text](#this-heading-is-not-unique-in-the-file-1).
```

> [!NOTE]
> If you edit a heading, or if you change the order of headings with "identical" anchors, you will also need to update any links to those headings as the anchors will change.

## Relative links

{% data reusables.repositories.relative-links %}

## Custom anchors

You can use standard HTML anchor tags (`<a name="unique-anchor-name"></a>`) to create navigation anchor points for any location in the document. To avoid ambiguous references, use a unique naming scheme for anchor tags, such as adding a prefix to the `name` attribute value.

> [!NOTE]
> Custom anchors will not be included in the document outline/Table of Contents.

You can link to a custom anchor using the value of the `name` attribute you gave the anchor. The syntax is exactly the same as when you link to an anchor that is automatically generated for a heading.

For example:

```markdown
# Section Heading

Some body text of this section.

<a name="my-custom-anchor-point"></a>
Some text I want to provide a direct link to, but which doesn't have its own heading.

(… more content…)

[A link to that custom anchor](#my-custom-anchor-point)
```

> [!TIP]
> Custom anchors are not considered by the automatic naming and numbering behavior of automatic heading links.

## Line breaks

If you're writing in issues, pull requests, or discussions in a repository, {% data variables.product.github %} will render a line break automatically:

```markdown
This example
Will span two lines
```

However, if you are writing in an .md file, the example above would render on one line without a line break. To create a line break in an .md file, you will need to include one of the following:

* Include two spaces at the end of the first line.
  <pre>
  This example&nbsp;&nbsp;
  Will span two lines
  </pre>
* Include a backslash at the end of the first line.

  ```markdown
  This example\
  Will span two lines
  ```

* Include an HTML single line break tag at the end of the first line.

  ```markdown
  This example<br/>
  Will span two lines
  ```

If you leave a blank line between two lines, both .md files and Markdown in issues, pull requests, and discussions will render the two lines separated by the blank line:

```markdown
This example

Will have a blank line separating both lines
```

## Images

You can display an image by adding <kbd>!</kbd> and wrapping the alt text in `[ ]`. Alt text is a short text equivalent of the information in the image. Then, wrap the link for the image in parentheses `()`.

`![Screenshot of a comment on a GitHub issue showing an image, added in the Markdown, of an Octocat smiling and raising a tentacle.](https://myoctocat.com/assets/images/base-octocat.svg)`

![Screenshot of a comment on a GitHub issue showing an image, added in the Markdown, of an Octocat smiling and raising a tentacle.](/assets/images/help/writing/image-rendered.png)

{% data variables.product.github %} supports embedding images into your issues, pull requests{% ifversion fpt or ghec %}, discussions{% endif %}, comments and `.md` files. You can display an image from your repository, add a link to an online image, or upload an image. For more information, see [Uploading assets](#uploading-assets).

> [!NOTE]
> When you want to display an image that is in your repository, use relative links instead of absolute links.

Here are some examples for using relative links to display an image.

| Context | Relative Link |
| ------ | -------- |
| In a `.md` file on the same branch | `/assets/images/electrocat.png` |
| In a `.md` file on another branch | `/../main/assets/images/electrocat.png` |
| In issues, pull requests and comments of the repository | `../blob/main/assets/images/electrocat.png?raw=true` |
| In a `.md` file in another repository | `/../../../../github/docs/blob/main/assets/images/electrocat.png` |
| In issues, pull requests and comments of another repository | `../../../github/docs/blob/main/assets/images/electrocat.png?raw=true` |

> [!NOTE]
> The last two relative links in the table above will work for images in a private repository only if the viewer has at least read access to the private repository that contains these images.

For more information, see [Relative Links](#relative-links).

### The Picture element

The `<picture>` HTML element is supported.

## Lists

You can make an unordered list by preceding one or more lines of text with <kbd>-</kbd>, <kbd>*</kbd>, or <kbd>+</kbd>.

```markdown
- George Washington
* John Adams
+ Thomas Jefferson
```

![Screenshot of rendered GitHub Markdown showing a bulleted list of the names of the first three American presidents.](/assets/images/help/writing/unordered-list-rendered.png)

To order your list, precede each line with a number.

```markdown
1. James Madison
2. James Monroe
3. John Quincy Adams
```

![Screenshot of rendered GitHub Markdown showing a numbered list of the names of the fourth, fifth, and sixth American presidents.](/assets/images/help/writing/ordered-list-rendered.png)

### Nested Lists

You can create a nested list by indenting one or more list items below another item.

To create a nested list using the web editor on {% data variables.product.github %} or a text editor that uses a monospaced font, like [{% data variables.product.prodname_vscode %}](https://code.visualstudio.com/), you can align your list visually. Type space characters in front of your nested list item until the list marker character (<kbd>-</kbd> or <kbd>*</kbd>) lies directly below the first character of the text in the item above it.

```markdown
1. First list item
   - First nested list item
     - Second nested list item
```

> [!NOTE]
> In the web-based editor, you can indent or dedent one or more lines of text by first highlighting the desired lines and then using <kbd>Tab</kbd> or <kbd>Shift</kbd>+<kbd>Tab</kbd> respectively.

![Screenshot of Markdown in {% data variables.product.prodname_vscode %} showing indentation of nested numbered lines and bullets.](/assets/images/help/writing/nested-list-alignment.png)

![Screenshot of rendered GitHub Markdown showing a numbered item followed by nested bullets at two different levels of nesting.](/assets/images/help/writing/nested-list-example-1.png)

To create a nested list in the comment editor on {% data variables.product.github %}, which doesn't use a monospaced font, you can look at the list item immediately above the nested list and count the number of characters that appear before the content of the item. Then type that number of space characters in front of the nested list item.

In this example, you could add a nested list item under the list item `100. First list item` by indenting the nested list item a minimum of five spaces, since there are five characters (`100.`) before `First list item`.

```markdown
100. First list item
     - First nested list item
```

![Screenshot of rendered GitHub Markdown showing a numbered item prefaced by the number 100 followed by a bulleted item nested one level.](/assets/images/help/writing/nested-list-example-3.png)

You can create multiple levels of nested lists using the same method. For example, because the first nested list item has seven characters (`␣␣␣␣␣-␣`) before the nested list content `First nested list item`, you would need to indent the second nested list item by at least two more characters (nine spaces minimum).

```markdown
100. First list item
     - First nested list item
       - Second nested list item
```

![Screenshot of rendered GitHub Markdown showing a numbered item prefaced by the number 100 followed by bullets at two different levels of nesting.](/assets/images/help/writing/nested-list-example-2.png)

For more examples, see the [GitHub Flavored Markdown Spec](https://github.github.com/gfm/#example-265).

## Task lists

{% data reusables.repositories.task-list-markdown %}

If a task list item description begins with a parenthesis, you'll need to escape it with <kbd>\\</kbd>:

`- [ ] \(Optional) Open a followup issue`

For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists).

## Mentioning people and teams

You can mention a person or [team](/organizations/organizing-members-into-teams) on {% data variables.product.github %} by typing <kbd>@</kbd> plus their username or team name. This will trigger a notification and bring their attention to the conversation. People will also receive a notification if you edit a comment to mention their username or team name. For more information about notifications, see [AUTOTITLE](/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/about-notifications).

> [!NOTE]
> A person will only be notified about a mention if the person has read access to the repository and, if the repository is owned by an organization, the person is a member of the organization.

`@github/support What do you think about these updates?`

![Screenshot of rendered GitHub Markdown showing how the team mention "@github/support" renders as bold, clickable text.](/assets/images/help/writing/mention-rendered.png)

When you mention a parent team, members of its child teams also receive notifications, simplifying communication with multiple groups of people. For more information, see [AUTOTITLE](/organizations/organizing-members-into-teams/about-teams).

Typing an <kbd>@</kbd> symbol will bring up a list of people or teams on a project. The list filters as you type, so once you find the name of the person or team you are looking for, you can use the arrow keys to select it and press either tab or enter to complete the name. For teams, enter the @organization/team-name and all members of that team will get subscribed to the conversation.

The autocomplete results are restricted to repository collaborators and any other participants on the thread.

## Referencing issues and pull requests

You can bring up a list of suggested issues and pull requests within the repository by typing <kbd>#</kbd>. Type the issue or pull request number or title to filter the list, and then press either tab or enter to complete the highlighted result.

For more information, see [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls).

## Referencing external resources

{% data reusables.repositories.autolink-references %}

## Uploading assets

You can upload assets like images by dragging and dropping, selecting from a file browser, or pasting. You can upload assets to issues, pull requests, comments, and `.md` files in your repository.

## Using emojis

You can add emoji to your writing by typing `:EMOJICODE:`, a colon followed by the name of the emoji.

`@octocat :+1: This PR looks great - it's ready to merge! :shipit:`

![Screenshot of rendered GitHub Markdown showing how emoji codes for +1 and shipit render visually as emoji.](/assets/images/help/writing/emoji-rendered.png)

Typing <kbd>:</kbd> will bring up a list of suggested emoji. The list will filter as you type, so once you find the emoji you're looking for, press **Tab** or **Enter** to complete the highlighted result.

For a full list of available emoji and codes, see [the Emoji-Cheat-Sheet](https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md).

## Paragraphs

You can create a new paragraph by leaving a blank line between lines of text.

## Footnotes

You can add footnotes to your content by using this bracket syntax:

```text
Here is a simple footnote[^1].

A footnote can also have multiple lines[^2].

[^1]: My reference.
[^2]: To add line breaks within a footnote, prefix new lines with 2 spaces.
  This is a second line.
```

The footnote will render like this:

![Screenshot of rendered Markdown showing superscript numbers used to indicate footnotes, along with optional line breaks inside a note.](/assets/images/help/writing/footnote-rendered.png)

> [!NOTE]
> The position of a footnote in your Markdown does not influence where the footnote will be rendered. You can write a footnote right after your reference to the footnote, and the footnote will still render at the bottom of the Markdown. Footnotes are not supported in wikis.

## Alerts

Alerts are a Markdown extension based on the blockquote syntax that you can use to emphasize critical information. On {% data variables.product.github %}, they are displayed with distinctive colors and icons to indicate the significance of the content.

Use alerts only when they are crucial for user success and limit them to one or two per article to prevent overloading the reader. Additionally, you should avoid placing alerts consecutively. Alerts cannot be nested within other elements.

To add an alert, use a special blockquote line specifying the alert type, followed by the alert information in a standard blockquote. Five types of alerts are available:

```markdown
> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```

Here are the rendered alerts:

![Screenshot of rendered Markdown alerts showing how Note, Tip, Important, Warning, and Caution render with different colored text and icons.](/assets/images/help/writing/alerts-rendered.png)

## Hiding content with comments

You can tell {% data variables.product.github %} to hide content from the rendered Markdown by placing the content in an HTML comment.

```text
<!-- This content will not appear in the rendered Markdown -->
```

## Ignoring Markdown formatting

You can tell {% data variables.product.github %} to ignore (or escape) Markdown formatting by using <kbd>\\</kbd> before the Markdown character.

`Let's rename \*our-new-project\* to \*our-old-project\*.`

![Screenshot of rendered GitHub Markdown showing how backslashes prevent the conversion of asterisks to italics.](/assets/images/help/writing/escaped-character-rendered.png)

For more information on backslashes, see Daring Fireball's [Markdown Syntax](https://daringfireball.net/projects/markdown/syntax#backslash).

> [!NOTE]
> The Markdown formatting will not be ignored in the title of an issue or a pull request.

## Disabling Markdown rendering

{% data reusables.repositories.disabling-markdown-rendering %}

## Further reading

* [{% data variables.product.prodname_dotcom %} Flavored Markdown Spec](https://github.github.com/gfm/)
* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/about-writing-and-formatting-on-github)
* [AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting)
* [AUTOTITLE](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/quickstart-for-writing-on-github)

 docs/troubleshooting.md

New file
@@ -0,0 +1,19 @@
---
title: Troubleshooting
date: 2026-01-16T08:00:00.000+0700
---

## Sorry, but "$FEATURE does not work" doesn't work for us

Long story short, ask yourself: If you start bleeding out of all your orifices, will you tell the doctor "Doctor please help, I am quite new to this whole health thing and know you will laugh about me but I suddenly started bleeding out of all my orifices."? Or will you tell the doctor "Doctor, after ingesting a couple of razor blades I suddenly started bleeding. The razor blades were quite sharp. Can you help me?"

In open source communities like ours reporting issues clearly helps everyone. A message like *"the homepage doesn’t work"* might feel like a good starting point, but without more detail, it leaves us guessing. Some problems come from Hugo itself, others from the Ananke theme, or even from how it's configured - so the more info you share, the faster we can figure it out together.

When reporting a bug or asking for help, please include:
* **Versions**: your Hugo version, the version of the Ananke theme (and how you installed it), and your operating system.
* **Configuration**: your full `hugo.toml` or `hugo.yaml` file or configuration folder, plus any relevant folder structure or module settings. Note that this can be `hugo.ext`, `config.ext`, or even a full folder `config` with several sub levels. Hugo is flexible.
* **Steps**: what you were trying to do, what you expected to happen, and what actually happened instead.
* **Output**: the full error messages from the command line—don’t just paste the last line.
* **Extras**: logs, browser details (for visual issues), screenshots are very much appreciated and help to put words into visual or, if something looks wrong, make that clear - anything that might help us reproduce the problem.

The more complete the picture, the more likely it is that someone in the community will jump in and help quickly. You're not just helping yourself—you’re making the project better for everyone.

 frontmatter.json

New file
@@ -0,0 +1,12 @@
{
  "$schema": "https://frontmatter.codes/frontmatter.schema.json",
  "frontMatter.framework.id": "hugo",
  "frontMatter.content.publicFolder": "static",
  "frontMatter.preview.host": "http://localhost:1313",
  "frontMatter.content.pageFolders": [
    {
      "title": "docs",
      "path": "[[workspace]]/docs"
    }
  ]
}

 package.json

@@ -47,7 +47,8 @@
  "scripts": {
    "release": "wireit",
    "release:minor": "wireit",
    "release:pre": "wireit"
    "release:pre": "wireit",
    "server": "wireit"
  },
  "wireit": {
    "release": {
@@ -58,6 +59,9 @@
    },
    "release:pre": {
      "command": "commit-and-tag-version --sign -a -t \"v\" --releaseCommitMessageFormat \"chore(release): v{{currentTag}}\" --prerelease prerelease -- --no-verify"
    },
    "server": {
      "command": "cd site && HUGO_MODULE_REPLACEMENTS=\"github.com/theNewDynamic/gohugo-theme-ananke/v2 -> /home/patrick/github.com/davidsneighbour/gohugo-theme-ananke/\" hugo server"
    }
  }
}

 site/.gitignore

New file
@@ -0,0 +1,3 @@
.hugo_build.lock
public
resources

 site/README.md

New file
@@ -0,0 +1,11 @@
# Ananke Wiki Demo Site

This Hugo site renders the wiki content stored in the repository `docs/` directory
using the Ananke theme via Hugo modules.

Run locally (after installing Hugo):

```sh
cd site
hugo server
```

 site/archetypes/default.md

New file
@@ -0,0 +1,8 @@
---
title: '{{ replace .File.ContentBaseName "-" " " | title }}'
description: ""
date: "{{ .Date }}"
tags: []
featured_image: ""
weight: 100
---

 site/go.mod

New file
@@ -0,0 +1,5 @@
module github.com/davidsneighbour/gohugo-theme-ananke

go 1.21

require github.com/theNewDynamic/gohugo-theme-ananke/v2 v2.12.1 // indirect

 site/go.sum

New file
@@ -0,0 +1,2 @@
github.com/theNewDynamic/gohugo-theme-ananke/v2 v2.12.1 h1:SxVd2+ADMcMiNSsCnAdBnoMMZAUfwHDCvDExZ5fRseo=
github.com/theNewDynamic/gohugo-theme-ananke/v2 v2.12.1/go.mod h1:+a6uqEsCq0+rqHWY5W5QA3P9DNnxcbyCw+CVEB+Uveg=

 site/hugo.toml

New file
@@ -0,0 +1,17 @@
baseURL = "/"
languageCode = "en-us"
title = "Ananke Documentation"
contentDir = "../docs"
enableRobotsTXT = true

[params]
description = "Documentation for the GoHugo Ananke theme."

[params.ananke.home]
content_alignment = "left" #options: left, center, right

[module]
replacements = ["github.com/theNewDynamic/gohugo-theme-ananke/v2 -> /home/patrick/github.com/davidsneighbour/gohugo-theme-ananke/"]

[[module.imports]]
path = "github.com/theNewDynamic/gohugo-theme-ananke/v2"

 site/layouts/_shortcodes/page-index.html

New file
@@ -0,0 +1,19 @@
{{ $pagesBySection := site.RegularPages.GroupBy "Section" }}
{{ $sortedSections := slice }}

{{ range $pagesBySection }}
  {{ $sectionPage := page.GetPage .Key }}
  {{ $sortedSections = $sortedSections | append (dict "sectionPage" $sectionPage "pages" .Pages) }}
{{ end }}

{{ range sort $sortedSections "sectionPage.Weight" }}
  <h3>{{ .sectionPage.Title }}</h3>

  <ul>
      {{ range .pages }}
      <li>
        <a href="{{ .Permalink }}">{{ .Title }}</a>
      </li>
      {{ end }}
  </ul>
{{ end }}

 site/partials/site-scripts.html

New file
@@ -0,0 +1,3 @@
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Roboto+Condensed:ital,wght@0,100..900;1,100..900&family=Roboto:ital,wght@0,100..900;1,100..900&display=swap" rel="stylesheet">

 site/static/assets/styles.css

New file
@@ -0,0 +1,38 @@
.roboto {
    font-family: "Roboto", sans-serif;
    font-optical-sizing: auto;
    font-weight: 400;
    font-style: normal;
    font-variation-settings:
        "wdth" 100;
}

.roboto-condensed {
    font-family: "Roboto Condensed", sans-serif;
    font-optical-sizing: auto;
    font-weight: 600;
    font-style: normal;
    text-transform: uppercase;
}

body {
    font-family: "Roboto", sans-serif;
    font-optical-sizing: auto;
    font-weight: 400;
    font-style: normal;
    font-variation-settings:
        "wdth" 100;
}

h1,
h2,
h3,
h4,
h5,
h6 {
    font-family: "Roboto Condensed", sans-serif;
    font-optical-sizing: auto;
    font-weight: 600;
    font-style: normal;
    text-transform: uppercase;
}