diff --git a/content/docs/api/db/obj/url-to/contents.lr b/content/docs/api/db/obj/url-to/contents.lr
index 6e9bbc45..90f33542 100644
--- a/content/docs/api/db/obj/url-to/contents.lr
+++ b/content/docs/api/db/obj/url-to/contents.lr
@@ -4,16 +4,28 @@ summary: Generates a URL relative to another path.
---
type: method
---
-signature: path, alt=None, absolute=None, external=None
+signature: path, alt=None, absolute=None, external=None, base_url=None, resolve=None, strict_resolve=None
---
body:
Calculates the URL from the current source object to the given other source
-object. Alternatively a path can also be provided instead of a source object.
-If the path starts with a leading bang (``!``) then no resolving is performed.
+object. Alternatively, a path can also be provided instead of a source object.
+
+This is what the [`|url` filter](../../../templates/filters/url/) uses
+internally to generate URLs.
+
+If `resolve` is not `False`, then (so long as `path` is not a URL
+containing either a _scheme_ or a _netloc_) an attempt is made to
+resolve `path` via the [Lektor database](../../) to a _source object_,
+then the URL of that source object is used. If database-resolution of
+the path fails, then the path is interpreted as a URL-path, or, if
+`strict_resolve` is `True`, an error is raised.
+
+If the path starts with a leading bang (``!``) then no resolving is
+performed. This is equivalent to passing `resolve=False`.
+
If no `alt` is provided the `alt` of the page is used.
-This is what the `|url` filter uses internally to generate URLs.
In addition to that `absolute` can enforce the URL to be absolute instead of
relative to the current page and `external` can be used to also add the
diff --git a/content/docs/api/db/types/markdown/contents.lr b/content/docs/api/db/types/markdown/contents.lr
index 25ec01a4..f9f26701 100644
--- a/content/docs/api/db/types/markdown/contents.lr
+++ b/content/docs/api/db/types/markdown/contents.lr
@@ -36,3 +36,37 @@ type = markdown
{{ this.body }}
```
+
+## Resolution of Links
+
+The way in which links in Markdown fields are resolved to URLs can be
+controlled using the `resolve_links` field option. There are three
+possible values for the option:
+
+- `resolve_links = never`
+ Never resolve links to Lektor source objects. This was the link
+ resolution behavior for all versions of Lektor before *FIXME*.
+
+- `resolve_links = when-possible`
+ This is the new default behavior. When possible, links are resolved
+ to Lektor [source objects](../../obj/), then the URL to those
+ source objects is used. When the resolution to a source object
+ fails, the links are interpreted as URL paths.
+
+- `resolve_links = always`
+ Resolve links to Lektor source objects, then use the URL of those
+ source objects. If that resolution fails, an error is raised.
+
+The `resolve_links` option only applies to Markdown links that do not
+include an explicit _scheme_ or _netloc_.
+
+As an example, to force the old behavior, wherein links were never
+resolved via the Lektor database, configure a `markdown` field like
+so:
+
+```ini
+[fields.body]
+label = Body
+type = markdown
+resolve_links = never
+```
diff --git a/content/docs/api/templates/filters/url/contents.lr b/content/docs/api/templates/filters/url/contents.lr
index 2bcda92a..64875441 100644
--- a/content/docs/api/templates/filters/url/contents.lr
+++ b/content/docs/api/templates/filters/url/contents.lr
@@ -4,7 +4,7 @@ type: filter
---
summary: Generates a relative URL from the current page to another.
---
-signature: alt=None, absolute=None, external=None
+signature: alt=None, absolute=None, external=None, resolve=None, strict_resolve=None
---
body:
@@ -19,10 +19,10 @@ as the final URLs. This is important when a page forcefully overrides the
URL path. In this case it could be that linking to `/project` for instance
would generate the URL `de/projekte/` if that's what's configured.
-If you want to override this behavior you can prefix the URL with `!` and
-no resolving will take place.
+To override this behavior, pass `resolve=False` (or, alternatively,
+prefix the URL with `!`) and no resolving will take place.
-Note that the URL filter always generates a relative URL. So for instance
+Note that, by default, the URL filter always generates a relative URL. So for instance
if you are currently at `/info/about/` and you want to link to `/projects/`
it will generate a link in the form of `../../projects/`. This makes it
possible to easily deploy the website to a folder outside of the root of
@@ -44,9 +44,17 @@ Same page to other alternative:
```
If you already know 100% where to link to, and you do not want any resolving
-to take place, then you can prefix a path with `!`. For instance this always
+to take place, then pass `resolve=False`. For instance this always
links to the root of the website:
```html+jinja
-To Root
+To Root
```
+
+## Details
+
+Internally, this filter uses [SourceObject.url_to][url-to]. See the
+[documentation for that method][url-to] to read more about the details
+of that process.
+
+[url-to]: ../../../db/obj/url-to/