Update the baseurl with "docs/"

support
1

Hi everyone,
I’m using Hugo for building my websites, I wanted to add/update the path from the root “/” to “docs/”.
I tried to update that with baseUrl="docs/" from config.toml, but it’s changing the path only for some resources like CSS, js build in the assets folder working fine, but images and fonts stored in the static folder were not updating, I saw from the network tab that these files (static files) are accessible by updating the URL with “docs/”. I wanted to add “docs/” to my domain as this is a documentation website.
For now, I tried canonifyURLs = true and run the build command as -b "example.com/docs/", but this is still not working properly as some images still are not updating the path. I’m using vercel for deployment.

2

1) The canonifyURLs setting is rarely used, and doesn’t do what you probably hope it does.

2) Your baseURL should be fully qualified and include a trailing slash.

baseURL = 'https://example.org/docs/'

3) To properly resolve destinations in markdown link and image elements, use link and image render hooks.

layouts/_default/_markup/render-image.html 
{{- /*
Internal destinations are resolved in this order:

  1. Page resource
  2. Global resource

External destinations are also captured as resources to determine width and
height attributes. The rendered URLs for these resources are relative to the
generated site.

Global resources must be placed within the assets directory. If these resources
are located in the static directory, and you are unable or unwilling to move
them, you must mount the static directory to the assets directory by including
both of these entries in the site configuration:

  [[module.mounts]]
  source = 'assets'
  target = 'assets'

  [[module.mounts]]
  source = 'static'
  target = 'assets'

By default, if the destination cannot be resolved, it will be passed through
without modification. To emit a warning or error, set the error level in the
site configuration:

  [params.render_hooks.image]
  errorLevel = 'error' # ignore (default), warning, or error

The example above will throw an error and fail the build if the destination
cannot be resolved.

This render hook may be unable to resolve destinations created with the ref and
relref shortcodes. Unless the error level is set to ignore, you should not use
either of these shortcodes.
*/}}

{{- /* Action when unable to resolve destination: ignore, warning, or error. */}}
{{- $errorLevel := or site.Params.render_hooks.image.errorLevel "ignore" | lower }}

{{- /* Validate action. */}}
{{- if not (in (slice "ignore" "warning" "error") $errorLevel) }}
  {{- errorf "%q is an invalid action when unable to resolve destination" $errorLevel }}
{{- end }}

{{- /* Determine content path for warning and error messages. */}}
{{- $contentPath := "" }}
{{- with .Page.File }}
  {{- $contentPath = .Path }}
{{- else }}
  {{- $contentPath = .Path }}
{{- end }}

{{- /* Parse destination. */}}
{{- $u := urls.Parse .Destination }}

{{- /* Set common message. */}}
{{- $msg := printf "Unable to resolve image destination %q in %s" $u.String $contentPath }}

{{- /* Get image resource. */}}
{{- $r := "" }}
{{- if $u.IsAbs }}
  {{- with resources.GetRemote $u.String }}
    {{- with .Err }}
      {{- if eq $errorLevel "warning" }}
        {{- warnf "%s. See %s" . $contentPath }}
      {{- else if eq $errorLevel "error" }}
        {{- errorf "%s. See %s" . $contentPath }}
      {{- end }}
    {{- else }}
      {{- /* Destination is external. */}}
      {{- $r = . }}
    {{- end }}
  {{- else }}
    {{- if eq $errorLevel "warning" }}
      {{- warnf $msg }}
    {{- else if eq $errorLevel "error" }}
      {{- errorf $msg }}
    {{- end }}
  {{- end }}
{{- else }}
  {{- with .Page.Resources.Get (strings.TrimPrefix "./" $u.Path) }}
    {{- /* Destination is a page resource. */}}
    {{- $r = . }}
  {{- else }}
    {{- with resources.Get $u.Path }}
      {{- /* Destination is a global resource. */}}
      {{- $r = . }}
    {{- else }}
      {{- if eq $errorLevel "warning" }}
        {{- warnf $msg }}
      {{- else if eq $errorLevel "error" }}
        {{- errorf $msg }}
      {{- end }}
    {{- end }}
  {{- end }}
{{- end }}

{{- /* Initialize attributes. */}}
{{- $attrs := merge .Attributes (dict "alt" .PlainText "title" .Title "src" $u.String) }}

{{- /* Merge attributes from resource. */}}
{{- with $r }}
  {{- $attrs = merge $attrs (dict "src" .RelPermalink) }}
  {{- if not (eq .MediaType.SubType "svg") }}
    {{- $attrs = merge $attrs (dict "height" (string .Height) "width" (string .Width)) }}
  {{- end }}
{{- end }}

{{- /* Render image element. */ -}}
<img
  {{- range $k, $v := $attrs }}
    {{- if or $v (eq $k "alt") }}
      {{- printf " %s=%q" $k $v | safeHTMLAttr }}
    {{- end }}
  {{- end -}}
>
{{- /**/ -}}

layouts/_default/_markup/render-link.html 
{{- /*
Internal destinations are resolved in this order:

  1. Content page
  2. Page resource   (example: PDF file)
  3. Global resource (example: PDF file)

External destinations are passed through without modification.

Global resources must be placed within the assets directory. If these resources
are located in the static directory, and you are unable or unwilling to move
them, you must mount the static directory to the assets directory by including
both of these entries in the site configuration:

  [[module.mounts]]
  source = 'assets'
  target = 'assets'

  [[module.mounts]]
  source = 'static'
  target = 'assets'

By default, if the destination cannot be resolved, it will be passed through
without modification. To emit a warning or error, set the error level in the
site configuration:

  [params.render_hooks.link]
  errorLevel = 'error' # ignore (default), warning, or error

The example above will throw an error and fail the build if the destination
cannot be resolved.

This render hook may be unable to resolve destinations created with the ref and
relref shortcodes. Unless the error level is set to ignore, you should not use
either of these shortcodes.
*/}}

{{- /* Action when unable to resolve destination: ignore, warning, or error. */}}
{{- $errorLevel := or site.Params.render_hooks.link.errorLevel "ignore" | lower }}

{{- /* Validate action. */}}
{{- if not (in (slice "ignore" "warning" "error") $errorLevel) }}
  {{- errorf "%q is an invalid action when unable to resolve destination" $errorLevel }}
{{- end }}

{{- /* Determine content path for warning and error messages. */}}
{{- $contentPath := "" }}
{{- with .Page.File }}
  {{- $contentPath = .Path }}
{{- else }}
  {{- $contentPath = .Path }}
{{- end }}

{{- /* Parse destination. */}}
{{- $u := urls.Parse .Destination }}

{{- /* Set common message. */}}
{{- $msg := printf "Unable to resolve link destination %q in %s" $u.String $contentPath }}

{{- /* Set attributes for anchor element. */}}
{{- $attrs := dict "href" $u.String }}
{{- if $u.IsAbs }}
  {{- /* Destination is external. */}}
  {{- $attrs = merge $attrs (dict "rel" "external") }}
{{- else }}
  {{- with $u.Path }}
    {{- with $.Page.GetPage . }}
      {{- /* Destination is a page. */}}
      {{- $href := .RelPermalink }}
      {{- with $u.RawQuery }}
        {{- $href = printf "%s?%s" $href $u.RawQuery }}
      {{- end }}
      {{- with $u.Fragment }}
        {{- $href = printf "%s#%s" $href $u.Fragment }}
      {{- end }}
      {{- $attrs = dict "href" $href }}
    {{- else }}
      {{- with $.Page.Resources.GetMatch $u.Path }}
        {{- /* Destination is a page resource; drop query and fragment. */}}
        {{- $attrs = dict "href" .RelPermalink }}
      {{- else }}
        {{- with resources.Get $u.Path }}
          {{- /* Destination is a global resource; drop query and fragment. */}}
          {{- $attrs = dict "href" .RelPermalink }}
        {{- else }}
          {{- if eq $errorLevel "warning" }}
            {{- warnf $msg }}
          {{- else if eq $errorLevel "error" }}
            {{- errorf $msg }}
          {{- end }}
        {{- end }}
      {{- end }}
    {{- end }}
  {{- else }}
    {{- with $u.Fragment }}
      {{- /* Destination is on the same page; prepend relative permalink. */}}
      {{- $attrs = dict "href" (printf "%s#%s" $.Page.RelPermalink .) }}
    {{- else }}
      {{- if eq $errorLevel "warning" }}
        {{- warnf $msg }}
      {{- else if eq $errorLevel "error" }}
        {{- errorf $msg }}
      {{- end }}
    {{- end }}
  {{- end }}
{{- end }}
{{- with .Title }}
  {{- $attrs = merge $attrs (dict "title" .) }}
{{- end -}}

{{- /* Render anchor element. */ -}}
<a
  {{- range $k, $v := $attrs }}
    {{- printf " %s=%q" $k $v | safeHTMLAttr }}
  {{- end -}}
>{{ .Text | safeHTML }}</a>
{{- /**/ -}}

To control the behavior when a link or image destination cannot be resolved, place this in your site configuration.

[params.render_hooks.link]
errorLevel = 'error' # ignore (default), warning, or error

[params.render_hooks.image]
errorLevel = 'error' # ignore (default), warning, or error

4) If the images you reference in markdown are stored in the static directory, you can either move them to the assets directory, or mount the static directory on the assets directory:

[[module.mounts]]
source = 'assets'
target = 'assets'

[[module.mounts]]
source = 'static'
target = 'assets'

5) In your templates, if you have hardcoded links to other assets, pass them through the relURL or relLangURL functions.

1 Like
3

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.