Documentation for lektor/lektor#992

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.
+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.
+
+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

content/docs/api/db/types/markdown/contents.lr

@@ -36,3 +36,37 @@ type = markdown
   {{ this.body }}
 </div>
 ```
+
+## 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
+```

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
+To override this behavior, pass `resolve=False` (or, alternatively,
-no resolving will take place.
+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
-<a href="{{ '!/'|url }}">To Root</a>
+<a href="{{ '/'|url(resolve=False) }}">To Root</a>
 ```
+
+## 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/