This commit is contained in:
Jeff Dairiki 2022-02-26 15:16:43 -08:00
parent 5874282667
commit 188e46d997
3 changed files with 64 additions and 10 deletions

View File

@ -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

View File

@ -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
```

View File

@ -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
<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/