### Build and Deploy Hugo Site

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Commands and configuration examples for building and deploying a Hugo site using the Blist theme. Includes development server start, production builds with optimization, and deployment configurations for Netlify and Vercel.

```bash
# Development build with live reload
npm start

# Production build with CSS purging and minification
NODE_ENV=production hugo --gc

# Or use the npm script
npm run build

# For Netlify/Vercel deployment, use this build command:
npm i && HUGO_ENVIRONMENT=production hugo --gc
```

```toml
# netlify.toml example
[build]
  publish = "public"
  command = "npm i && HUGO_ENVIRONMENT=production hugo --gc"

[build.environment]
  HUGO_VERSION = "0.124.0"
  NODE_VERSION = "18"

[context.production.environment]
  HUGO_ENV = "production"
```

```json
# vercel.json example
{
  "build": {
    "env": {
      "HUGO_VERSION": "0.124.0"
    }
  },
  "buildCommand": "npm i && HUGO_ENVIRONMENT=production hugo --gc",
  "outputDirectory": "public"
}
```

--------------------------------

### NPM Scripts for Hugo Development and Build

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Reference for available NPM scripts provided by the Blist Hugo theme for managing development and production builds. Includes commands for starting the development server with live reload and creating optimized production builds.

```json
{
  "scripts": {
    "start": "hugo server --disableFastRender",
    "build": "NODE_ENV=production hugo --gc"
  }
}
```

```bash
# Start development server
# - Runs Hugo server with live reload
# - Accessible at http://localhost:1313
# - Disables fast render for accurate preview
npm start

# Production build
# - Enables CSS purging (removes unused Tailwind classes)
# - Runs garbage collection (--gc)
# - Optimizes for deployment
npm run build

# Preview example site
cd themes/blist/exampleSite
hugo serve --themesDir ../..
```

--------------------------------

### Preview Blist Theme with Example Content

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/README.md

These commands are used to preview the Blist theme with its example content. It involves copying package.json, installing dependencies, and serving the site locally.

```sh
cd themes/blist/exampleSite/
hugo serve --themesDir ../..
```

--------------------------------

### Custom HTML Partials for Layouts

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Examples of custom HTML partials used within the theme's layout system. The 'intro.html' partial demonstrates how to implement the homepage hero section, incorporating dynamic content and accent colors. The 'blog-card.html' partial is mentioned for its role in displaying blog post summaries.

```html
<!-- layouts/partials/intro.html - Homepage hero section -->
<section class="{{ .Site.Params.ascentColor | default "bg-pink-50" }} dark:bg-gray-900">
  <div class="container max-w-screen-lg mx-auto px-6 py-12 grid md:grid-cols-2 gap-4 lg:gap-16 items-center">
    <div>
      <h1 class="text-4xl font-bold mb-4">{{ .Site.Params.introTitle | safeHTML}}</h1>
      <p class="font-light text-lg">{{ .Site.Params.introSubtitle | safeHTML}}</p>
    </div>
    <img class="rounded-lg shadow-sm" src="{{ .Site.Params.introPhoto }}" alt="{{ .Site.Title }}" />
  </div>
</section>
```

```html
<!-- layouts/partials/blog-card.html - Blog post card component -->
<!-- Automatically displays post thumbnail, title, date, and summary -->
<!-- Used on homepage and blog list pages -->
```

--------------------------------

### Enable LaTeX Math Support

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Configuration and markdown example for enabling LaTeX math notation within Hugo posts using the Blist theme. This involves enabling passthrough for math delimiters in the Goldmark parser and setting the `math` front matter to true for individual posts.

```toml
# In hugo.toml, enable passthrough for math delimiters
[markup.goldmark.extensions]
  [markup.goldmark.extensions.passthrough]
    enable = true
    [markup.goldmark.extensions.passthrough.delimiters]
      block = [['\[', ']'], ['$$', '$$']]
      inline = [['\(', '\)']]
```

```markdown
---
title: "Advanced Mathematics"
math: true
---

Inline math: The famous equation \( E = mc^2 \) describes mass-energy equivalence. 

Block math:
$$ 
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} 
$$

Another block example:
\[ 
\frac{d}{dx}\left( \int_{0}^{x} f(u)\,du\right)=f(x) 
\]
```

--------------------------------

### Enable Table of Contents

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Configuration and markdown example for enabling automatic table of contents generation in Hugo posts using the Blist theme. This can be set site-wide via parameters or individually for each post using front matter.

```toml
# Site-wide setting
[params]
  toc = true
```

```markdown
---
title: "Long Article"
toc: true  # Enable for this post
---

## Section 1
Content here...

## Section 2
More content...

### Subsection 2.1
Details...
```

--------------------------------

### Install Blist Theme and Dependencies with Git and npm

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Clone the Blist theme into your Hugo project's themes directory as either a direct clone or git submodule, then install Node.js dependencies including npm packages and PostCSS CLI for development. This sets up the complete environment needed to run the theme with Tailwind CSS processing.

```bash
# Clone theme into themes directory
git clone https://github.com/apvarun/blist-hugo-theme.git themes/blist

# Or add as git submodule
git submodule add https://github.com/apvarun/blist-hugo-theme.git themes/blist

# Copy package files to project root
cp themes/blist/package.json ./
cp themes/blist/package-lock.json ./

# Install dependencies
npm install

# Install PostCSS CLI globally
npm i -g postcss-cli

# Start development server
npm start
```

--------------------------------

### Create New Blog Posts with Hugo CLI

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Use the Hugo CLI to generate new blog post files. This command creates a new markdown file in the specified directory, ready for content and front matter.

```bash
# Create new post
hugo new blog/my-first-post/index.md

```

--------------------------------

### Hugo Highlight Shortcode Example

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/de/blog/markdown-syntax.md

Illustrates the use of Hugo's internal 'highlight' shortcode for rendering HTML code blocks. This method allows for language-specific syntax highlighting within Hugo sites.

```html
{{< highlight html >}}

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>
{{< /highlight >}}
```

--------------------------------

### HTML Code Block Example

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/de/blog/markdown-syntax.md

Demonstrates an HTML code block enclosed in backticks. This is a common way to display code snippets in Markdown, preserving formatting and syntax highlighting.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Example HTML5 Document</title>
  </head>
  <body>
    <p>Test</p>
  </body>
</html>
```

--------------------------------

### Hugo Content Structure

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Demonstrates the standard directory structure for organizing content in a Hugo project using the Blist theme. It shows how to manage multilingual content, blog posts, static pages, and global assets like images and favicons.

```text
content/
├── en/                    # English content (if multilingual)
│   ├── blog/             # Blog posts section
│   │   ├── _index.md     # Blog section index
│   │   ├── post-1/
│   │   │   ├── index.md
│   │   │   └── featured.jpg
│   │   └── post-2/
│   │       └── index.md
│   └── page/             # Static pages
│       └── about/
│           └── index.md
└── de/                    # German content (if multilingual)
    └── blog/
        └── ...

static/
├── images/               # Global images
├── favicon.svg
└── logo.png
```

--------------------------------

### Configure Multilingual Site Support in Hugo

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Set up multiple languages for your Hugo site by defining language configurations, content directories, and menu items for each language. This ensures your site can be served in different languages to a global audience.

```toml
DefaultContentLanguage = "en"
DefaultContentLanguageInSubdir = true

[languages]
  [languages.en]
    contentDir = "content/en"
    weight = 1
    languageName = "English"
    [languages.en.params]
      introTitle = "Welcome to My Blog"
      introSubtitle = "Developer and content creator"
      introPhoto = "/picture.jpg"
      logo = "/logo-en.png"

    [[languages.en.menu.main]]
      name = "Blog"
      url = "blog"
      weight = 1

    [[languages.en.menu.main]]
      name = "About"
      url = "page/about/"
      weight = 2

  [languages.de]
    contentDir = "content/de"
    weight = 2
    languageName = "Deutsch"
    title = "Mein Blog"
    [languages.de.params]
      description = "Entwickler und Content-Ersteller"
      introTitle = "Willkommen auf meinem Blog"
      introSubtitle = "Entwickler und Content-Ersteller"
      introPhoto = "/picture.jpg"
      logo = "/logo-de.png"

    [[languages.de.menu.main]]
      name = "Blog"
      url = "blog"
      weight = 1

  [languages.fr]
    contentDir = "content/fr"
    weight = 3
    languageName = "Français"
    [languages.fr.params]
      introTitle = "Bienvenue sur mon blog"
      introSubtitle = "Développeur et créateur de contenu"
      introPhoto = "/picture.jpg"

```

--------------------------------

### Configure and Build Blist Theme Locally

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/README.md

Steps to configure the Blist theme for a Hugo website locally. This includes copying configuration files, installing Node.js packages, and setting up PostCSS.

```sh
npm i
npm i -g postcss-cli
```

--------------------------------

### Configure Social Links on Homepage in Hugo

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Add social media links to your homepage by configuring the `params.homepage.social` section in your Hugo configuration file. Supports various platforms and custom links.

```toml
[params.homepage.social]
  title = "Follow me"
  description = "Connect with me on social media"

  [[params.homepage.social.icons]]
    website = "github"
    url = "https://github.com/yourusername"

  [[params.homepage.social.icons]]
    website = "x"
    url = "https://x.com/yourusername"

  [[params.homepage.social.icons]]
    website = "linkedin"
    url = "https://linkedin.com/in/yourusername"

  [[params.homepage.social.icons]]
    website = "email"
    url = "mailto:your@email.com"

  [[params.homepage.social.icons]]
    website = "medium"
    url = "https://medium.com/@yourusername"

  [[params.homepage.social.icons]]
    website = "youtube"
    url = "https://youtube.com/@yourusername"

  [[params.homepage.social.icons]]
    website = "instagram"
    url = "https://instagram.com/yourusername"

  [[params.homepage.social.icons]]
    website = "mastodon"
    url = "https://mastodon.social/@yourusername"

  [[params.homepage.social.icons]]
    website = "reddit"
    url = "https://reddit.com/u/yourusername"

  [[params.homepage.social.icons]]
    website = "stackoverflow"
    url = "https://stackoverflow.com/users/12345/yourusername"

  [[params.homepage.social.icons]]
    website = "buymeacoffee"
    url = "https://www.buymeacoffee.com/yourusername"

  [[params.homepage.social.icons]]
    website = "address"
    url = "Your Name<br/>123 Main Street<br/>City, Country"

```

--------------------------------

### Configure Blog Post Front Matter in Hugo

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Define metadata for your Hugo blog posts using front matter, including title, description, date, author, tags, and categories. Optional parameters like `math`, `toc`, `hideMeta`, `hidePageThumbnail`, and `thumbnail` can also be set.

```markdown
+++
title = "My First Blog Post"
description = "A comprehensive guide to getting started"
date = 2024-01-15T10:00:00Z
author = "Your Name"
tags = ["hugo", "blogging", "web-development"]
categories = ["Tutorial"]
draft = false

# Optional: Enable math support for this post
math = true

# Optional: Override site-level settings
toc = true
hideMeta = false
hidePageThumbnail = false

# Optional: Featured image
thumbnail = "featured.jpg"
+++

Your content goes here. The theme supports full Markdown syntax including:

## Headers

### Code blocks with syntax highlighting

```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}
greet("World");
```

### Mathematical notation (when math = true)

Inline math: \( E = mc^2 \)

Block math:
$$

\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$


### Images

![Alt text](/images/example.jpg)

### Lists, tables, and more...

```

--------------------------------

### Integrate Comment Systems (giscus, utterances, Disqus) in Hugo

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Configure comment systems for your Hugo site by setting the `system` parameter and providing necessary details for the chosen service. Supports giscus, utterances, and native Disqus integration.

```toml
# Using giscus (GitHub Discussions-based comments)
[params.comments]
  system = "giscus"
  repo = "username/repository"
  repoid = "R_kgDOHxxxxxxx"
  category = "Announcements"
  categoryid = "DIC_kwDOHxxxxxxx"
  mapping = "pathname"
  strict = "0"
  reactionsenabled = "1"
  emitmetadata = "0"
  inputposition = "bottom"
  theme = "preferred_color_scheme"

# Using utterances (GitHub Issues-based comments)
[params.comments]
  system = "utterances"
  repo = "username/repository"
  issueterm = "pathname"
  theme = "github-light"

# Using Disqus (Hugo native support)
[params.comments]
  system = "disqus"

[services.disqus]
  shortname = "your-disqus-shortname"

```

--------------------------------

### Configure Blist Theme in hugo.toml

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Set up essential Blist theme parameters in hugo.toml including site metadata, dark mode toggle, search functionality, accent colors, homepage content, menu items, syntax highlighting, and Google Analytics integration. This configuration file controls all major theme features and customization options.

```toml
baseurl = "https://yourblog.com"
title = "My Blog"
theme = "blist"

# Enable JSON output for search functionality
[outputs]
  home = ["HTML", "RSS", "JSON"]

[params]
  # Enable dark mode toggle
  darkModeToggle = true

  # Enable search feature
  enableSearch = true

  # Customize accent color (Tailwind CSS colors)
  ascentColor = "bg-blue-100"

  # Homepage intro section
  introTitle = "Welcome to My Blog"
  introSubtitle = "I write about technology, coding, and web development"
  introPhoto = "/profile.jpg"

  # Optional: Use logo instead of site title
  logo = "/logo.png"

  # Show table of contents on posts
  toc = true

  # Custom copyright text
  copyright = "Copyright © 2024 - Your Name · All rights reserved"

  # Favicon
  favicon = "/favicon.svg"

  # Content bundle shown on homepage
  frontBundle = "blog"

  # Hide post metadata (date, reading time, word count)
  hideMeta = false

  # Hide page thumbnails in single post view
  hidePageThumbnail = false

# Add menu items
[[menu.main]]
  name = "Blog"
  url = "/blog"
  weight = 1

[[menu.main]]
  name = "About"
  url = "/about"
  weight = 2

[[menu.main]]
  name = "Tags"
  url = "/tags"
  weight = 3

# Syntax highlighting configuration
[markup]
  [markup.highlight]
    style = "dracula"
  [markup.goldmark.renderer]
    unsafe = true

# Google Analytics
[services.googleAnalytics]
  ID = "G-XXXXXXXXXX"
```

--------------------------------

### Indented Code Block Example

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/de/blog/markdown-syntax.md

Shows an HTML code block indented with four spaces. This method is also supported by Markdown for displaying code but may be less visually distinct than backticks.

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>
```

--------------------------------

### Implement Search with Fuse.js and Keyboard Shortcuts

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Configure Fuse.js search options in assets/js/search.js with fuzzy matching parameters including location, distance, threshold, and indexed keys. Users can trigger search via search icon click or keyboard shortcuts (Ctrl+/ or Cmd+/), navigate results with arrow keys, and close with ESC. Results display up to 5 matches.

```javascript
// The search implementation uses Fuse.js for fuzzy search
// Users can trigger search by:
// 1. Clicking the search icon in header
// 2. Pressing Ctrl+/ or Cmd+/ keyboard shortcut

// Search options (from assets/js/search.js)
var options = {
  shouldSort: true,
  location: 0,
  distance: 100,
  threshold: 0.4,
  minMatchCharLength: 2,
  keys: [
    'title',
    'permalink',
    'contents'
  ]
};

// Search results display up to 5 matches
// Navigation through results with arrow keys (up/down)
// ESC key closes the search overlay
```

--------------------------------

### Configure Search Functionality with Fuse.js

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Enable and configure the Blist theme's search feature by enabling search in parameters, defining searchable fields in hugo.toml, and ensuring JSON output is enabled. The theme uses Fuse.js for fuzzy search with configurable options including threshold, distance, and key fields for search indexing.

```toml
[params]
  # Enable search
  enableSearch = true

  # Configure which fields to index for search
  searchKeys = [
    "tags",
    "date",
    "categories",
    "summary",
    "content",
    "link",
    "author"
  ]

# Required: Enable JSON output
[outputs]
  home = ["HTML", "RSS", "JSON"]
```

--------------------------------

### Render Inline Math Expressions in Markdown

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/en/blog/math-typesetting.md

Demonstrates how to include inline LaTeX math expressions within Markdown content using KaTeX. The example shows a simple inline equation using standard LaTeX syntax.

```markdown
Inline math: \(\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…\)
```

--------------------------------

### Customize Accent Color

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Configuration for customizing the accent color of the theme using Tailwind CSS background color classes. This affects elements like the homepage intro section background and blog card hover states.

```toml
[params]
  # Any Tailwind CSS background color class
  # Examples: bg-blue-100, bg-pink-50, bg-green-100, bg-purple-100
  ascentColor = "bg-blue-100"

  # The accent color is used for:
  # - Homepage intro section background
  # - Blog card hover states
  # - Interactive elements
```

--------------------------------

### Enable Dark Mode Toggle

Source: https://context7.com/apvarun/blist-hugo-theme/llms.txt

Configuration to enable the dark mode toggle button in the theme's header. This setting allows users to switch between light and dark themes, with preferences persisted using localStorage. Tailwind CSS dark mode classes are utilized for styling.

```toml
[params]
  # Enable dark mode toggle button in header
  darkModeToggle = true
```

```javascript
// Dark mode preference is automatically saved to localStorage
// Users can toggle between light/dark modes
// System preference is respected on first visit
// The toggle icon appears in the header navigation

// Tailwind dark mode classes are used throughout:
// - bg-white dark:bg-gray-800
// - text-gray-900 dark:text-white
// - border-gray-200 dark:border-gray-700
```

--------------------------------

### Generate Main Navigation Menu Items in Hugo

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/header.html

Iterates through the site's main menu items and renders each as a markdown link. Uses Hugo's range function to loop through .Site.Menus.main and applies the relLangURL filter to ensure URLs respect the current language context in multilingual setups.

```Hugo Template
{{ range .Site.Menus.main }}*   [{{ .Name }}]({{ .URL | relLangURL }})
{{ end }}
```

--------------------------------

### Render Block Math Expressions in Markdown

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/en/blog/math-typesetting.md

Illustrates how to render block-level LaTeX math equations in Markdown using KaTeX. This example uses double dollar signs for a separate paragraph equation.

```markdown
$$\varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } }$$
```

--------------------------------

### Build Hugo Site for Production with Blist Theme

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/README.md

This command builds the Hugo site for production using the Blist theme, enabling CSS purging for optimized performance. It's commonly used for deployment on platforms like Netlify or Vercel.

```sh
npm i && HUGO_ENVIRONMENT=production hugo --gc
```

--------------------------------

### Hugo Alternative Output Formats and Partials Inclusion

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/head.html

Iterates through alternative output formats for the site, printing a link to each with its associated media type and permalink. It also includes common site-wide partials for Open Graph, Twitter Cards, and schema markup, essential for SEO and social sharing.

```gohtml
{{ range .AlternativeOutputFormats -}} {{ printf `` .Rel .MediaType.Type .Permalink $.Site.Title | safeHTML }} {{ end }} {{ partial "opengraph.html" . }} {{ partial "twitter_cards.html" . }} {{ partial "schema.html" . }}
```

--------------------------------

### Configure Hugo for KaTeX Math Rendering

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/en/blog/math-typesetting.md

Enables KaTeX for math typesetting by configuring passthrough delimiters in Hugo's markup settings. Ensure the passthrough extension is enabled in your Hugo configuration file.

```yaml
markup:
  goldmark:
    extensions:
      passthrough:
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]
        enable: true
```

--------------------------------

### Hugo KaTeX CSS Integration for Mathematical Content

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/head.html

Conditionally fetches and processes KaTeX CSS from a CDN. It checks if the page has math content stored using '.Page.Store.Get "hasMath"'. If true, it constructs the KaTeX CSS URL (minified in production) and attempts to retrieve it. If retrieval fails, it throws an error. Successfully retrieved CSS is then copied and fingerprinted.

```gohtml
{{ $noop := .WordCount }} {{ if .Page.Store.Get "hasMath" }} {{ $katex_css_url := printf "https://cdn.jsdelivr.net/npm/katex@latest/dist/katex%s.css" (cond hugo.IsProduction ".min" "") -}} {{ with try (resources.GetRemote $katex_css_url) -}} {{ with .Err -}} {{ errorf "Could not retrieve KaTeX css file from CDN. Reason: %s." . -}} {{ else with.Value -}} {{ with resources.Copy (printf "css/katex%s.css" (cond hugo.IsProduction ".min" "")) . }} {{ $secureCSS := . | resources.Fingerprint "sha512" -}}  {{ end -}} {{ end -}} {{ end -}} {{ end }}
```

--------------------------------

### Hugo CSS Asset Processing with PostCSS and Minification

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/head.html

Processes a CSS file named 'styles.css' located in the 'css' directory using PostCSS with a configuration defined in './assets/css/'. If the site is not running in server mode, it further minifies, fingerprints, and post-processes the CSS. This ensures optimized and cached CSS for production.

```gohtml
{{ $styles := resources.Get "css/styles.css" | postCSS (dict "config" "./assets/css/") -}} {{- if hugo.IsServer }}  {{ else }} {{- $styles := $styles| minify | fingerprint | resources.PostProcess -}}  {{ end -}}
```

--------------------------------

### Clone Blist Hugo Theme

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/README.md

This command clones the Blist Hugo theme repository into the themes directory of your Hugo site.

```sh
git clone https://github.com/apvarun/blist-hugo-theme.git themes/blist
```

--------------------------------

### Enable JSON Output for Search in Hugo

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/README.md

This configuration snippet enables JSON output for the home page in Hugo, which is required for the theme's search functionality to generate the search index.

```toml
[outputs]
  home = ["HTML", "RSS", "JSON"]
```

--------------------------------

### Add Blist Hugo Theme as Git Submodule

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/README.md

This command adds the Blist Hugo theme as a Git submodule, which simplifies theme updates.

```sh
git submodule add https://github.com/apvarun/blist-hugo-theme.git themes/blist
```

--------------------------------

### Hugo Template Logic for Site Title and Home Page

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/head.html

Renders the page title followed by the site title, conditionally displaying the page title only if it's not the home page. It also includes logic for handling keywords and author parameters, though these are not explicitly displayed in this snippet.

```gohtml
{{ if not .IsHome }}{{ .Title }} - {{ end }}{{ site.Title }}  {{- if .Keywords }}  {{ end -}} {{- if .Params.Author }}  {{ end -}} {{ hugo.Generator }}
```

--------------------------------

### Hugo Template: Conditional Partial Rendering

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/footer.html

This Hugo template snippet demonstrates conditional rendering of partials. It checks if 'enableSearch' is true in site parameters to include the 'search-ui.html' partial, and always includes 'google_analytics.html'. It also checks if there are more than 3 languages configured to render language-specific UI.

```gohtml
{{ if .Site.Params.enableSearch }} {{- partial "search-ui.html" . -}} {{ end }} {{ partial "google_analytics.html" . }} {{ if ge (len .Site.Languages) 3 }}
```

--------------------------------

### Hugo Language Handling

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/head.html

Checks if the site has more than one language configured. This condition is typically used to conditionally render language switchers or other language-specific elements in the template.

```gohtml
{{ if gt (len .Site.Languages) 1}}  {{ end }}
```

--------------------------------

### Build Multilingual Language Switcher in Hugo

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/header.html

Conditionally renders a language switcher for multilingual Hugo sites. When 3+ languages exist, displays a grouped switcher; otherwise displays inline links. Uses Hugo's i18n function for label translation and excludes the current language from the list. Each language links to its corresponding language-specific URL path.

```Hugo Template
{{ if hugo.IsMultilingual }} {{ if ge (len .Site.Languages) 3 }}*   {{ i18n "languageSwitcherLabel" }}
    
    {{ range .Site.Languages }} {{ if not (eq .Lang $.Site.Language.Lang) }} [{{ default .Lang .LanguageName }}](/{{ .Lang }}/) {{ end }} {{ end }}
    
{{ else }}*   {{ range .Site.Languages }} {{ if not (eq .Lang $.Site.Language.Lang) }} [{{ default .Lang .LanguageName }}](/{{ .Lang }}/) {{ end }} {{ end }}
{{ end }} {{ end }}
```

--------------------------------

### Hugo: Generate Table of Contents from Headers

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/toc.html

This Go template code processes the content of a Hugo page to create a table of contents. It uses regular expressions to find headers (h1-h4), determine their levels, extract the header text, and generate anchor links. It handles nested headers to create a properly indented list. Dependencies include Hugo's template functions like `findRE`, `ge`, `index`, `seq`, `sub`, `add`, `replace`, `replaceRE`, `safeHTML`, and `Scratch`.

```go-template
{{- $headers := findRE "(.|\\n\\])+?" .Content -}} {{- $has_headers := ge (len $headers) 1 -}} {{- if $has_headers -}} {{- $largest := 6 -}} {{- range $headers -}} {{- $headerLevel := index (findRE "\\[1-4\\]" . 1) 0 -}} {{- $headerLevel := len (seq $headerLevel) -}} {{- if lt $headerLevel $largest -}} {{- $largest = $headerLevel -}} {{- end -}} {{- end -}} {{- $firstHeaderLevel := len (seq (index (findRE "\\[1-4\\]" (index $headers 0) 1) 0)) -}} {{- $.Scratch.Set "bareul" slice -}} Table of contents

{{- range seq (sub $firstHeaderLevel $largest) -}}

{{- $.Scratch.Add "bareul" (sub (add $largest .) 1) -}} {{- end -}} {{- range $i, $header := $headers -}} {{- $headerLevel := index (findRE "\\[1-4\\]" . 1) 0 -}} {{- $headerLevel := len (seq $headerLevel) -}} {{/\* get id=\"xyz\" \*/}} {{ $id := index (findRE "(id=\\\\"(.\\*?)\\\\\")" $header 9) 0 }} {{/\* strip id=\"\" to leave xyz (no way to get regex capturing groups in hugo :(\*/}} {{ $cleanedID := replace (replace $id "id=\\\\"" "") "\\\"" "" }} {{- $header := replaceRE "((.|\\n\\])+?)" "$1" $header -}} {{- if ne $i 0 -}} {{- $prevHeaderLevel := index (findRE "\\[1-4\\]" (index $headers (sub $i 1)) 1) 0 -}} {{- $prevHeaderLevel := len (seq $prevHeaderLevel) -}} {{- if gt $headerLevel $prevHeaderLevel -}} {{- range seq $prevHeaderLevel (sub $headerLevel 1) -}} {{/\* the first should not be recorded \*/}} {{- if ne $prevHeaderLevel . -}} {{- $.Scratch.Add "bareul" . -}} {{- end -}} {{- end -}} {{- else -}} {{- if lt $headerLevel $prevHeaderLevel -}} {{- range seq (sub $prevHeaderLevel 1) -1 $headerLevel -}} {{- if in ($.Scratch.Get "bareul") . -}} {{/\* manually do pop item \*/}} {{- $tmp := $.Scratch.Get "bareul" -}} {{- $.Scratch.Delete "bareul" -}} {{- $.Scratch.Set "bareul" slice}} {{- range seq (sub (len $tmp) 1) -}} {{- $.Scratch.Add "bareul" (index $tmp (sub . 1)) -}} {{- end -}} {{- else -}} {{- end -}} {{- end -}} {{- end -}} {{- end -}}*   [{{- $header | safeHTML -}}](#{{- $cleanedID -}}) {{- else -}}
*   [{{- $header | safeHTML -}}](#{{- $cleanedID -}}) {{- end -}} {{- end -}} {{ $firstHeaderLevel := $largest }} {{- $lastHeaderLevel := len (seq (index (findRE "\\[1-4\\]" (index $headers (sub (len $headers) 1)) 1) 0)) -}}
{{- range seq (sub $lastHeaderLevel $firstHeaderLevel) -}} {{- if in ($.Scratch.Get "bareul") (add . $firstHeaderLevel) -}}

{{- else -}} {{- end -}} {{- end -}} {{- end -}}
```

--------------------------------

### Render Conditional Logo and Site Title in Hugo

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/header.html

Conditionally displays either a logo image or plain text site title as a link to the homepage. Uses Hugo's if-else templating to check if a logo parameter exists in site configuration. The logo image alt text and link URL are both dynamically sourced from site parameters.

```Hugo Template
[{{ if .Site.Params.logo }} ![{{ .Site.Title }}]({{ .Site.Params.logo }}) {{ else }} {{ .Site.Title }} {{ end }}]({{ .Site.Home.Permalink }})
```

--------------------------------

### Hugo: Enable Emojis Globally

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/de/blog/emoji-support.md

Enables Unicode Standard emoji characters and sequences globally in Hugo by setting `enableEmoji` to `true` in the site configuration. This allows the use of emoji shorthand codes directly in content files. No external dependencies are required.

```yaml
enableEmoji: true
```

--------------------------------

### JavaScript: Dark Mode Toggle Functionality

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/footer.html

This JavaScript snippet implements a dark mode toggle. It allows users to switch between light and dark themes by adding/removing the 'dark' class from the document element and persisting the preference in local storage. It also respects the user's OS preference if no local storage value is found.

```javascript
// On page load or when changing themes
const darkmode = document.querySelector('.toggle-dark-mode');

function toggleDarkMode() {
    if (document.documentElement.classList.contains('dark')) {
        document.documentElement.classList.remove('dark')
        localStorage.setItem('darkmode', 'light')
    } else {
        document.documentElement.classList.add('dark')
        localStorage.setItem('darkmode', 'dark')
    }
}

if (darkmode) {
    darkmode.addEventListener('click', toggleDarkMode);
}

const darkStorage = localStorage.getItem('darkmode');
const isBrowserDark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;

if (!darkStorage && isBrowserDark) {
    document.documentElement.classList.add('dark');
}

if (darkStorage && darkStorage === 'dark') {
    toggleDarkMode();
}
```

--------------------------------

### Conditionally Enable Search and Dark Mode Toggle in Hugo

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/header.html

Renders search functionality and dark mode toggle buttons based on site configuration parameters. Uses Hugo's if conditionals to check enableSearch and darkModeToggle parameters from site configuration. Actual implementation details for search and dark mode are defined elsewhere in the theme.

```Hugo Template
{{ if .Site.Params.enableSearch }}

{{ end }} {{ if .Site.Params.darkModeToggle }}

{{ end }}
```

--------------------------------

### Hugo Template: Conditional Copyright Display

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/footer.html

This Hugo template snippet conditionally displays a copyright notice. If a 'copyright' parameter is set in the site's configuration, it uses that value. Otherwise, it displays the current year and the site's title.

```gohtml
{{ if (isset .Site.Params "copyright") }} {{ .Site.Params.copyright | safeHTML }} {{ else }} {{ dateFormat "2006" now }} © {{ .Site.Title }} {{ end }}
```

--------------------------------

### Hugo: Use Emojify Function

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/de/blog/emoji-support.md

Demonstrates calling the `emojify` function directly within Hugo templates or inline shortcodes. This function converts emoji shorthand codes (e.g., `:see_no_evil:`) into their corresponding emoji characters. No specific inputs or outputs are defined beyond the shorthand conversion.

```go-template
{{ emojify ":see_no_evil:" }}
```

--------------------------------

### CSS: Styling Emojis

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/de/blog/emoji-support.md

Provides CSS rules to ensure consistent emoji rendering across different platforms and browsers. It utilizes a font stack that prioritizes common emoji fonts. This snippet is intended for use in a project's CSS files or within `<style>` tags.

```css
.emoji {
font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols;
}
```

```css
.emojify {
font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols;
font-size: 2rem;
vertical-align: middle;
}
@media screen and (max-width:650px) {
  .nowrap {
    display: block;
    margin: 25px 0;
  }
}
```

--------------------------------

### JavaScript: Language Switcher Functionality

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/footer.html

This JavaScript code handles the functionality for a language switcher. It toggles the visibility of a language dropdown menu when a corresponding button is clicked. It relies on 'language-switcher' and 'language-dropdown' CSS classes for element selection.

```javascript
const languageMenuButton = document.querySelector('.language-switcher');
const languageDropdown = document.querySelector('.language-dropdown');
languageMenuButton.addEventListener('click', (evt) => {
    evt.preventDefault()
    if (languageDropdown.classList.contains('hidden')) {
        languageDropdown.classList.remove('hidden')
        languageDropdown.classList.add('flex')
    } else {
        languageDropdown.classList.add('hidden');
        languageDropdown.classList.remove('flex');
    }
})
```

--------------------------------

### Style Emoji with Custom Font Stack CSS

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/en/blog/emoji-support.md

CSS ruleset that applies a comprehensive font stack to emoji elements for consistent rendering across different browsers and operating systems. Includes responsive design adjustment for mobile devices to improve readability on smaller screens.

```css
.emoji {
  font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols;
}

.emojify {
  font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols;
  font-size: 2rem;
  vertical-align: middle;
}

@media screen and (max-width:650px) {
  .nowrap {
    display: block;
    margin: 25px 0;
  }
}
```

--------------------------------

### JavaScript: Mobile Menu Toggle Functionality

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/layouts/partials/footer.html

This JavaScript code manages a mobile menu. It toggles the 'hidden' and 'flex' CSS classes on a mobile menu element when a corresponding mobile menu button is clicked, effectively showing or hiding the menu.

```javascript
const mobileMenuButton = document.querySelector('.mobile-menu-button')
const mobileMenu = document.querySelector('.mobile-menu')

function toggleMenu() {
    mobileMenu.classList.toggle('hidden');
    mobileMenu.classList.toggle('flex');
}

if(mobileMenu && mobileMenuButton){
    mobileMenuButton.addEventListener('click', toggleMenu)
}
```

--------------------------------

### Use Emojify Function in Hugo Templates

Source: https://github.com/apvarun/blist-hugo-theme/blob/main/exampleSite/content/en/blog/emoji-support.md

Hugo template function that converts emoji shorthand codes to their Unicode representations. Can be called directly in templates or used within inline shortcodes to render emoji from text codes.

```hugo
{{ emojify ":see_no_evil:" }}
{{ emojify ":hear_no_evil:" }}
{{ emojify ":speak_no_evil:" }}
```