Force-subdirectory UrlRelative policy

[notriddle]

If you put this in your GitHub repo's README.md file:

<p>Please read the <a href="/CONTRIBUTING.md">contributing</a> document.</p>

It'll end up translating it to this:

<p>Please read the <a rel="nofollow noopener" href="https://github.com/notriddle/ammonia/blob/master/CONTRIBUTING.md">contributing</a> document.</p>

Ammonia does not offer a URL resolver that allows people to implement that, and it probably should.

---

I would guess the API would be something like this:

enum UrlRelative<'a> {
    ...
    /// Force absolute and relative paths into a particular directory.
    ///
    /// Note that the resolver does not affect fully-qualified URLs,
    /// so it doesn't prevent users from linking wherever they want.
    /// This feature only serves to make content more portable.
    ///
    /// # Examples
    ///
    /// | root | path | url | result |
    /// |------|------|-----|--------|
    /// | https://github.com/notriddle/ammonia/blob/master/ | /README.md | | https://github.com/notriddle/ammonia/blob/master/README.md |
    /// | https://github.com/notriddle/ammonia/blob/master/ | /README.md | / | https://github.com/notriddle/ammonia/blob/master/ |
    /// | https://github.com/notriddle/ammonia/blob/master/ | /README.md | /CONTRIBUTING.md | https://github.com/notriddle/ammonia/blob/master/CONTRIBUTING.md |
    /// | https://github.com | /notriddle/ammonia/blob/master/README.md | | https://github.com/notriddle/ammonia/blob/master/README.md |
    /// | https://github.com | /notriddle/ammonia/blob/master/README.md | / | https://github.com |
    /// | https://github.com | /notriddle/ammonia/blob/master/README.md | CONTRIBUTING.md | https://github.com/notriddle/ammonia/blob/master/CONTRIBUTING.md |
    /// | https://github.com | /notriddle/ammonia/blob/master/README.md | /CONTRIBUTING.md | https://github.com/CONTRIBUTING.md |
    RewriteWithRoot {
        /// The URL that is treated as the root by the resolver.
        root: &'a str,
        /// The "current path" used to resolve relative paths.
        path: &'a str,
    }
}

RewriteWithRoot

Force absolute and relative paths into a particular directory.

Note that the resolver does not affect fully-qualified URLs, so it doesn't prevent users from linking wherever they want. This feature only serves to make content more portable.

Examples

root	path	url	result
https://github.com/notriddle/ammonia/blob/master/	/README.md		https://github.com/notriddle/ammonia/blob/master/README.md
https://github.com/notriddle/ammonia/blob/master/	/README.md	/	https://github.com/notriddle/ammonia/blob/master/
https://github.com/notriddle/ammonia/blob/master/	/README.md	/CONTRIBUTING.md	https://github.com/notriddle/ammonia/blob/master/CONTRIBUTING.md
https://github.com	/notriddle/ammonia/blob/master/README.md		https://github.com/notriddle/ammonia/blob/master/README.md
https://github.com	/notriddle/ammonia/blob/master/README.md	/	https://github.com
https://github.com	/notriddle/ammonia/blob/master/README.md	CONTRIBUTING.md	https://github.com/notriddle/ammonia/blob/master/CONTRIBUTING.md
https://github.com	/notriddle/ammonia/blob/master/README.md	/CONTRIBUTING.md	https://github.com/CONTRIBUTING.md

[notriddle]

@lnicola https://github.com/notriddle/ammonia/pull/50#issuecomment-331962179

Just one concern, does #48 obsolete UrlRelative::RewriteWithBase?

It would be possible, by picking apart the URL and putting the domain part in base and the path part in path, to emulate RewriteWithBase using RewriteWithRoot.

However, if the user has a URL, RewriteWithBase is easier, so I don't think it would be obsolete. For example, it looks like the Discourse could use RewriteWithBase("https://user.rust-lang.org/") for all the user-submitted links.

[lnicola]

Right, then.

@Eijebong, any opinions on an RC?

[Eijebong]

👍 on doing an RC release.