mdBook
mdBook copied to clipboard
rust-lang
site-url not respected in links
Since I set the site-url (or base url in other frameworks):
[output.html]
site-url = "/proof-systems/"
I would expect all markdown links to be rewritten to respect that in my book. They aren't :o
All links in your book should be relative, so it shouldn't matter where it is located. The site-url is only needed for generating the 404 page which has to be able to work when loaded from any location.
If you are using absolute links, like /foo.md, then I recommend changing them to be relative (such as foo.md or ../foo.md). I'm not sure mdbook should rewrite absolute links, since they may legitimately be trying to link to a location outside of the book.
in my case, I am moving the generated rust documentation into the /rustdoc folder in the book. So that on github pages, I can access both the book and the rustdoc.
I'm not sure mdbook should rewrite absolute links, since they may legitimately be trying to link to a location outside of the book.
I'm not sure I understand, all frameworks that expose a base-url do this: they rewrite all absolute links using the base url. What is a use case where you wouldn't want that?
I'm not sure I understand, all frameworks that expose a base-url do this: they rewrite all absolute links using the base url. What is a use case where you wouldn't want that?
I'd second this.
Writing a large book with mdbook means that I'm constantly shifting chapters from one place to another, sometimes across folders or up/down levels. It would be a huge mess to manually fix all relative url links whenever I move a file.
Always using absolute url links resolve this issue nicely, resulting in a huge savings of time. I believe this feature is sorely needed.
Right now, I use a templating engine mdbook-tera and put {{rootUrl}}/ in front of all my url links, but it is not as good as built-in support.
What is a use case where you wouldn't want that?
This probably isn't used in practice very often, but I can imagine a book that wants to link to other pages on the same website (that aren't part of a book). We don't use it for rust-lang, so I would be fine changing it, but it could possibly be a breaking change for other users, so it would need to wait for the next incompatible release.
This probably isn't used in practice very often, but I can imagine a book that wants to link to other pages on the same website (that aren't part of a book)
yeah I'm not personally convinced, from a site-url standpoint everything else is "external" and should be linked with a fully-qualified URL
but it could possibly be a breaking change for other users, so it would need to wait for the next incompatible release.
no worries : )
This probably isn't used in practice very often
Actually it is used very often for me.
It is not absolutely needed as I can always use ../../../some/path/doc.md instead of the much better /some/path/doc.md, but that means that I can never move files around as well as up/down levels without doing a global scan for broken links!
It happens a lot during periods of heavy revision.
If I move a folder up/down, then God forbid!
Hey you all! Not sure if what I did solves your issue. But could you check #1802 and test it if you have some time? Thank you!
What should I do to test an open unmerged PR? Never done this before...
or is it in the add_absolute_links_support branch?
or is it in the add_absolute_links_support branch?
Yes, you can build the add_absolute_links_support branch and test from there.
Here's the repo/branch: https://github.com/joaofreires/mdBook/tree/add_absolute_links_support
Note: as described in the PR, you need to set the feature as true. So, inside the book.toml you will need to have something like:
[output.html]
site-url = "/some/path/"
use-site-url-as-root = true
Seems to work just fine!
I particularly like the fact that it doesn't add the site url if going through mdbook serve, that makes things Just Work everywhere.
@schungx , mdBook already set the site-url to / in the "serve mode". 😃
https://github.com/rust-lang/mdBook/blob/7c37dd5e8570ffc93701c1d6b6ffdd97b430467e/src/cmd/serve.rs#L79
@schungx , mdBook already set the
site-urlto/in the "serve mode". 😃
With this change, I can actually remove mdbook-tera because I only used the templating engine in order to put in the correct url prefix. It makes the entire project much simpler to build and deploy!
@ehuss I wonder if this PR can be merged? Since it introduces a new option flag, it should not break any existing build.
Now if I would ask for one more thing: make the #include command take paths that are based off src.
Right now, it is either relative path based off the current file, or an absolute path based off the file system root (which is extremely unusual). It is much more common to have include files offset from src.
@schungx, the #include is part of the link preprocessor and it doesn't have access to the HTML configuration. It's possible to build a different preprocessor that does the "same", but adding your src at the preprocessor configuration (or change a lot the current one and add the prefix path. I guess that the easiest way to do it will apply it to all "link tags" ({{ #playground }}, {{ #include }}, and {{ #rustdoc_include }})).
If I have some free time I can implement this preprocessor or try to extend/change the current link preprocessor.
The #include tag is what I use to automatically include a file containing URL links in abstract form, so that I can use simple link tags everywhere.
For example, I have links.md:
[`Foo`]: /path/to/foo.md
[`Bar`]: /path/to/bar.md
[baz]: /path/to/baz.md
And then in each file:
{{ #include ../links.md }}
Now I can use [`Foo`] and [`Bar`] and [baz] anywhere I like!
It works very well, except for having to always put in the right number of ../ to reach that particular file.
Is there any update on this?
The PR/Branch proposed seems like a decent fix, and would resolve the issues im having too, but this seems to have died in the water?
Thanks
