Use relative paths, not the site url about antora-lunr HOT 19 CLOSED

from antora-lunr.

page.pub.url is the root-relative path (starting from the root of the docs site, not necessarily the web server root). So it's your first example, /the-component/2.0/index.html.

Anyway, we want to index /the-component/2.0/index.html and then construct the complete URL client-side.

Exactly. Though if you know the page.pub.url and the root-relative URL you indexed (file.pub.url), then you can compute a relative URL to that result page.

The reason we use page.pub.url everywhere in Antora is because it allows us to make a portable URL (by any standard) any time we want. In other words, we have all the information we need to construct URLs, but no assumption about which URL variant we are constructing.

After trying a bunch of different ways in the early days of Antora, we found this strategy works best. If you want to make an absolute URL, then you prepend site.url. If you want to make a root-relative path (taking into account the path at which the site is running), you prepend site.path. If you want to make a relative URL from the current page, then you relativize using the two root-relative URL values.

from antora-lunr.

But file.pub.url is also /the-component/2.0/index.html?

I was getting the property names mixed up. This is the correct description of file.pub.url (where file is the virtual file in Antora's VFS). There's actually no page.pub.url. In the UI model, page.url matches the value of file.pub.url (where page is the name of a variable in the UI model).

from antora-lunr.

Perhaps I'm fooling myself, but it seems really easy to make the search completely portable/relocatable. Commit 94185cb in my plugin-377 branch has the changes, but there's also a bunch of lint fixes to search.js

It looks good.

Is there some reason to use absolute urls in the search?

No particular reason... @mojavelinux does it sound OK to you?

from antora-lunr.

I would like to get this too since my use case is having the doc site on the filesystem as well as on a web server.

from antora-lunr.

Be sure to pick the pathname off the site.url though if you're going to
make a root-relative path.

We are already doing that:

https://github.com/Mogztter/antora-lunr/blob/1320f8ccd5f52a91d1817bda801c0b0baec2045d/lib/generate-index.js#L22-L28

https://github.com/Mogztter/antora-lunr/blob/1320f8ccd5f52a91d1817bda801c0b0baec2045d/lib/generate-index.js#L118-L126

I think I took this code from Antora.

Perhaps I'm fooling myself, but it seems really easy to make the search completely portable/relocatable.

@djencks @thomasmhofmann Do you have a sample repository where I can reproduce this issue?

from antora-lunr.

@Mogztter I just finished incorporating the (part of) the change mentioned by @djencks in the first comment and it works. I only modified the following:

I added these two lines to search.js in createSearchResultItem

    var rootPath = window.antora.basePath
    documentHitLink.href = rootPath + item.ref

and remove what was there before. You can see the change in the diff of the commit mentioned in comment 1. I don't know how to reference the exact line here in the comment - sorry for that.
The other changes to that file in the comment are just "cosmetic".

In order to have window.antora.basePath available I also added to footer-script.hbs:

<script type="text/javascript">

  window.antora = window.antora || {}
  window.antora.basePath = '{{or siteRootPath (or siteRootUrl site.url)}}'
  window.antora.pagePath = '{{@root.page.url}}'
</script>

This was mentioned on Gitter...

I did not change the generator because it will already produce relative paths in case site.url is not set (which I am not setting in my playbook). These changes were everything it took to make the links in the search result work. I wanted a solution which only involves modifying my supplemental-ui.

I am sorry, the doc site is not public.

from antora-lunr.

I did not change the generator because it will already produce relative paths in case site.url is not set (which I am not setting in my playbook).

I'm using the same configuration.
In fact, in this case the url (on the document index) will be equal to page.pub.url.

Be sure to pick the pathname off the site.url though if you're going to
make a root-relative path.

I think we don't want to use the pathname from the site.url no? IIUC what we are trying to achieve here, the index should only contain the page URL.

So the index will work on any of the following site URL:

file:///path/to/somewhere
file:///path/to/somewhere/else
http://www.doc.org/foo
http://www.doc.org/foo/bar
http://doc.foo.org/
https://doc.foo.org/

from antora-lunr.

from antora-lunr.

There are three ways for this to work:

1. Use absolute URLs (which binds you to the domain.
2. Use root-relative paths, taking into account the pathname in the
   site.url (now you are domain free, but still coupled to the server env)
3. Use relative paths from page.pub.url

Indeed 👍

What we ultimately want for maximum portability is (3), which is
effectively what relativize is doing. But here we have to do it client
side, since you don't know the current page until the search is preformed.
For this to work, you need to pass the page.pub.url to the HTML so you can
use it to relativize the links in the search results. And that means the
records in the index should also use page.pub.url.

You mean the site.url? Do we need to relativize the links? We cannot concat the page.pub.url with the current site URL?
I don't remember what page.pub.url contains... something like /the-component/2.0/index.html or the complete URL http://example.com/the-component/2.0/the-page.html?
Anyway, we want to index /the-component/2.0/index.html and then construct the complete URL client-side.

If you can make 3 work, maybe that's all you need. But a setting might be warranted.

If we can make produce a portable index (that will work in any cases) I don't see the point of using an alternative method... but maybe I'm missing something?

from antora-lunr.

Exactly. Though if you know the page.pub.url and the root-relative URL you indexed (file.pub.url), then you can compute a relative URL to that result page.

So if my site.url is https://example.com/docs then file.pub.url is /docs/the-component/2.0/index.html (starting at server root)?

After trying a bunch of different ways in the early days of Antora, we found this strategy works best. If you want to make an absolute URL, then you prepend site.url.

It sounds like the simplest solution. So if my site.url is https://example.com/docs and my page.pub.url is /the-component/2.0/index.html then the link is https://example.com/docs/the-component/2.0/index.html right?
I think that's the most flexible solution since we only rely on site.url.

If you want to make a root-relative path (taking into account the path at which the site is running), you prepend site.path.

With my above example, site.path is /docs, correct?

If you want to make a relative URL from the current page, then you relativize using the two root-relative URL values.

Maybe it makes sense in other cases but here it feels like a lot of work for nothing no?

from antora-lunr.

So if my site.url is https://example.com/docs then file.pub.url is /docs/the-component/2.0/index.html (starting at server root)?

No, it's /the-component/2.0/index.html (the Antora publish root). The /docs path is part of the site metadata, specifically site.path.

from antora-lunr.

Maybe it makes sense in other cases but here it feels like a lot of work for nothing no?

Since it's computed at runtime (and thus not stored anywhere), I'm tempted to say there's no benefit. The server root-relative url is likely sufficient: site.path + file.pub.url.

from antora-lunr.

There are benefits for not including the domain name (which comes from site.url) since the browser can recognize it as a same-site URL.

from antora-lunr.

No, it's /the-component/2.0/index.html (the Antora publish root). The /docs path is part of the site metadata, specifically site.path.

I'm confused, you said that page.pub.url "is the root-relative path (starting from the root of the docs site, not necessarily the web server root). So it's your first example, /the-component/2.0/index.html".
But  file.pub.url is also /the-component/2.0/index.html?

It makes me think that it could be useful to add a concret example with the values of site.url, site.path, page.pub.url, file.pub.url... somewhere in the documentation, wdyt?

Since it's computed at runtime (and thus not stored anywhere), I'm tempted to say there's no benefit. The server root-relative url is likely sufficient: site.path + file.pub.url.
There are benefits for not including the domain name (which comes from site.url) since the browser can recognize it as a same-site URL.

I see that's a good point 👍

from antora-lunr.

If I understand correctly and in summary:

• In generate-index.js, the indexable content should have an url attribute with the value file.pub.url
• In search.js, the href (to go to the result page) should be site.path + item.ref (item.ref is equal to the url attribute)

A concret example:

• site.url: http://example.com/docs
• site.path: /docs
• file.pub.url: /the-component/2.0/index.html
• item.ref (url attribute): /the-component/2.0/index.html
• href (to go to the result page): /docs/the-component/2.0/index.html

Since the indexable documents do not rely on the site.url or the site.path, the Lunr index is portable/relocatable (for instance, we can use the same index when the site.url is equal to https://docs.example.org)

from antora-lunr.

Your understanding and explanation are absolutely correct.

from antora-lunr.

If there's an actual example of a situation in which my suggestion doesn't work, I'd appreciate seeing it in reproducible detail.

from antora-lunr.

If there's an actual example of a situation in which my suggestion doesn't work, I'd appreciate seeing it in reproducible detail.

@djencks I think the only difference is using site.path instead of site.url in the UI. Dan explained one benefit of using a root-relative url:

The server root-relative url is likely sufficient: site.path + file.pub.url.
There are benefits for not including the domain name (which comes from site.url) since the browser can recognize it as a same-site URL.

Though, I don't have a praticable example where using an absolute URL (rather than a relative URL) on the same site is an issue... So I think it should be relatively safe.

Do you want to submit a pull request with this change?

from antora-lunr.