Clarifying the mental model and API for base paths

[j-maas]

While working on the alternative to #230 I was trying to figure out all the places where the base needs to be prepended. I was looking at the canonical URL and I am now thinking that since we have to provide the canonical URL anyway, we might be able to get rid of the base.

My hunch is that maybe we can replace the CLI optional parameter --base with a --canonical and make all absolute URLs fully qualified. For example, I would deploy with elm-pages build --canonical https://y0hy0h.github.io/unnecessarily-bad-design/ and all the links would look like https://y0hy0h.github.io/unnecessarily-bad-design/radiator-valves instead of /unnecessarily-bad-design/radiator-valves.

The main advantage is that we can rid of the finicky base path concept and simply embed it into the existing canonical URL concept. Also, it feels easier to decide on the canonical when I deploy rather then while I'm building the site, therefore moving the canonical out of the code and into a deploy parameter seems cleaner to me.

This also makes it easier to have fully qualified URLs for the dev server, since we could use localhost as the default canonical, if none is supplied.

What are your thoughts on this?

[dillonkearns]

Using the full canonical URLs for all links is an interesting idea, but in practice I think there are probably reasons to have internal links start with /. I can't put my finger on the exact reasons off the top of my head, but I think there may be some ways that URLs are treated differently. Perhaps Elm even treats them as internal or external based on whether they being with a protocol or a slash?

It's worth researching a little more to see if there are more pros and cons there. My gut feeling is that it should probably be up to the user to be able to opt in to using internal or external (full) URLs. It can't think of any specific issues it would cause, but it does seem unconventional so I could imagine there might be some.

[j-maas]

We should probably park the discussion about fully qualified vs absolute-path until we found a nice API for the path. I just want to dump a few resources here:

• https://stackoverflow.com/a/17407082/3287963
• https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL#absolute_urls_vs_relative_urls
• https://github.com/elm/browser/blob/1.0.2/src/Elm/Kernel/Browser.js#L164-L167

[dillonkearns]

Some notes from our discussion today:

Get link to asset

Example: link to an image resource.

• elm-review rule could check against files in the public folder whenever you use

1. Pages.linkToAsset : Path -> String
2. Pages.linkToAsset : List String -> String

Pages.linkToAsset [ "images", "hero.png" ]
Pages.linkToPublicAsset [ "images", "hero.png" ]

• Missing feature/bug: shadowed assets should give a build error.

Have a URL that points to a page

Route.toString <| Route.Blog__Slug { slug = "my-post" }

Route.toPath <| Route.Blog__Slug { slug = "my-post" }

• Get rid of Path.toAbsolute/Relative - why would anyone want relative? Instead, just provide Path.toString (to do what toAbsolute does now)
• Bug: Route.toString doesn't currently include the base.

Route.Blog__Slug { slug = "my-post" }
    |> Route.toPath
    |> Pages.toAbsolute

Get the path for the current page

Example: check if navbar link is a prefix of current path (you're on /marketing/blog/my-post and /marketing/blog in navbar should be highlighted)

Two helpers for with or without base

• Route.pathWithBase : Route -> Path
• Route.pathWithoutBase : Route -> Path

• Route.pathWithBase : IncludeBase -> Route -> Path

[j-maas]

To cristallize the notes:

There are three use cases: Linking to a page, linking to an asset, using a page's path to e.g. implement menu highlighting. We could abstract linking to a page and linking to an asset into one.

We have two APIs: One where we differentiate pages and assets and use Routes for anything relating to a page (e.g. Route.toString, Pages.linkToAsset, Route.pathWithBase, Route.pathWithoutBase), another where Path changes its meaning to be the place of a part of our site and usage is focused around Path (e.g. Route.toPath, Path.fromString, Path.toString).

[Erudition]

Not sure if this is the right place to ask this, but are these features available in 2.0+? Or just being discussed?
Because I know they were available in 1.0. In fact the starter repo I used had a function that highlighted a nav link based on whether it shares a prefix with the current page.

Unfortunately, the new docs site says nothing about how to get access to the current page URL, other page's URLs, URLs of static assets, and a few other things that I used in the elm-pages site I'm trying to upgrade. This is the only place I've seen mention of these features anymore.

[dillonkearns]

Because I know they were available in 1.0. In fact the starter repo I used had a function that highlighted a nav link based on whether it shares a prefix with the current page.

I think you're confusing two meanings of the term "base path". Checking whether a directory begins with a certain section of a path is possible in 2.0+, and that's unrelated from the discussion here. This thread is about the idea of hosting a site under a base path (for example, having it so that Page.Index is actually /marketing because you're hosting under that as the base path in your deployment).

You can check if the current path starts with a given sub-path (which I think is what you're thinking of here) - for example, in Shared.elm you get access to the current Path, and you can check if that list of segments starts with something to see if you're under that section. If you have more questions on that, feel free to ask in the #elm-pages slack channel.

[Erudition]

Thank you! I'm not much of a proprietary software user so I appreciate the public response. And you're right, the Shared module does get access to the page URL, perfect! I didn't say "base path" though, that is part of the discussion topic but this particular thread I replied to has three headers, which jumped out to me because they're exactly what I'm trying to figure out when converting my 1.0 project:

1. Get link to asset
2. Have a URL that points to a page
3. Get the path for the current page

You answered my question about how to do item 3, now I just need to figure out how to do items 1 and 2. Apologies if this is already documented somewhere.

[j-maas]

The longer I think about, the more I value a centralized Path that takes responsibility of the base. But this is my initial idea, so I might be biased, therefore please poke for issues in this proposal.

The goal: Anything that lives on your site can be pointed to by a Path.

Constructing Paths

• For an instance of a Route, you can get the path via Route.toPath. An elm-review rule could ensure the Route exists at build-time.
• For an asset that you know exists, you can build it via Path.fromString, Path.fromSegments and Path.join. An elm-review rule could ensure the asset the Path points to exists at build-time.

Using Paths

• Everywhere something on the site needs to be referenced, a Path is required. This seems to only apply to the Head tags, for example sitemapLink changes signature to sitemapLink : Path -> Tag.
• When you need to to link to something on the site, e.g. via <a>, you use Path.toString (there is a caveat, see next section) which gives you a URL.
• If you need to analyze what the Path contains, e.g. to highlight parts of your navigation, you use Path.toSegments (which does not include the base).

Caveat

If we have a Path.toString, then the Path module depends on the base which we only know at build-time. As far as I can tell, this means we need to generate Path at build-time. That would make it impossible to import from the many parts from the elm-pages library that currently do. An alternative is to have a Pages.pathToString and document that clearly on Path.

Build-time canonical and base

The base is currently set at build-time. I think that we would benefit from defining the canonical URL at build-time, too. That would simplify the differentiation between dev server and deployment: Currently, the canonical is hardcoded and so on the local dev build, some head tags that get the canonical prepended point to the hardcoded instance, on which I probably haven't yet deployed anything, which leads to 404s.

It seems like it is plausible to even combine the base and canonical into one thing, e.g. elm-pages build --canonical https://elm-pages.com or elm-pages build --canonical https://j-maas.github.io/unnecessarily-bad-design.¹ The effect would be that Path.toString would output fully qualified URLs.

It seems that that is a valid approach according to the standard, because the absolute-path URLs are just a shorthand when the protocol, domain and port can be inferred from the context (see https://stackoverflow.com/a/17407082/3287963 and https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL#absolute_urls_vs_relative_urls). Also, this would not impact Elm's detection on page change of whether the URL is internal or external, because that is implemented safely (see https://github.com/elm/browser/blob/1.0.2/src/Elm/Kernel/Browser.js#L164-L167).

Footnotes

1. As seen on slack with the example "<meta property="og:url" content="https://elm-pages.com/sub-page" /> is not using the base path", defining the canonical link as an Elm value has the disadvantage that you will need to redundantly declare the base, which can lead to instances where one isn't correctly updated. By defining the canonical at build-time together with the base, this deviation cannot happen. ↩