Jekyll: Rename `baseurl` to `base_path`

[benbalter]

I'd like to propose that we rename baseurl to base_path in a backwards compatible way (meaning if you have baseurl in your config, we'll use it as base_path automatically, but with a deprecation warning).

There's a lot of confusion about how to use baseurl, and I suspect much of that stems from the name itself. Oddly, baseurl is not intended to represent the base _URL_, but really, the base _path_. We should name it accordingly.

Additionally, I'm wondering if we should throw a warning-level error, if baseurl begins with https?://, letting users know they're not using the setting properly.

Misusing baseurl causes all sorts of problems when rendering locally or across forks, and I swear I've seen it done wrong more times than done right.

One _nice_ thing about baseurl, however, is that it can be overridden via the command line via --baseurl flag. There's a common design pattern where baseurl might be http://example.com, used to build paths throughout templates, and then locally, baseurl is set to / or "" when previewing the site, preserving URLs. We may want to add a url flag, or similar, to allow users to set site.url, a bit more easily (although they could always use a second config, or github-metadata).

[envygeeks]

I'd like to propose that we rename baseurl to base_path

If they don't know what baseurl means they might not know what base_path means? Why not path_prefix? which is very explicit in it's intent and very direct in what it's intentions are (to prefix the path.) Base anything can go on either end because a base is the edge.

Additionally, I'm wondering if we should throw a warning-level error

Warnings are for recoverable errors, deprecation are not an error.

One nice thing about baseurl, however, is that it can be overridden via the command line via --baseurl flag. There's a common design pattern where baseurl might be http://example.com

Seems like both parties are doing it wrong then. Maybe we need to embed https://github.com/jekyll/jekyll/blob/master/lib/jekyll/commands/serve.rb#L7 better (if we already don't.) But using baseurl for that purpose seems to be abusing the prefix IMO.

[pathawks]

Maybe also throw a warning if baseurl ends with /, since that is a constant source of frustration.

• jekyll/jekyll-sitemap#76
• jekyll/jekyll-sitemap#79
• jekyll/jekyll-feed#63
• jekyll/jekyll-feed#93

[surrim]

I think the name baseurl is okay because you can use absolute URLs.
Use that in combination with minifyURLs from html-minifier to get rid of long/absolute links.

[benbalter]

I think the name baseurl is okay because you can use absolute URLs.

@surrim Please see http://blog.parkermoore.de/2014/04/27/clearing-up-confusion-around-baseurl/.

[benbalter]

/cc @jekyll/build, @jekyll/stability

[jaybe-jekyll]

I recall back when I delved into understanding baseurl and I recall thinking the same thing... that the "URL" piece is misleading and not appropriate or proper or accurate. For folks that take the time to read, learn, test, and understand-- it eventually nets out to nothing to worry about.

On the other hand, it's not a "URL"; a URL has a scheme, domain, and URI.

I agree the term, baseurl, is misleading and confusing, especially to new users of the function.

[ghost]

You'll of course need to keep site.baseurl and you can't break site.url

[felicianotech]

For some reference:

In Drupal:

$base_url   // Will point to http://example.com or https://example.com/my-site
$base_path;  // Will point to at least "/" or the subdirectory where the drupal in installed.
$base_root  // the url without the path, basically $base_url - $base_path

In WordPress:

$site_url // Will point to http://example.com or https://example.com/my-site, everything else is returned by functions

I think baseurl is misleading and should be basepath. Makes you wonder though that if the URL is commonly located in site.url that maybe just site.path would be appropriate.

[parkr]

@benbalter What do you think about this many months later?

[benbalter]

@parkr I still don't know of a good design pattern to have absolute URLs in production and localhost-based URLs locally. Since base URL has the configuration flag, I suspect that's why it's being used the way it is. I don't know that it's our # 1 issue, but do think there's still merit in a coming up with an "official" way to support development URLs that's less heavyweight than a 2nd config file.

[TWiStErRob]

@benbalter I agree about absolute urls, they shouldn't be mandatory. I try to make everything relative, which means that my website can be deployed anywhere without modification (re-generation with a different config in this case)... Jekyll is a static website generator, and static websites are usually based on relative paths (just think about a fully handwritten html website that you run locally from file system and upload via FTP).

[ghost]

If you want fully relative URLs, I can make this happen :)

[GeorgePhillips]

Building sites with absolute URLs is fine if you are not using baseurl. What if we added a new config variable called base_path (or an alternative) that parsed the html after build to alter the paths from working in the base directory to working in the new base path. This would leave relative paths alone and update absolute ones to contain the base path. The output directory would have all of the files built into a folder of the same name as the base path allowing no configuration to the server. This would remove all of the confusion of using baseurl as it would simply work. Looking at the HTML output it would make sense to someone who understands HTML. As an additional plus, there would be no need to use liquid on paths anymore with {{ page.path | prefix: site.baseurl }}.

Not sold on the idea, just thought I'd put it down.

[GeorgePhillips]

I agree with @pathawks, some validation should be added to baseurl.

• Must start with a slash, jekyll serve --baseurl example produces Server address: http://127.0.0.1:4000example/. Alternatively, a slash could be prepended if it doesn't have one when generating the URL.
• Warn ending with a slash, jekyll serve --baseurl /example/ produces Server address: http://127.0.0.1:4000/example//. Alternatively, double slashes could be when generating the URL.

[mattr-]

For the rest of the 3.x series, I propose we take both baseurl and base_path with the added validation for both, deprecate baseurl in favor of base_path and if we find a better name than base_path, we can just deprecate that too. :smiley:

[GeorgePhillips]

Could do something like:

("/" + site.baseurl).replace(/\/+/mg, "/").replace(/\/$/, "")

[envygeeks]

@GeorgePhillips uhm, see: https://github.com/jekyll/jekyll/blob/9061f0b1f35541f6d000910484df9f35d2ddd16f/lib/jekyll/url.rb#L102

Edit: I realize that we don't provide ending "/" removal, it's easily added.

[TWiStErRob]

@parkr / @envygeeks you should consider a "this is never stale" label (e.g. "future") to make exceptions for @jekyllbot. (Edit: sorry, this unrelated comment removed stale.)

[pathawks]

@TWiStErRob https://github.com/parkr/auto-reply/blob/19357fa7c4a82cecb4aedaae9a453e834caf3720/cmd/mark-and-sweep-stale-issues/mark_and_sweep_stale_issues.go#L18-L21

[jekyllbot]

This issue has been automatically marked as stale because it has not been commented on for at least two months.

The resources of the Jekyll team are limited, and so we are asking for your help.

If this is a bug and you can still reproduce this error on the 3.3-stable or master branch, please reply with all of the information you have about it in order to keep the issue open.

If this is a feature request, please consider building it first as a plugin. Jekyll 3 introduced hooks which provide convenient access points throughout the Jekyll build pipeline whereby most needs can be fulfilled. If this is something that cannot be built as a plugin, then please provide more information about why in order to keep this issue open.

This issue will automatically be closed in two months if no further activity occurs. Thank you for all your contributions.

[pathawks]

Not stale, just not near term

[TWiStErRob]

@pathawks @jekyllbot is really persistent that this is a no-issue...

[pathawks]

@TWiStErRob It has been a year, and it still doesn't seem clear what the path forward is. Maybe we're thinking about this the wrong way.

idk what the solution is, but I’ve pinned the issue to keep it away from @jekyllbot 😛👍🏼

[parkr]

I don't think renaming a field is a particularly good idea – people use configs for custom values all the time. If we didn't claim it at first, we will get a lot of pushback if we try to claim it now.

[pathawks]

@parkr A very good point. It seems _every time_ we try to add a new field to _config.yml we run into a conflict with somebody who was using that key for some custom unrelated feature.

It is kind of too bad that _config.yml serves double duty: setting configuration options _and_ setting site.* Liquid context.

[envygeeks]

In Jekyll 4 add in a namespacer. Start moving anything Jekyll specific into the jekyll namespace but still support the old stuff, and have the new namespace move to the new/old name and then flag it as deprecated, remove it in 4.2?

[envygeeks]

And then remove non-namespace support (for Jekyll specific stuff) in 5.0

[TWiStErRob]

it still doesn't seem clear what the path forward is

Well, that escalated quickly. I like that plan!

Though it's not 100% clear how it will solve the issue: if someone has declared a base_path in their config, it'll still be accessible via site.base_path, would the course of action you proposed mean site.baseurl becomes site.jekyll.base_path?

[pathawks]

would the course of action you proposed mean site.baseurl becomes site.jekyll.base_path?

Ideally, users should never need to access that in Liquid at all. URL filters will conquer all!

[TWiStErRob]

Ah, I see. I'm still on pre-filter, didn't migrate yet. Thanks!

[envygeeks]

Gotta get on that migration :wink:

[jekyllbot]

This issue has been automatically marked as stale because it has not been commented on for at least two months.

The resources of the Jekyll team are limited, and so we are asking for your help.

If this is a bug and you can still reproduce this error on the 3.3-stable or master branch, please reply with all of the information you have about it in order to keep the issue open.

If this is a feature request, please consider building it first as a plugin. Jekyll 3 introduced hooks which provide convenient access points throughout the Jekyll build pipeline whereby most needs can be fulfilled. If this is something that cannot be built as a plugin, then please provide more information about why in order to keep this issue open.

This issue will automatically be closed in two months if no further activity occurs. Thank you for all your contributions.

[pathawks]

What if Jekyll v4.0 used base_path to generate relative URLs with the URL filters?

This way, if sites were still using baseurl and not base_path, the URL filters would continue the previous behavior. If sites were updated to use base_path instead of baseurl, there would be no fear of prepending {{ site.baseurl }} to links generated with the URL filters.

[ashmaroli]

If sites were updated to use base_path instead of baseurl, there would be no fear of prepending {{ site.baseurl }} to links generated with the URL filters.

I think this would depend on how exactly we handle base_path when only baseurl is configured...

[miklb]

is this still earmarked for 4.0? I'm also looking at #6727 and curious how they may relate.

[schneems]

I ran into this issue and it was very difficult to debug. Here's a description of the problem I was having https://github.com/envygeeks/jekyll-assets/issues/616#issuecomment-533322098

I actually found this issue before asking the question, but figured that it would be good for others who might be having similar issues to be able to google for it.

[zlatanvasovic]

Is this going to be resolved any time soon?

[ashmaroli]

@zdroid This won't be resolved in the near future..