# Understanding relative URLs

**URL:** <https://discourse.gohugo.io/t/understanding-relative-urls/26012>\
**Category:** support\
**Created:** [June 3, 2020, 8:42am UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012 "2020-06-03T08:42:47Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![sciurius](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/sciurius/32/11499_2.png) [@sciurius](https://discourse.gohugo.io/u/sciurius)\
**Post date:** [June 3, 2020, 8:42am UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012/1 "2020-06-03T08:42:47Z")

</div>

Setup:

```auto
config.toml
content/_index.html
content/home/index.md

```

In `config.toml` I have `relativeURLs = "true"`.  
In `content/home/index.md` I have:

```auto
{{< relurl "index.html" >}}
{{< relurl "/index.html" >}}
{{< relurl "../index.html" >}}
{{< relurl "./index.html" >}}

```

`relurl` is a trivial shortcode wrapper for `relURL`:

```auto
{{ .Get 0 | relURL }}

```

The generated `public/home/index.html` contains _four times_ `/index.html`.  
I would have expected:

```auto
{{< relurl "index.html" >}} index.html or ./index.html
{{< relurl "/index.html" >}} /index.html
{{< relurl "../index.html" >}} ../index.html
{{< relurl "./index.html" >}} ./index.html or index.html

```

Apparently I’m misunderstanding something basic. But what?

---

<div class="post-metadata">

**Author:** ![jmooring](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/jmooring/32/4214_2.png) [@jmooring](https://discourse.gohugo.io/u/jmooring)\
**Post date:** [June 3, 2020, 6:05pm UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012/2 "2020-06-03T18:05:06Z")

</div>

`relURL` returns a path relative to the protocol+host portion of the `baseURL` specified in config.toml.

## Example 1

```auto
baseURL = "https://www.example.org/"

```

The `baseURL` protocol+host is `https://www.example.org`  
The `baseURL` path is `/`

```auto
{{< relurl "quez.html" >}} --> /quez.html
{{< relurl "/quez.html" >}} --> /quez.html
{{< relurl "../quez.html" >}} --> /quez.html
{{< relurl "./quez.html" >}} --> /quez.html

```

## Example 2

```auto
baseURL = "https://www.example.org/foo/bar/baz/"

```

The `baseURL` protocol+host is `https://www.example.org`  
The `baseURL` path is `/foo/bar/baz/`

```auto
{{< relurl "quez.html" >}} --> /foo/bar/baz/quez.html
{{< relurl "/quez.html" >}} --> /foo/bar/baz/quez.html
{{< relurl "../quez.html" >}} --> /foo/bar/quez.html
{{< relurl "./quez.html" >}} --> /foo/bar/baz/quez.html

```

## How It Works

The `relURL` function uses [path.Join](https://golang.org/pkg/path/#Join) to assemble the return value.

> Join joins any number of path elements into a single path, separating them with slashes. Empty elements are ignored. The result is Cleaned.

What does “Cleaned” mean? From the [path.Clean](https://golang.org/pkg/path/#Clean) documentation:

> Clean returns the shortest path name equivalent to path by purely lexical processing. It applies the following rules iteratively until no further processing can be done:

> ```
> 1. Replace multiple slashes with a single slash.
> 2. Eliminate each . path name element (the current directory).
> 3. Eliminate each inner .. path name element (the parent directory)
> along with the non-.. element that precedes it.
> 4. Eliminate .. elements that begin a rooted path:
> that is, replace "/.." by "/" at the beginning of a path.
> 
> ```

This was helpful:

> [@Use case for relURL and absURL](https://discourse.gohugo.io/t/use-case-for-relurl-and-absurl/16633):
>
> Searched the forum and didn’t find an answer. So could someone highlight a use case for relURL and absURL in conjunction with baseURL? Very much appreciated.

Setting `relativeURLs = true` in config.toml has no effect when running `hugo server`. It only affects the output generated when you build the site with `hugo`.

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [June 3, 2020, 6:20pm UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012/3 "2020-06-03T18:20:25Z")

</div>

> [@jmooring](#):
>
> Setting `relativeURLs = true` in config.toml has no effect when running `hugo server` . I

That is not true, but I admit it that the `relativeURLs = true` feature is … confusing. But you are right in your above explanation. I think the important part is that.

- relURL and `.RelPermalink` is conceptually the same
- `relativeURLs = true` is _something else_, and works on the final output and should (if you’re diciplined enough) create URLs that works without a web server root (e.g. by clicking on the file on disk).

---

<div class="post-metadata">

**Author:** ![sciurius](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/sciurius/32/11499_2.png) [@sciurius](https://discourse.gohugo.io/u/sciurius)\
**Post date:** [June 3, 2020, 7:46pm UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012/4 "2020-06-03T19:46:14Z")

</div>

This is the crucial piece of information (emphasis mine):

> `relURL` returns a path **relative to the protocol+host portion** of the `baseURL` specified in config.toml.

The docs on `relURL` read (emphasis, again, mine):

> Given a string, prepends the relative URL **according to a page’s position in the project directory structure**.

This makes me expect `{{< relurl "../index.html" >}}` to return `/foo/index.html` when invoked from e.g. `/foo/bar/doc.md`.

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [June 3, 2020, 8:06pm UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012/5 "2020-06-03T20:06:10Z")

</div>

OK, the docs was wrong – I made a quick adjustment. `relURL` does not know/care about “the page position”.

---

<div class="post-metadata">

**Author:** ![sciurius](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/sciurius/32/11499_2.png) [@sciurius](https://discourse.gohugo.io/u/sciurius)\
**Post date:** [June 3, 2020, 8:40pm UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012/6 "2020-06-03T20:40:06Z")

</div>

Thanks!

---

<div class="post-metadata">

**Author:** ![sciurius](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/sciurius/32/11499_2.png) [@sciurius](https://discourse.gohugo.io/u/sciurius)\
**Post date:** [June 4, 2020, 8:44am UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012/7 "2020-06-04T08:44:53Z")

</div>

Related:

```auto
relref . "feedback/index.html"

```

yields `/feedback/`. While this is correct for web sites (that by default serve an `index.html` when asked for a folder) it defeats the possibiliity to use the static files directly from disk (as suggested in [https://gohugo.io/content-management/urls/#relative-urls](https://gohugo.io/content-management/urls/#relative-urls)).

Or is this the “It can’t be used for the homepage, section pages, etc.” exception?

---

<div class="post-metadata">

**Author:** ![bep](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/bep/32/3332_2.png) [@bep](https://discourse.gohugo.io/u/bep)\
**Post date:** [June 4, 2020, 8:56am UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012/8 "2020-06-04T08:56:54Z")

</div>

The “serves static files from disk” only works with `relativeURLs=true`.

---

<div class="post-metadata">

**Author:** ![sciurius](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/sciurius/32/11499_2.png) [@sciurius](https://discourse.gohugo.io/u/sciurius)\
**Post date:** [June 4, 2020, 9:23am UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012/9 "2020-06-04T09:23:26Z")

</div>

Yes, that’s what I have in the config.

---

<div class="post-metadata">

**Author:** ![system](https://yyz2.discourse-cdn.com/flex036/user_avatar/discourse.gohugo.io/system/32/1_2.png) [@system](https://discourse.gohugo.io/u/system)\
**Post date:** [June 6, 2020, 9:23am UTC](https://discourse.gohugo.io/t/understanding-relative-urls/26012/10 "2020-06-06T09:23:28Z")

</div>

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