Merge pull request #338 from dairiki/feature.lektor-pr992

Documentation updates for lektor/lektor#992
This commit is contained in:
Jeff Dairiki 2022-07-27 20:27:07 -07:00 committed by GitHub
commit 6f3d75186e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 105 additions and 20 deletions

File diff suppressed because one or more lines are too long

File diff suppressed because one or more lines are too long

View File

@ -4,16 +4,32 @@ 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`.
An explicit value for `alt` may be specified via the `alt` parameter to `url_to`.
Alternatively, an `alt` query arg may be included in the `path` parameter.
For example, `src.url_to('/', alt='de')` is equivalent to `src.url_to('/?alt=de')` — both return the URL to the root of the site with `alt=de`.
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,45 @@ 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
```
## Linking to a Specific Alt
When links are resolved through the Lektor database, URLs to specific _alt_s may be obtained by adding an `alt` query arg to the link.
For example, to link to the current page, but in the French alt:
```md
Here is the [French version of the blog](/blog?alt=fr).
```

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/

View File

@ -19,19 +19,31 @@
{%- endmacro %}
{% macro get_doc_link(page) -%}
<a href="{{ page|url }}">{{ page.title }}{%
if page.type == 'function' or page.type == 'method' %}(){% endif %}</a>
<a href="{{ page|url }}">
{{- page.title -}}{% if page.type in ('function', 'method') %}(){% endif -%}
</a>
{%- endmacro %}
{% macro get_doc_header(page) %}
{% if page.type %}
<h1>{% if page.type %}{{ get_doc_icon(page) }} {% endif %}{%
if page.module %}<code class="mod">{{ page.module }}.</code>{% endif
%}<code class="obj">{{ page.title }}</code>{%
if (page.type == 'method' or page.type == 'function' or page.type == 'filter'
or page.type == 'event') or page.signature
%} <span class="sig">(<code>{{ page.signature }}</code>)</span>{% endif %}</h1>
<h1>
{%- if page.type %}{{ get_doc_icon(page) }} {% endif %}
{%- if page.module %}<code class="mod">{{ page.module }}.</code>{% endif -%}
<code class="obj">{{ page.title }}</code>
{%- if page.signature or page.type in ('method', 'function', 'filter', 'event') %}
<span class="sig">({{ format_signature(page.signature) }})</span>
{%- endif -%}
</h1>
{% else %}
<h1>{{ page.title }}</h1>
{% endif %}
{% endmacro %}
{% macro format_signature(signature) -%}
{% if signature|trim -%}
{% set sep = joiner(" ") -%}
{% for param in signature.split(',')|map('trim') -%}
{{ sep() }}<code>{{ param }}{% if not loop.last %},{% endif %}</code>
{%- endfor -%}
{% endif -%}
{% endmacro %}

View File

@ -221,6 +221,13 @@ div.blog-snippet {
div.doc-styling, div.blog-post, div.plugin {
line-height: 1.75;
h1 {
text-indent: -2em;
padding-left: 2em;
.glyphicon {
text-indent: 0;
}
}
a.ref {
font-style: italic;
}