hugo-theme-m10c

In Hugo, a 'skin' refers to the files responsible for the site's appearance (CSS, JavaScript, and HTML transformation rules). You can implement skins in two ways:

1. layouts/ directory: The simplest method. Hugo automatically looks here first, so no additional configuration is required. However, skins in layouts/ cannot be easily customized by end-users without modifying the core templates.
2. themes/ directory: A skin placed in a sub-directory of themes/ is considered a 'theme'. This allows for easier customization by others. If you use this method, you must specify the theme in your site's configuration file so Hugo knows where to search.

Use the layouts/ directory for site-specific overrides and the themes/ directory for reusable, distributable designs.

The theme supports two icon libraries:

1. Feather: Used for application-related icons. Use the icon name directly.
2. Simple Icons: Used for brand icons. To use these, you must prefix the icon name with brand- (e.g., brand-github, brand-x, brand-mastodon).

Hugo operates using two distinct mechanisms during site generation:

1. Templates: Hugo uses HTML files located in the layouts/ directory to transform content files into HTML pages. The layouts/index.html file is specifically used to generate the home page.
2. Static Files: Files located in the static/ directory (and theme-specific static/ directories) are copied exactly as they are into the public/ directory. They are not transformed by Hugo. It is common practice to organize these into static/css/ and static/js/ directories.

Hugo uses a hierarchical lookup for templates. If you want a specific layout for a certain content type (e.g., only for posts) without affecting the global default, create a template within a directory named after that content type inside layouts/.

Hierarchy Example:

1. layouts/_default/single.html: The fallback template for all single pages.
2. layouts/post/single.html: The specific template used only for content of type post.

By moving logic (like displaying a publication date) from _default/single.html to post/single.html, you ensure that only posts display that information, while other pages (like an 'about' page) remain unaffected.

# Directory structure for section templates
layouts/
  _default/
    single.html  <-- Default fallback
  post/
    single.html  <-- Specific to 'post' type

Hugo content files consist of two distinct sections:

1. Front Matter: Meta-information about the content (e.g., title, date, tags) that is passed to templates before rendering. It can be written in TOML, YAML, or JSON. Hugo identifies the format by markers:
   • TOML: Surrounded by +++
   • YAML: Surrounded by ---
   • JSON: Enclosed in {}
2. Markdown: The body of the content, which Hugo processes through a Markdown engine to generate HTML.

+++
title = "Example Post"
date = "2014-09-28"
+++

This is the Markdown content.

Hugo automatically generates a home page and looks for specific template files in the theme's layouts/ directory. It follows a hierarchy of specificity, searching for files in this order:

1. index.html (most specific)
2. _default/list.html
3. _default/single.html

To customize the home page, it is a best practice to update the most specific template available (usually index.html).

Go templates are HTML files that use double curly braces {{ }} to execute variables and functions.

• Variables/Functions: Accessed via {{ variable_name }} or {{ function_name arg1 arg2 }}.
• Parameters: Separated by spaces.
• Dot Notation: Used to access methods and fields (e.g., {{ .Params.bar }}).
• Grouping: Use parentheses to group logic (e.g., {{ if or (condition1) (condition2) }} ... {{ end }}).

<!-- Accessing a variable -->
{{ foo }}

<!-- Calling a function with parameters -->
{{ add 1 2 }}

<!-- Accessing a field via dot notation -->
{{ .Params.bar }}

<!-- Grouping logic with parentheses -->
{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}

When running the Hugo server with the --watch option, Hugo automatically injects a Live Reload script into your HTML files. This allows the browser to refresh automatically when content changes. The injected script typically looks like this:

<script>document.write('<script src="http://' + (location.host || 'localhost').split(':')[0] + ':1313/livereload.js?mindelay=10"></' + 'script>')</script>

Hugo uses templates to bridge content and presentation. There are three primary template types:

• Single Template: Renders a single piece of content (e.g., a specific blog post).
• List Template: Renders a group of related content (e.g., a list of recent posts or a category archive). The homepage is a special type of list template.
• Partial Template: Small, reusable templates that can be included within other templates using the partial command. These are ideal for common elements like banners or footers.

The dot . represents the current context.

Crucial Behavior: The value of . changes depending on where you are in the template. At the top level, it is the page/node struct. Inside a range loop, . is rebound to the current item in the iteration.

Best Practice: If you need to access top-level data (like .Site.Title) from inside a loop, save it to a variable before entering the loop.

{{ $title := .Site.Title }}
{{ range .Params.tags }}
  <!-- Inside the loop, '.' is the tag, not the site. We use '$title' to access the saved context -->
  <a href="{{ . | urlize }}">{{ . }}</a> - {{ $title }}
{{ end }}

Partials are reusable template snippets stored in the layouts/partials/ directory. Unlike standard template references that require a full path, partials are searched for by Hugo along a defined path, making them easy to override.

Syntax

• Template reference (full path): {{ template "theme/partials/header.html" . }}
• Partial call (shorthand): {{ partial "header.html" . }}

Always pass the current context (.) to the partial so it can access page data.

Pipes (|) allow you to stack actions. The output of one action becomes the input (as the last parameter) of the next. This is useful for chaining functions like escaping HTML or formatting strings.

<!-- Escaping a parameter value as HTML -->
{{ index .Params "disqus_url" | html }}

<!-- Chaining multiple logical checks -->
{{ isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" | if }}
    Stuff Here
{{ end }}