Documented URL styles

Website.lektorproject

@@ -1,6 +1,7 @@
 [project]
 name = Lektor
 url = https://www.getlektor.com/
+url_style = absolute
 
 [servers.production]
 enabled = yes

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

@@ -4,7 +4,7 @@ summary: Generates a URL relative to another path.
 ---
 type: method
 ---
-signature: path, alt=None, absolute=False, external=False
+signature: path, alt=None, absolute=None, external=None
 ---
 body:
 
@@ -17,7 +17,10 @@ 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
-domain part to the URL (if configured).
+domain part to the URL (if configured).  The default behavior is to use the
+configured URL style (which is `relative`) unless absolute or external were
+explicitly provided.  For more information read about this in the
+[Project Configuration :ref](../../../../project/file/#[project]).
 
 ## Example
 

content/docs/api/utils/url-to/contents.lr

@@ -0,0 +1,19 @@
+title: url_to
+---
+summary: Calculates the URL to a specific page realtive to the current.
+---
+type: function
+---
+module: lektor.context
+---
+signature: path, alt=None, absolute=None, external=None
+---
+body:
+
+Calculates the URL from the current source object on the context 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.  If no `alt` is provided the `alt` of the page is used.
+
+This works exactly the same as [the method with the same name
+:ref](../../db/obj/url-to/) on source objects.

content/docs/content/urls/contents.lr

@@ -92,12 +92,18 @@ if `404.html` has an attachment named `foo.jpeg` it will move into
 
 ## External and Absolute URLs
 
-Lektor will generally prefer relative URLs when it has a choice to use them.
+Lektor by default will prefer relative URLs.  This makes it possible to easily
-This makes it possible to easily host a website below a certain folder
+host a website below a certain folder without having to do anything special to
-without having to do anything special to make this work.  However there are
+make this work.  However there are some features which will require the use of
-some features which will require the use of an absolute URL.  For instance
+an absolute or fully canonical (external) URL.  For instance sitemaps or Atom
-sitemaps or Atom feeds do not work with realtive URLs.  In this case the
+feeds do not work with realtive URLs.  In this case the absolute URL path has
-absolute URL path has to be configured.
+to be configured.
 
-To see how this can be configured see [Project Configuration
+You can pick the default for URL generation in the project configuration.
+For more information read about the [Project Configuration
 :ref](../../project/file/#[project]).
+
+The default of `relative` a realtive URL style means that you can deploy a
+website to a sub folder without any configuration, however most likely custom
+404 pages will fail to find the needed assets.  Fully canonical URLs are not
+recommended as default style.

content/docs/project/file/contents.lr

@@ -45,6 +45,29 @@ This section controls some basics about the project:
 > some systems might need it.  For instance sitemaps require full URLs and
 > not having them would be a violation of the specification.
 
+`url_style`
+> This controls the style of generated URL references through the
+> [url_to :ref](../../api/utils/url-to/) function or filters.  The default
+> value for this is `relative`.  The following values are possible:
+>
+> | Value      | Behavior
+> | ---------- | -----------
+> | `relative` | URLs are generated relative to the currently active page.
+> | `absolute` | URLs are generated absolute (relative to root page)
+> | `external` | URLs are generated with the fully canonical URL (external).
+>
+> There are advantages and disadvantages to all styles.  `relative` has the
+> benefit that it works without any configuration no matter where you deploy
+> to.  The downside is that you cannot have a page appear on multiple paths
+> which for instance breaks custom error pages.  `absolute` is useful for
+> situations where you have custom error pages and you generally know a bit
+> about the server you are deploying to.  `external` generally makes not a lot
+> of sense as default setting but exists for consistency's sake.
+>
+> For individual URLs that are generated with the [url_to
+> :ref](../../api/utils/url-to/) function it's possible to override the
+> default URL style.
+
 `path`
 > This setting can be used to configure a different path for the project
 > tree.  This requires a bit of explanation: