### First-Time Setup - Initialize submodules if needed

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Ensures all Git submodules are initialized and updated.

```bash
# Initialize submodules if needed
git submodule update --init --recursive
```

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

### First-Time Setup - Navigate to directory

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Changes the current directory to the cloned hugothemes repository.

```bash
# Navigate to directory
cd hugothemes
```

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

### First-Time Setup - Test with single theme

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Tests a specific theme by providing its Git repository URL.

```bash
# Test with single theme
_script/reviewTheme.sh https://github.com/user/theme.git
```

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

### GitHub Actions Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Example GitHub Actions workflow for building and deploying the Hugo themes showcase.

```yaml
name: Build Themes Showcase

on:
  push:
    branches: [ main ]
  schedule:
    - cron: '0 0 * * 0'  # Weekly

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true
          depth: 0
      
      - name: Build theme showcase
        run: ./buildThemeSite.sh https://themes.example.com
      
      - name: Deploy
        run: |
          # Push output to deployment service
          rsync -avz _script/hugoThemeSite/themeSite/public/ deploy@server:/var/www/
```

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

### First-Time Setup - Clone repository

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Clones the hugoThemes repository, including submodules.

```bash
# Clone repository
git clone --recursive https://github.com/gohugoio/hugoThemes.git
```

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

### Complete Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/configuration.md

A complete example of a `theme.toml` file.

```toml
name = "Awesome Blog Theme"
license = "MIT"
licenselink = "https://github.com/user/awesome-theme/blob/main/LICENSE"
description = "A clean, responsive blog theme with dark mode support and advanced customization options"
homepage = "https://github.com/user/awesome-theme"
tags = ["blog", "responsive", "dark-mode"]
features = ["responsive", "dark-mode", "search", "syntax-highlighting", "tags", "categories"]
min_version = "0.87.0"

authors = [
  {name = "Jane Developer", homepage = "https://jane.dev"},
  {name = "John Smith", homepage = "https://johnsmith.com"}
]

[original]
    author = "Original Designer"
    homepage = "https://originaldesigner.com"
    repo = "https://github.com/original/theme"
```

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

### Repository Setup for Build Scripts

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

Commands to clone the necessary repositories for setting up the theme showcase site and example content.

```bash
# Theme showcase site (templates, config)
git clone --recursive ${HUGO_THEME_SITE_REPO} themeSite

# Demo content (default content for themes)
git clone ${HUGO_BASIC_EXAMPLE_REPO} exampleSite
```

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

### Clone/update example content

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Clones the basic example site repository if it doesn't exist, or pulls updates if it does.

```bash
if [ -d exampleSite ]; then
    git pull --rebase
else
    git clone ${HUGO_BASIC_EXAMPLE_REPO} exampleSite
fi
```

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

### Base URL Configuration Examples

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/configuration.md

Bash examples for setting the BASEURL environment variable or as a command argument.

```bash
# As environment variable
export BASEURL=https://demo.example.com
./buildThemeSite.sh

# As command argument (takes precedence)
./buildThemeSite.sh https://demo.example.com
```

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

### Usage Examples for buildThemeSite.sh

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

Examples demonstrating how to use the buildThemeSite.sh script with different configurations.

```bash
BASEURL=http://themes.gohugo.io ./buildThemeSite.sh
```

```bash
./buildThemeSite.sh http://localhost:1313
```

```bash
export BASEURL=http://localhost:8080
./buildThemeSite.sh
```

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

### Complete theme.toml with Multiple Authors

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

An example of a comprehensive theme.toml including multiple authors and original author information.

```toml
name = "Advanced Theme"
license = "Apache-2.0"
licenselink = "https://github.com/user/theme/blob/main/LICENSE"
description = "Feature-rich theme for modern blogs"
homepage = "https://github.com/user/theme"
tags = ["blog", "portfolio", "responsive"]
features = ["dark-mode", "search", "comments", "syntax-highlighting"]
min_version = "0.95.0"

authors = [
  {name = "Alice Developer", homepage = "https://alice.dev"},
  {name = "Bob Smith", homepage = "https://bob.dev"}
]

[original]
    author = "Original Designer"
    homepage = "https://original.com"
    repo = "https://github.com/original/theme"
```

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

### Netlify Configuration

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Example Netlify configuration file (`netlify.toml`) for building and publishing the Hugo themes site.

```toml
[build]
  command = "./buildThemeSite.sh"
  publish = "_script/hugoThemeSite/themeSite/public"

[build.environment]
  BASEURL = "https://themes.gohugo.io"
```

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

### Theme Review Script Optimization Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

An example snippet demonstrating how the script reuses previously cloned themes to speed up iterative reviews.

```bash
if [ ! -d $cloneDest ]; then
    git clone --recursive $repoUrl $cloneDest
else
    echo "Found theme already at $cloneDest. Skip cloning"
fi
```

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

### Theme Review Script Usage Example 3

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

Example of how to review multiple themes sequentially using the reviewTheme.sh script.

```bash
./reviewTheme.sh https://github.com/user/theme1.git -t ./reviews
# After review, press Ctrl+C to stop server
./reviewTheme.sh https://github.com/user/theme2.git -t ./reviews
```

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

### Metadata Extraction Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

Example bash commands for extracting theme metadata.

```bash
title=$(echo "${x}" | tr "-" " " | awk '{for(i=1;i<=NF;i++)sub(/./,toupper(substr($i,1,1)),$i)}1')
repo=`git -C ${themesDir}/$x remote -v | head -n 1 | awk '{print$2}'`
themeCreated=`git log --reverse --pretty=format:"%ai" $x | head -1`
themeUpdated=`git log --pretty=format:"%ai" -n1`
```

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

### Theme Review Script Usage Example 1

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

Example of how to use the reviewTheme.sh script to review a theme using the default directory.

```bash
./reviewTheme.sh https://github.com/user/my-theme.git
```

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

### Usage Examples for try() function

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

Examples demonstrating the usage of the try() function.

```bash
try rm -rf themeSite/public
```

```bash
try git clone --recursive ${HUGO_THEME_SITE_REPO} themeSite
```

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

### Path A1: Whitelisted Theme (custom exampleSite/) - Directory setup

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Sets up symbolic links for a custom exampleSite and themes directory for a whitelisted theme.

```bash
ln -s ${themesDir}/$x/exampleSite ${siteDir}/exampleSite2
ln -s ${themesDir} ${siteDir}/exampleSite2/themes
```

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

### Theme Review Script Usage Example 2

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

Example of how to use the reviewTheme.sh script to review a theme in a custom directory.

```bash
./reviewTheme.sh https://github.com/user/my-theme.git -t /tmp/theme-reviews
```

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

### Test Build with Limited Themes

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Instructions to test the build process with a limited subset of themes for faster iteration.

```bash
# Copy subset of themes to test directory
mkdir -p /tmp/themes-test
cp -r academic beautiful-hugo docsy /tmp/themes-test/

# Set environment variable and build
cd /workspace/home/hugothemes
export HUGO_THEMES_REPO=/tmp/themes-test
_script/generateThemeSite.sh http://localhost:1313

# Much faster (only 3 themes)
```

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

### Faster Builds During Development

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Tips for speeding up builds during development, including selective theme builds and skipping demo generation.

```bash
# Build only new/modified themes
export HUGO_THEMES_REPO=/path/to/modified-themes-only
./generateThemeSite.sh

# Review single theme
./reviewTheme.sh https://github.com/user/theme.git

# Skip demo generation (metadata only)
# Edit generateThemeSite.sh and set generateDemo=false
```

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

### Demo Content Hierarchy Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

An example of the directory structure for a theme's demo content.

```tree
/theme/academic/
├── index.html                  # Homepage
├── about/                      # About page
│   └── index.html
├── publication/                # Publication listing
│   ├── index.html
│   └── 2024-study/
│       └── index.html
├── post/                       # Blog posts
│   ├── index.html
│   ├── getting-started/
│   │   └── index.html
│   └── second-post/
│       └── index.html
├── tags/                       # Tag pages
│   ├── index.html
│   └── hugo/
│       └── index.html
├── categories/                 # Category pages
│   ├── index.html
│   └── tutorial/
│       └── index.html
├── css/                        # Stylesheets
│   ├── main.css
│   └── ...
├── js/                         # JavaScript
│   ├── main.js
│   └── ...
├── images/                     # Demo images
│   └── ...
├── sitemap.xml                 # Demo sitemap
└── rss.xml                     # Demo feed
```

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

### Build Complete Theme Showcase

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Commands to build the complete theme showcase for production or local testing, and to view it locally.

```bash
cd /workspace/home/hugothemes

# Build for production
BASEURL=https://themes.gohugo.io ./buildThemeSite.sh

# Build for local testing
./buildThemeSite.sh http://localhost:1313

# View locally
hugo server -s _script/hugoThemeSite/themeSite
```

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

### Build Scripts Navigation

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Navigates to the directory containing build scripts.

```bash
cd /workspace/home/hugothemes/_script
```

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

### Clone Example Site

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/git-integration.md

Bash script snippet to clone the Hugo Basic Example repository or pull updates if it already exists.

```bash
if [ -d exampleSite ]; then
    pushd exampleSite
    git pull --rebase
    popd
else
    git clone ${HUGO_BASIC_EXAMPLE_REPO} exampleSite
fi
```

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

### View creation date

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Shows the creation date of a theme directory.

```bash
git log --reverse --pretty=format:"%ai" -- theme-name | head -1
```

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

### Single Author Example TOML Configuration

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/configuration.md

Example TOML configuration for a single author theme.

```toml
name = "Minimalist Theme"
license = "Apache-2.0"
licenselink = "https://github.com/user/minimal/blob/master/LICENSE"
description = "Ultra-lightweight theme focusing on typography and readability"
homepage = "https://github.com/user/minimal"
tags = ["blog", "minimal"]
features = ["responsive", "typography-focused"]
min_version = "0.59.1"

[author]
    name = "Alice Cooper"
    homepage = "https://alicecooper.dev"
```

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

### index.md Frontmatter Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

An example of the TOML frontmatter for an index.md file in the showcase content, detailing theme metadata.

```toml
+++
title = "Theme Name"
date = "2020-01-15T10:30:00Z"
lastmod = "2024-05-27T12:00:00Z"
source = "https://github.com/user/theme-repo"
demo = "/theme/theme-name/"
name = "Theme Name"
license = "MIT"
licenselink = "https://..."
description = "..."
homepage = "..."
tags = ["blog", "portfolio"]
features = ["responsive", "dark-mode"]
min_version = "0.59.1"
[author]
    name = "Author Name"
    homepage = "https://..."
+++

# Theme README content
...
```

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

### Quick Debug Workflow - Step 7: Verify output

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Lists the first 20 items in the public output directory.

```bash
# 7. Verify output
ls -la _script/hugoThemeSite/themeSite/public/ | head -20
```

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

### Test Locally

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Starts a local Hugo server to test the built themes.

```bash
cd _script/hugoThemeSite/themeSite
hugo server
```

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

### Monitor build progress

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Follows the build log in real-time to monitor progress.

```bash
tail -f build.log
```

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

### Clean Rebuild

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Commands to perform a clean rebuild of the theme site.

```bash
# Remove all generated files
cd _script
rm -rf hugoThemeSite

# Rebuild from scratch
./generateThemeSite.sh http://localhost:1313

# View final output
hugo server -s hugoThemeSite/themeSite
```

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

### Quick Debug Workflow - Step 4: Verify theme file

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Displays the first 20 lines of a theme's theme.toml file.

```bash
# 4. Verify theme file
cat hugothemes-theme-name/theme.toml | head -20
```

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

### Sitemap Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

Example of the XML sitemap generated for search engine crawling.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://themes.gohugo.io/</loc>
    <lastmod>2024-05-27T00:00:00+00:00</lastmod>
    <changefreq>daily</changefreq>
  </url>
  <url>
    <loc>https://themes.gohugo.io/theme/academic/</loc>
    <lastmod>2024-05-15T14:22:00Z</lastmod>
    <changefreq>weekly</changefreq>
  </url>
  <!-- ... 400+ theme entries ... -->
</urlset>
```

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

### Count showcase content pages

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Counts the number of content pages in the showcase.

```bash
ls -d _script/hugoThemeSite/themeSite/content/*/ | wc -l
```

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

### Check Logs

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Commands to check build and review logs for errors.

```bash
# Full build output
./buildThemeSite.sh 2>&1 | tee build.log
grep -i error build.log

# Single theme review
_script/reviewTheme.sh <url> 2>&1 | tee review.log
```

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

### Showcase Page Structure Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Markdown front matter structure for a theme's index.md file, including metadata and source links.

```markdown
+++
title = "Theme Display Name"
date = "2020-01-15T10:30:00Z"
lastmod = "2024-05-27T12:00:00Z"
source = "https://github.com/user/theme"
demo = "/theme/theme-name/"

# Theme.toml fields appended
name = "..."
license = "..."
... 
+++

# Theme README content follows
```

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

### Check README exists

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Verifies that a README.md file is present for the theme.

```bash
test -f {theme}/README.md && echo "Has README"
```

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

### Quick Debug Workflow - Step 2: View recent output

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Displays the last 100 lines of the build log.

```bash
# 2. View recent output
tail -100 build.log
```

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

### Individual Theme Navigation

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Navigates into a specific theme's directory.

```bash
cd /workspace/home/hugothemes/{theme-name}
```

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

### Set Hugo example site repository environment variable

Source: https://github.com/gohugoio/hugothemes/blob/master/_script/README.md

To alter the Hugo example site repository used, provide a value for the environment variable HUGO_EXAMPLE_SITE_REPO.

```bash
HUGO_EXAMPLE_SITE_REPO=<repo> ./generateThemeSite.sh http://localhost:1313
```

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

### Development Cycle - Make changes to a theme

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Steps to make edits, commit, and push changes to a theme's repository.

```bash
# Make changes to a theme
cd theme-name
# ... make edits ...
git add -A && git commit -m "Update theme"
git push
```

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

### Theme Submission Preparation

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Steps to prepare a theme for submission, including cloning, ensuring required files, and validation.

```bash
# Clone theme repository
git clone https://github.com/user/theme.git my-theme
cd my-theme

# Ensure required files
touch theme.toml README.md
mkdir -p images

# Validate with example content
git clone https://github.com/gohugoio/hugoBasicExample.git content
hugo server -t .

# When ready, open GitHub issue with repository link
```

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

### Quick Debug Workflow - Step 5: Test single theme

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Tests a single theme by providing its Git repository URL.

```bash
# 5. Test single theme
cd _script
./reviewTheme.sh https://github.com/user/theme.git
```

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

### Repository Configuration Environment Variables

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/configuration.md

Bash examples for setting environment variables to configure repository locations for the build system.

```bash
export HUGO_THEME_SITE_REPO=https://github.com/myorg/custom-themes-site.git
./buildThemeSite.sh
```

```bash
export HUGO_BASIC_EXAMPLE_REPO=https://github.com/myorg/example-content.git
./buildThemeSite.sh
```

```bash
export HUGO_THEMES_REPO=/tmp/new-themes-only
./buildThemeSite.sh http://localhost:1313
```

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

### Install all themes

Source: https://github.com/gohugoio/hugothemes/blob/master/README.md

Command to clone the entire repository of Hugo themes.

```bash
git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes
```

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

### Minimal Valid theme.toml

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

A basic template for a valid theme.toml file.

```toml
name = "My Theme"
license = "MIT"
licenselink = "https://github.com/user/theme/blob/main/LICENSE"
description = "A clean, responsive blog theme"
homepage = "https://github.com/user/theme"
tags = ["blog", "responsive"]
features = ["dark-mode"]
min_version = "0.87.0"

[author]
    name = "Your Name"
    homepage = "https://yourwebsite.com"
```

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

### Demo Base URL Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

The base URL format for a theme's demo site.

```text
https://themes.gohugo.io/theme/{theme-name}/
```

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

### README Transformation: Shortcode Escaping

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

Example of escaping shortcodes in README files.

```diff
Before: {{%include content%}}
After:  {{%/*include content*/%}}
```

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

### View recent changes

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Lists the last 10 commit logs for a theme directory.

```bash
git log --oneline -10 -- theme-name
```

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

### Check TOML syntax

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Verifies the presence of essential keys in the theme.toml file.

```bash
cat {theme}/theme.toml | grep -E '(^name|^license|^min_version)'
```

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

### View repository URL

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Displays the remote URL for a theme's repository.

```bash
git -C theme-name remote -v
```

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

### README Transformation: GitHub URL Rewriting

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

Example of rewriting GitHub image URLs in README files.

```diff
Before: ![Screenshot](github.com/user/theme/blob/master/images/screenshot.png)
After:  ![Screenshot](raw.githubusercontent.com/user/theme/master/images/screenshot.png)
```

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

### Run Hugo Server for Showcase

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Commands to run the Hugo server for the theme showcase, with an option to disable live reload.

```bash
cd /workspace/home/hugothemes/_script/hugoThemeSite/themeSite

# Start development server
hugo server

# Visit http://localhost:1313

# With live reload disabled (faster)
hugo server -l=false
```

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

### Single Theme Review

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Clones a theme, sets the HUGO_THEMES_REPO environment variable, and starts a Hugo server for reviewing a single theme.

```bash
_script/reviewTheme.sh https://github.com/user/theme.git
```

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

### Review Single Theme Before Submission

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Commands to review a single theme locally before submission, with options for a custom directory.

```bash
cd /workspace/home/hugothemes/_script

# Review theme (will clone if needed)
./reviewTheme.sh https://github.com/user/new-theme.git

# Or review in custom directory
./reviewTheme.sh https://github.com/user/new-theme.git -t /tmp/reviews

# View in browser at http://localhost:1313
```

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

### Add New Theme to Repository

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Steps to add a new theme to the repository using git submodules.

```bash
cd /workspace/home/hugothemes

# Add as git submodule
git submodule add https://github.com/user/theme.git theme-name

# Initialize
git submodule update --init --recursive

# Verify
git status  # Should show theme-name and .gitmodules modified

# Commit
git add .gitmodules theme-name
git commit -m "Add theme-name theme"
git push origin main
```

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

### Whitelist Configuration

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

List of themes using custom exampleSite/ content.

```bash
whiteList=(
  'academic'
  'reveal-hugo'
  'hugo-terrassa-theme'
  # ... (complete list in script lines 230)
)
```

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

### Theme.toml Processing: Version Normalization

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

Example of normalizing version strings in theme.toml.

```diff
Before: min_version = 0.20.1
After:  min_version = "0.20.1"
```

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

### Local Testing

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Commands to test a theme locally by cloning it and running the Hugo server.

```bash
cd ../_script
./reviewTheme.sh https://github.com/user/theme.git -t ./test
```

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

### Project Root Navigation

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Navigates to the root directory of the Hugo themes project.

```bash
cd /workspace/home/hugothemes
```

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

### View last update

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Displays the last modification date of a theme directory.

```bash
git log --pretty=format:"%ai" -n1 -- theme-name
```

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

### Quick Debug Workflow - Step 1: Check if build is running

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Checks for active Hugo processes.

```bash
# 1. Check if build is running
ps aux | grep -i hugo
```

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

### Count theme demos generated

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Counts the number of individual theme demo directories created.

```bash
ls -d _script/hugoThemeSite/themeSite/static/theme/*/ | wc -l
```

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

### Validate Theme Locally

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Steps to validate a theme locally by cloning example content, building with the theme, and checking various aspects.

```bash
# Clone Hugo example content
git clone https://github.com/gohugoio/hugoBasicExample.git content

# Build with your theme
hugo server -t /path/to/theme -s content

# Visit http://localhost:1313 and verify
```

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

### fixThemeTOML Usage Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

Example of how to use the fixThemeTOML function.

```bash
fixThemeTOML ${themesDir}/$x/theme.toml >> themeSite/content/$x/index.md
```

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

### README Transformation: Custom Element Escaping

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

Example of escaping custom elements in README files.

```diff
Before: {{<bootstrap alert>}}
After:  {{</*bootstrap alert*/>}}
```

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

### Quick Debug Workflow - Step 3: Check disk space

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Checks available disk space and the size of the build directory.

```bash
# 3. Check disk space
df -h .
du -sh _script/hugoThemeSite/
```

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

### fixThemeTOML Transformation Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

Example of a transformation performed by fixThemeTOML.

```bash
min_version = 0.20.1 -> min_version = "0.20.1"
```

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

### Directory Creation for Theme Content

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Creates content and image directories for each theme.

```bash
mkdir -p themeSite/content/{theme-name}
mkdir -p themeSite/static/images
```

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

### theme.toml example

Source: https://github.com/gohugoio/hugothemes/blob/master/README.md

Example structure and fields for the theme.toml file, which contains metadata about the theme.

```toml
name = "Theme Name"
license = "MIT"
licenselink = "Link to theme's license"
description = "Theme description"
homepage = "Website of your theme"
tags = ["blog", "company"]
features = ["some", "awesome", "features"]
min_version = "0.59.1"

# If the theme has multiple authors
authors = [
  {name = "Name of author", homepage = "Website of author"},
  {name = "Name of author", homepage = "Website of author"}
]

# If the theme has a single author
[author]
    name = "Your name"
    homepage = "Your website"

# If porting an existing theme
[original]
    author = "Name of original author"
    homepage = "His/Her website"
    repo = "Link to source code of original theme"
```

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

### Combine Configuration Files

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Combines base and parameter configuration files into a single theme configuration.

```bash
cat baseConfig > themeConfig
cat paramsConfig >> themeConfig
```

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

### Install a single theme

Source: https://github.com/gohugoio/hugothemes/blob/master/README.md

Steps to install a single Hugo theme by cloning its repository.

```bash
cd themes
git clone URL_TO_THEME
```

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

### Theme-Specific Build Configuration (custom exampleSite/)

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/configuration.md

Hugo build command for themes with a custom exampleSite/ directory.

```bash
HUGO_THEME=${theme_name} hugo --quiet \
  -s exampleSite2 \
  -d ../themeSite/static/theme/${theme_name}/ \
  -b ${BASEURL}/theme/${theme_name}/
```

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

### Theme .gitignore Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/theme-submission.md

Typical contents for a theme's .gitignore file to exclude build artifacts and editor files.

```gitignore
.DS_Store
resources/
.vscode/
.idea/
*.swp
*.swo
*~
```

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

### Academic Theme Metadata Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

Example of generated metadata for the Academic theme.

```yaml
title: Academic
name: Academic
description: The website builder for Hugo...
license: MIT
date: 2020-03-29
lastmod: 2024-05-15
source: https://github.com/gcushen/hugo-academic
demo: /theme/academic/
tags: [academic, blog, landing page, portfolio]
features: [responsive, dark mode, multilingual, blog]
min_version: 0.93.0
author: George Cushen
```

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

### Beautiful Hugo Theme Metadata Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

Example of generated metadata for the Beautiful Hugo theme.

```yaml
title: Beautiful Hugo
name: Beautiful Hugo
description: A port of the Beautiful Jekyll theme...
license: MIT
date: 2016-11-03
lastmod: 2024-01-20
source: https://github.com/halogenica/beautifulhugo
demo: /theme/beautiful-hugo/
tags: [blog, responsive]
features: [responsive, syntax-highlighting]
min_version: 0.38
author: Halogenica
original:
  author: Dean Attali
  repo: https://github.com/daattali/beautiful-jekyll
```

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

### Update All Repositories

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Updates all theme repositories and submodules to their latest versions.

```bash
cd _script/hugoThemeSite
cd themeSite && git pull --rebase && cd ..
cd exampleSite && git pull && cd ..
cd ../..
git submodule foreach git fetch origin
```

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

### Testing Theme with custom exampleSite

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/theme-submission.md

Bash command to test a theme using its custom exampleSite directory.

```bash
cd exampleSite
hugo server -t ..
```

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

### Submodule Declaration Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/git-integration.md

Example of entries in the .gitmodules file, mapping theme directories to their repository URLs.

```ini
[submodule "academic"]
    path = academic
    url = https://github.com/gcushen/hugo-academic.git
[submodule "beautiful-hugo"]
    path = beautiful-hugo
    url = https://github.com/halogenica/beautifulhugo.git
```

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

### Create Index.md for Showcase Content

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Creates the index.md file for a theme's showcase page, adding essential metadata.

```bash
echo "+++" > themeSite/content/$x/index.md
echo "title = \"$title\"" >> themeSite/content/$x/index.md
echo "date = \"$themeCreated\"" >> themeSite/content/$x/index.md
echo "lastmod = \"$themeUpdated\"" >> themeSite/content/$x/index.md
echo "source = \"$repo\"" >> themeSite/content/$x/index.md
```

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

### Path A1: Whitelisted Theme (custom exampleSite/) - Hugo build command

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Builds the demo site for a whitelisted theme using Hugo, specifying the theme and output directory.

```bash
HUGO_THEME=${x} hugo --quiet \
  -s exampleSite2 \
  -d ../themeSite/static/theme/$x/ \
  -b $BASEURL/theme/$x/
```

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

### Date/Time Formats - ISO 8601 Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/data-structures.md

Example of an ISO 8601 formatted timestamp used in build output.

```text
2024-05-27T14:30:45+00:00
```

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

### Twitter Card Tags Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

Example of Twitter Card metadata included on each theme page for social sharing.

```html
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Academic">
<meta name="twitter:description" content="The website builder for Hugo...">
<meta name="twitter:image" content="https://themes.gohugo.io/images/tn-featured-academic.png">
```

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

### Theme Loop Structure

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Iterates through all theme directories to process each theme.

```bash
for x in `find ${themesDir} -mindepth 1 -maxdepth 1 -type d ...`; do
    # Process theme $x
    # Timing: ~10-20 seconds per theme
    # Error handling: Count failures, continue
done
```

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

### Open Graph (OG) Tags Example

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/showcase-structure.md

Example of Open Graph metadata included on each theme page for social sharing.

```html
<meta property="og:title" content="Academic">
<meta property="og:description" content="The website builder for Hugo...">
<meta property="og:image" content="https://themes.gohugo.io/images/tn-featured-academic.png">
<meta property="og:url" content="https://themes.gohugo.io/theme/academic/">
<meta property="og:type" content="website">
```

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

### Hugo Build Command for Themes with Components

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Builds a demo site for a theme with components, specifying themes directory.

```bash
hugo --quiet \
  -s exampleSite2 \
  -c ${siteDir}/exampleSite/content/ \
  --themesDir ${themesDir}/$x/exampleSite/themes/ \
  --config=${demoConfig},${taxoConfig} \
  -d ../themeSite/static/theme/$x/ \
  -b $BASEURL/theme/$x/
```

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

### Validate Files

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Commands to validate theme.toml syntax and theme structure.

```bash
# Check theme.toml syntax
hugo config -s {theme}

# Validate theme structure
find {theme} -type f -name "*.toml" -o -name "*.md" | head -20
```

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

### No-Demo List Configuration

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-scripts.md

List of themes that only have metadata and no rendered demo.

```bash
noDemo=(
  'hugo-theme-w3css-basic'
  'devfest-theme-hugo'
  'docsy'
  'hugo-geekblog'
  'hugo-geekdoc'
  'hugo-PaperMod'
  'uBlogger'
  'doks'
  'less'
  'hugo-theme-stack'
  'toha'
  'hugo-profile'
)
```

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

### Clone/update showcase site

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Clones the showcase site repository if it doesn't exist, or pulls and updates submodules if it does.

```bash
if [ -d themeSite ]; then
    git pull --rebase --recurse-submodules origin master
    git submodule update --init --recursive
else
    git clone --recursive ${HUGO_THEME_SITE_REPO} themeSite
fi
```

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

### Useful Aliases

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Bash aliases for common hugoThemes commands to simplify workflows.

```bash
# Add to ~/.bashrc or ~/.zshrc

# Navigate to hugothemes directory
alias cdhugothemes='cd /workspace/home/hugothemes'

# Run full build
alias buildthemes='./buildThemeSite.sh http://localhost:1313'

# Start showcase server
alias servethemes='hugo server -s _script/hugoThemeSite/themeSite'

# Review a theme
alias reviewtheme='_script/reviewTheme.sh'

# Update all submodules
alias updatethemes='git submodule foreach git pull origin master'

# Check build status
alias themestatus='ls -d _script/hugoThemeSite/themeSite/static/theme/*/ | wc -l && echo " themes built"'
```

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

### Verify required images

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Checks for the existence of screenshot and thumbnail images for a theme.

```bash
test -f {theme}/images/screenshot.png && echo "Has screenshot"
test -f {theme}/images/tn.png && echo "Has thumbnail"
```

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

### Error Handling for Demo Site Creation

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Checks the exit status of the previous command and handles errors during demo site creation.

```bash
if [ $? -ne 0 ]; then
    echo "FAILED to create demo site for $x"
    rm -rf ${demoDestination}
    errorCounter=$((errorCounter + 1))
    generateDemo=false
fi
```

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

### Add Demo Link to Showcase Content

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Conditionally adds a demo link to the showcase content if a demo was generated.

```bash
if $generateDemo; then
    echo "demo = \"/theme/$x/\"" >> themeSite/content/$x/index.md
fi
```

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

### List active Hugo processes

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Checks for any running Hugo build processes.

```bash
ps aux | grep hugo
```

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

### Verify theme.toml exists and is valid

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Checks if a theme.toml file exists in the theme directory.

```bash
test -f {theme}/theme.toml && echo "Has theme.toml"
```

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

### Create hugoThemeSite directory

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Creates the hugoThemeSite directory and navigates into it.

```bash
mkdir -p hugoThemeSite
pushd hugoThemeSite
```

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

### Generated Content Navigation

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Navigates to directories where Hugo generates content and static files.

```bash
cd /workspace/home/hugothemes/_script/hugoThemeSite/themeSite/content
cd /workspace/home/hugothemes/_script/hugoThemeSite/themeSite/static/theme
cd /workspace/home/hugothemes/_script/hugoThemeSite/themeSite/public
```

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

### Hugo Settings (Set by Scripts)

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/quick-reference.md

Hugo settings that are automatically set by build scripts.

```bash
# Canonify URLs (set automatically)
export HUGO_CANONIFYURLS=true

# Themes directory (set automatically)
export HUGO_THEMESDIR=/path/to/themes
```

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

### Image Extraction - Thumbnail

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Copies the tn.png from the theme's images directory to the showcase site's content directory.

```bash
cp ${themesDir}/$x/images/tn.png \
   themeSite/content/$x/tn-featured-$x.png
```

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

### Append README to Showcase Content

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Appends the README.md content to the showcase index.md file.

```bash
fixReadme ${themesDir}/$x/README.md >> themeSite/content/$x/index.md
```

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

### Inspect Demo Output

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/build-process.md

Command to list the files in a theme's demo output directory.

```bash
ls -la _script/hugoThemeSite/themeSite/static/theme/{theme-name}/
```

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

### Error Logging - Fatal Errors

Source: https://github.com/gohugoio/hugothemes/blob/master/_autodocs/data-structures.md

Example log messages for fatal build errors.

```text
Command failed: exit status X
Logged to stderr
Script exits with code 1
```