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

Documentation updates for lektor/lektor#992

content/docs/api/db/obj/url-to/contents.lr

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

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

@@ -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).
+```

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

templates/macros/docs.html

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

webpack/scss/main.scss

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