Add absolute links support

[joaofreires]

Prepend the site-url in links with absolute path.

Problem:

If we host in the book in a sub page we lost the references for the relative root. We already have the site-url in configs, but we do not use it. If we want to link a page in the root of the book, we need to prepend a lot of ../ to reach the actual root, and if we move pages these relative refs could lead us to dead links.

Proposal

Add a new flag use-site-url-as-root in the HtmlConfig. The changes should have backward compatibility, we'll need to enable the use-site-url-as-root flag in [output.html] section inside the book.toml file to use the new feature.

TODO:

• [x] check if other type of links were affected by the changes

Closes: #1764

[watsom27]

Hey,

Is there any update on this one? This fixes the exact issue im having. Would be awesome if we could get this merged/looked at again.

Thanks

[joaofreires]

I can fix the merge conflict. Though, I still need someone to review/merge it.

[watsom27]

You'd be an actual hero if you did, thank you.

I replied on the issue thread too so hopefully someone notices.

[schungx]

You'd be an actual hero if you did, thank you.

Yes, this is long overdue. I currently have to resort to a templating engine to handle absolute paths. I use absolute paths almost exclusively as they don't require massive editing when I move a chapter up/down folder levels.

[watsom27]

Bump @ehuss

[mgeisler]

I think it is a little unfortunate to need to add a new config setting for this, but I don't see much of a way around it.

Would it not be better to add a syntax to let links use the path_to_root setting instead? That would be fully backwards compatible and avoid the need for a new config flag.

I'm thinking of something like

To back to [the root]($path_to_root/index.md)

The $path_to_root part would be a relative link, so it works even if site-url is not set. The syntax could also be {{ path_to_root }} if you let handlebars render it.

[JesusPerez]

site-url value in book.toml did not work for me as far as I tried with mdbook v0.4.29

• chapter-item are not changed for {{toc}}
• **<base href ** only works for 404.page
• {{ path_to_root }} for index.hbs has relative dots in hrefs

I can not rely on base href to solve all links and references use cases, dots in paths does not always help. SUMMARY.md has to use relative paths

To solve this I made some changes in:

• src/renderer/html_handlebars/hbs_renderer.rs
• src/renderer/html_handlebars/helpers/toc.rs

Changes can be seen in this fork (updated to v0.4.31) :

https://github.com/rust-lang/mdBook/compare/master...JesusPerez:mdBook:master

Obviously to complete the absolute paths in the pages I use a variable {{baseurl}} as a prefix of the href and src links. How to use it is described here: how to use absolute links in content

[Introduction]({{urlbase}}introduction.md)
![Image]({{urlbase}}image.jpg)

[calvinbrewer]

The code looks good to me, and the tests run, but unfortunately I wasn't able to actually confirm on the test_book the repo has that this PR fixes the issue. Is there some issue introduced in the latest commits that breaks this?

Confirmed here as well. Not working here: https://github.com/calvinbrewer/mdBook/tree/add_absolute_links_support with the configuration added as reference

[joaofreires]

The code looks good to me, and the tests run, but unfortunately I wasn't able to actually confirm on the test_book the repo has that this PR fixes the issue. Is there some issue introduced in the latest commits that breaks this?

Confirmed here as well. Not working here: https://github.com/calvinbrewer/mdBook/tree/add_absolute_links_support with the configuration added as reference

Sorry If I'm saying something wrong, but I opened this PR more than a year ago. I did not include any examples in the test_book. Could you please clarify what you mean by 'Not working here'? What specific aspect are you testing? The proposed solution involves adding the site-url as a root in absolute paths. Therefore, in your configuration example, it would be /docs/. If you create a Markdown link in your test_book, such as [Prefix](/prefix.md) (note it starts with /), it should correctly generate an HTML a element with the href attribute set to /docs/prefix.html.

[calvinbrewer]

Sorry If I'm saying something wrong, but I opened this PR more than a year ago. I did not include any examples in the test_book. Could you please clarify what you mean by 'Not working here'? What specific aspect are you testing? The proposed solution involves adding the site-url as a root in absolute paths. Therefore, in your configuration example, it would be /docs/. If you create a Markdown link in your test_book, such as [Prefix](/prefix.md) (note it starts with /), it should correctly generate an HTML a element with the href attribute set to /docs/prefix.html.

I've added an example in the test_book test_book/src/individual/link_hr.md that links to the prefix.md here. This does not seem to have the site-url added to the rendered a href.

In addition, from a usability perspective, I'd assume the left nav items to also include the site-url as a prefix. I may be mistaken on the intent of the original absolute link support. Ideally, the entire mdBook application would live under a main domain as a micro application e.g. https://example.com/docs

[joaofreires]

I've added an example in the test_book test_book/src/individual/link_hr.md that links to the prefix.md here. This does not seem to have the site-url added to the rendered a href.

I have successfully built your branch, and the HTML output from your example seems to be producing the expected results. In test_book/book/individual/link_hr.html, the following segment is generated for your example:

....
<a href="/docs/prefix.html">This</a> should link to prefix.md.
....

IMO, this outcome aligns with our assumptions. Could you please share your build results? Maybe I missed something.

In addition, from a usability perspective, I'd assume the left nav items to also include the site-url as a prefix. I may be mistaken on the intent of the original absolute link support. Ideally, the entire mdBook application would live under a main domain as a micro application e.g. https://example.com/docs

My intention with this particular changes was not to address all those cases. Regarding the navigation links, they are generated based on SUMMARY.md, which, as per the mdBook documentation, requires all links to be relative.

[KFearsoff]

Therefore, in your configuration example, it would be /docs/. If you create a Markdown link in your test_book, such as [Prefix](/prefix.md) (note it starts with /), it should correctly generate an HTML a element with the href attribute set to /docs/prefix.html.

Hmm. I've tried doing this by myself, and after you wrote a response I checked again with the exact inputs you've provided. Here's a patch that I'm got for testing:

diff --git a/test_book/book.toml b/test_book/book.toml
index a305007..91e8c9d 100644
--- a/test_book/book.toml
+++ b/test_book/book.toml
@@ -9,6 +9,8 @@ edition = "2018"
 
 [output.html]
 mathjax-support = true
+site-url = "/docs/"
+use-site-url-as-root = true
 
 [output.html.playground]
 editable = true
diff --git a/test_book/src/individual/README.md b/test_book/src/individual/README.md
index 67a1e9d..fceb065 100644
--- a/test_book/src/individual/README.md
+++ b/test_book/src/individual/README.md
@@ -2,6 +2,8 @@
 
 This contains following tags:
 
+[Prefix](/prefix.md)
+
 - Headings
 - Paragraphs
 - Line breaks

I then run cargo run -- serve --hostname 127.0.0.1. My expectation is that at http://127.0.0.1:3000/individual/index.html, I should see a link to http://127.0.0.1:3000/docs/prefix.html, but I'm seeing a link to http://127.0.0.1:3000/prefix.html. Am I missing something?

[joaofreires]

@KFearsoff to view the results, it is necessary to execute the command cargo run -- build. This is because the server mode overrides the site-url configuration to "/" for development purposes, I presume.

You can check it here: https://github.com/rust-lang/mdBook/blob/c1d622e56ea02cc47d22a6e8cdc70a836d96e721/src/cmd/serve.rs#L67

[KFearsoff]

@KFearsoff to view the results, it is necessary to execute the command cargo run -- build. This is because the server mode overrides the site-url configuration to "/" for development purposes, I presume.

Oh. Ohhh. Yeah, I can confirm this works.

This is... pretty unfortunate, though. I think serve overriding the setting is extremely unintuitive and does more harm than good, especially with this PR. Do you mind seeing if it's possible to remove, and can we afford making this breaking change? Because I'd really hate it if we can't.

[joaofreires]

@KFearsoff, I believe this constitutes a reasonable usage. The serve mode is designed exclusively for development purposes and is tasked solely with hosting the book files. I agree that enhanced documentation would be beneficial in this context though.

Another aspect to consider carefully is the content of site-url. It's important to note that this is not limited to pathnames; it can include absolute URLs complete with hostnames and schemas. This flexibility could potentially lead to further complications when operating on a local server if we want to include the site-url as is.

It would be good to have more feedbacks on it before any change.

[JesusPerez]

Just in case if it helps I updated my mdBook with absolute links via site-url based in current mdBook master branch (v0.4.36 59d371715924752a18a31e96081bfba3c15bb0a6)

I only fixed a couple of files, maybe it is not enough but it seems to work for me.

You can clone it, build and try following how-to-use-it notes with sitefix-book as example.

For instance I have tested absolute URL with hostnames and schemas and it works ! @joaofreires I use to keep absolute path in most cases and leave the rest for web service resolution (server and browsers) in some circunstances "<base href=" in index.hbs can also help.

I have to deal with multi-books services with auth, for me it is critical to support absolute links.

Let me know if I can help on this.