Configure server

Configure the development server.

These settings are exclusive to Hugo’s development server, so a dedicated configuration directory for development, where the server is configured accordingly, is the recommended approach.

project/
└── config/
    ├── _default/
    │   └── hugo.toml
    └── development/
        └── server.toml

Default settings

The development server defaults to redirecting to /404.html for any requests to URLs that don’t exist. See the 404 errors section below for details.

server:
  headers: null
  redirects:
  - force: false
    from: /**
    fromHeaders: null
    fromRe: ""
    status: 404
    to: /404.html

[server]
  [[server.redirects]]
    force = false
    from = '/**'
    fromRe = ''
    status = 404
    to = '/404.html'

{
   "server": {
      "headers": null,
      "redirects": [
         {
            "force": false,
            "from": "/**",
            "fromHeaders": null,
            "fromRe": "",
            "status": 404,
            "to": "/404.html"
         }
      ]
   }
}

force: (bool) Whether to force a redirect even if there is existing content in the path.
from: (string) A glob pattern matching the requested URL. Either from or fromRE must be set. If both from and fromRe are specified, the URL must match both patterns.
fromHeaders: New in v0.144.0; (map[string][string]) Headers to match for the redirect. This maps the HTTP header name to a glob pattern with values to match. If the map is empty, the redirect will always be triggered.
fromRe: New in v0.144.0; (string) A regular expression used to match the requested URL. Either from or fromRE must be set. If both from and fromRe are specified, the URL must match both patterns. Capture groups from the regular expression are accessible in the to field as $1, $2, and so on.
status: (string) The HTTP status code to use for the redirect. A status code of 200 will trigger a URL rewrite.
to: (string) The URL to forward the request to.

Headers

Include headers in every server response to facilitate testing, particularly for features like Content Security Policies.

headers:
- for: /**
  values:
    Content-Security-Policy: script-src localhost:1313
    Referrer-Policy: strict-origin-when-cross-origin
    X-Content-Type-Options: nosniff
    X-Frame-Options: DENY
    X-XSS-Protection: 1; mode=block

[[headers]]
  for = '/**'
  [headers.values]
    Content-Security-Policy = 'script-src localhost:1313'
    Referrer-Policy = 'strict-origin-when-cross-origin'
    X-Content-Type-Options = 'nosniff'
    X-Frame-Options = 'DENY'
    X-XSS-Protection = '1; mode=block'

{
   "headers": [
      {
         "for": "/**",
         "values": {
            "Content-Security-Policy": "script-src localhost:1313",
            "Referrer-Policy": "strict-origin-when-cross-origin",
            "X-Content-Type-Options": "nosniff",
            "X-Frame-Options": "DENY",
            "X-XSS-Protection": "1; mode=block"
         }
      }
   ]
}

Redirects

You can define simple redirect rules.

redirects:
- force: false
  from: /myspa/**
  status: 200
  to: /myspa/

[[redirects]]
  force = false
  from = '/myspa/**'
  status = 200
  to = '/myspa/'

{
   "redirects": [
      {
         "force": false,
         "from": "/myspa/**",
         "status": 200,
         "to": "/myspa/"
      }
   ]
}

The 200 status code in this example triggers a URL rewrite, which is typically the desired behavior for single-page applications.

404 errors

The development server defaults to redirecting to /404.html for any requests to URLs that don’t exist.

server:
  headers: null
  redirects:
  - force: false
    from: /**
    fromHeaders: null
    fromRe: ""
    status: 404
    to: /404.html

[server]
  [[server.redirects]]
    force = false
    from = '/**'
    fromRe = ''
    status = 404
    to = '/404.html'

{
   "server": {
      "headers": null,
      "redirects": [
         {
            "force": false,
            "from": "/**",
            "fromHeaders": null,
            "fromRe": "",
            "status": 404,
            "to": "/404.html"
         }
      ]
   }
}

If you’ve already defined other redirects, you must explicitly add the 404 redirect.

redirects:
- force: false
  from: /**
  status: 404
  to: /404.html

[[redirects]]
  force = false
  from = '/**'
  status = 404
  to = '/404.html'

{
   "redirects": [
      {
         "force": false,
         "from": "/**",
         "status": 404,
         "to": "/404.html"
      }
   ]
}

For multilingual sites, ensure the default language 404 redirect is defined last:

defaultContentLanguage: en
defaultContentLanguageInSubdir: false
redirects:
- from: /fr/**
  status: 404
  to: /fr/404.html
- from: /**
  status: 404
  to: /404.html

defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = false
[[redirects]]
  from = '/fr/**'
  status = 404
  to = '/fr/404.html'
[[redirects]]
  from = '/**'
  status = 404
  to = '/404.html'

{
   "defaultContentLanguage": "en",
   "defaultContentLanguageInSubdir": false,
   "redirects": [
      {
         "from": "/fr/**",
         "status": 404,
         "to": "/fr/404.html"
      },
      {
         "from": "/**",
         "status": 404,
         "to": "/404.html"
      }
   ]
}

When the default language is served from a subdirectory:

defaultContentLanguage: en
defaultContentLanguageInSubdir: true
redirects:
- from: /fr/**
  status: 404
  to: /fr/404.html
- from: /**
  status: 404
  to: /en/404.html

defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[[redirects]]
  from = '/fr/**'
  status = 404
  to = '/fr/404.html'
[[redirects]]
  from = '/**'
  status = 404
  to = '/en/404.html'

{
   "defaultContentLanguage": "en",
   "defaultContentLanguageInSubdir": true,
   "redirects": [
      {
         "from": "/fr/**",
         "status": 404,
         "to": "/fr/404.html"
      },
      {
         "from": "/**",
         "status": 404,
         "to": "/en/404.html"
      }
   ]
}

Last updated: March 5, 2025 : content: Consolidate configuration documentation (b6cae5cbc)

Improve this page