> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/hugo

Common CircleCI tasks for installing and using Hugo.

Supports the Docker executor (Linux OS with libc) and the macOS executor.
 Includes a `cibuilds` executor image with Hugo and html-proofer
 pre-installed.


## Commands

### html-proofer

Runs HTML Proofer on 'path' to check for html errors. Ruby and the `html-proofer` gem must already be installed to use.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `allow-hash-href` | boolean | true | If `true`, ignores the `href= |
| `allow-missing-href` | boolean | false | If `true`, does not flag `a` tags missing `href` (this is the default for HTML5). |
| `alt-ignore` | string |  | A comma-separated list of Strings or RegExps containing `img`s whose missing `alt` tags are safe to ignore |
| `as-links` | boolean | false | Assumes that `PATH` is a comma-separated array of links to check. |
| `assume-extension` | boolean | false | Automatically add extension (e.g. `.html`) to file paths, to allow extensionless URLs (as supported by Jekyll 3 and GitHub Pages) (default: `false`). |
| `check-external-hash` | boolean | false | Checks whether external hashes exist (even if the webpage exists). This slows the checker down (default: `false`). |
| `check-favicon` | boolean | false | Enables the favicon checker (default: `false`). |
| `check-html` | boolean | false | Enables HTML validation errors from Nokogiri (default: `false`). |
| `check-img-http` | boolean | false | Fails an image if it's marked as `http` (default: `false`). |
| `check-opengraph` | boolean | false | Enables the Open Graph checker (default: `false`). |
| `check-sri` | boolean | false | Check that `<link>` and `<script>` external resources do use SRI (default: `false`). |
| `checks-to-ignore` | string | '' | An array of Strings indicating which checks you'd like to not perform. |
| `directory-index-file` | string | index.html | Sets the file to look for when a link refers to a directory. (default: `index.html`) |
| `disable-external` | boolean | false | If `true`, does not run the external link checker, which can take a lot of time (default: `false`) |
| `empty-alt-ignore` | boolean | true | If `true`, ignores images with empty alt tags |
| `enforce-https` | boolean | false | Fails a link if it's not marked as `https` (default: `false`). |
| `error-sort` | string |  | Defines the sort order for error output. Can be `:path`, `:desc`, or `:status`. |
| `extension` | string | '.html' | The extension of your HTML files including the dot. (default: `.html`) |
| `external_only` | boolean | false | Only checks problems with external references |
| `file-ignore` | string | '' | A comma-separated list of Strings or RegExps containing file paths that are safe to ignore |
| `http-status-ignore` | string | '' | A comma-separated list of numbers representing status codes to ignore. |
| `internal-domains` | string | '' | A comma-separated list of Strings containing domains that will be treated as internal urls. |
| `log-level` | string | info | Sets the logging level, as determined by Yell. One of `:debug`, `:info`, `:warn`, `:error`, or `:fatal`. (default: `:info`) |
| `only-4xx` | boolean | false | Only reports errors for links that fall within the 4xx status code range |
| `path` | string |  | Path to generated files relative to working_directory. |
| `report-eof-tags` | boolean | false | Ignore `check_html` errors associated with malformed tags (default: `false`) |
| `report-invalid-tags` | boolean | false | Ignore `check_html` errors associated with unknown markup (default: `false`) |
| `report-mismatched-tags` | boolean | false | Ignore `check_html` errors associated with mismatched tags (default: `false`) |
| `report-missing-doctype` | boolean | false | Ignore `check_html` errors associated with missing or out-of-order `DOCTYPE` (default: `false`) |
| `report-missing-names` | boolean | false | Ignore `check_html` errors associated with missing entities (default: `false`) |
| `report-script-embeds` | boolean | false | Ignore `check_html` errors associated with `script`s (default: `false`) |
| `storage-dir` | string | 'tmp/.htmlproofer' | Directory where to store the cache log (default: "tmp/.htmlproofer") |
| `timeframe` | string | '1h' | A string representing the caching timeframe. The format is `[0-9]+[mhd]` where `m` stands for month, `h` for hours and `d` for days. |
| `typhoeus-config` | string | '{}' | JSON-formatted string of Typhoeus config. Will override the html-proofer defaults. |
| `url-ignore` | string | '' | A comma-separated list of Strings or RegExps containing URLs that are safe to ignore. It affects all HTML attributes. Note that non-HTTP(S) URIs are always ignored |
| `url-swap` | string | '' | A comma-separated list containing key-value pairs of `RegExp => String`. It transforms URLs that match `RegExp` into `String` via `gsub`. The escape sequences `:` should be used to produce literal `:`s. |

### hugo-build

Builds with Hugo a static site located at 'source'. The default is '.'.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `destination` | string | public | Path to where Hugo outputs generated site. Relative to `source`. |
| `extra-flags` | string |  | Additional flags to pass when running Hugo (e.g. -DF). |
| `hugo-env` | string | production | Set the value of HUGO_ENV prior to running Hugo. |
| `source` | string | . | Path to Hugo root relative to working_directory. |

### install

Install the Hugo binary into your build.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `extended` | boolean | true | Install the Hugo extended binary? |
| `install-location` | string | /usr/local/bin | Location where the hugo binary should be installed. |
| `version` | string |  | The Hugo version. |

## Jobs

### build

Build a site with Hugo.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `destination` | string | public | Path to where Hugo outputs generated site. Relative to `source`. |
| `html-proofer` | boolean | true | Whether or not to test the outputted HTML with HTML Proofer. |
| `htmlproofer-http-status-ignore` | string | '' | An array of numbers representing status codes to ignore. |
| `htmlproofer-timeframe` | string | '1h' | A string representing the caching timeframe. The format is `[0-9]+[mhd]` where `m` stands for month, `h` for hours and `d` for days. |
| `htmlproofer-url-ignore` | string | '' | An array of Strings or RegExps containing URLs that are safe to ignore. It affects all HTML attributes. Note that non-HTTP(S) URIs are always ignored. |
| `hugo-env` | string | production | Set the value of HUGO_ENV prior to running Hugo. |
| `hugo-extra-flags` | string |  | Additional flags to pass when running Hugo (e.g. -DF). |
| `persist-to-workspace` | boolean | true | Whether to persist generated files to a CircleCI Workspace. This uses `parameters.source` as root and `parameters.publishdir` as the path. |
| `source` | string | . | Path to Hugo root relative to working_directory. |
| `version` | string | latest | Hugo version to use. Defaults to latest. |

## Executors

### default

The cibuilds/hugo Docker image.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `hugo_version` | string | 0.162.1 | Specifies the hugo version to install |

## Examples

### build-and-deploy

"An example of building a Hugo site, testing with HTML Proofer, and deployng it. Here the Hugo source is in a subdirectory called 'src'. The deploy job is empty and serves as an example. Instead of the 'ls' command, you'd want to deploy the files using whatever tools you're used to."


```yaml
version: '2.1'
orbs:
  hugo: circleci/hugo@1.3.1
jobs:
  deploy:
    docker:
      - image: cimg/base
    steps:
      - attach_workspace:
          at: my-site
      - run: ls -lah my-site
workflows:
  main:
    jobs:
      - hugo/build:
          html-proofer: true
          source: src/
          version: 0.141.0
      - deploy:
          filters:
            branches:
              only: master
          requires:
            - hugo/build
```

### build-and-test

"The simplest example of using the Hugo orb."


```yaml
version: '2.1'
orbs:
  hugo: circleci/hugo@1.3.1
workflows:
  main:
    jobs:
      - hugo/build:
          html-proofer: true
          version: 0.141.0
```