From b5dfaf3c2d29785f6b6aaefecd527823302873c4 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Sat, 19 Dec 2015 21:24:52 +0100 Subject: [PATCH] Documented URL styles --- Website.lektorproject | 1 + content/docs/api/db/obj/url-to/contents.lr | 7 +++++-- content/docs/api/utils/url-to/contents.lr | 19 ++++++++++++++++++ content/docs/content/urls/contents.lr | 20 ++++++++++++------- content/docs/project/file/contents.lr | 23 ++++++++++++++++++++++ 5 files changed, 61 insertions(+), 9 deletions(-) create mode 100644 content/docs/api/utils/url-to/contents.lr diff --git a/Website.lektorproject b/Website.lektorproject index d227475b..a5da2add 100644 --- a/Website.lektorproject +++ b/Website.lektorproject @@ -1,6 +1,7 @@ [project] name = Lektor url = https://www.getlektor.com/ +url_style = absolute [servers.production] enabled = yes diff --git a/content/docs/api/db/obj/url-to/contents.lr b/content/docs/api/db/obj/url-to/contents.lr index 41518bec..6e9bbc45 100644 --- a/content/docs/api/db/obj/url-to/contents.lr +++ b/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 diff --git a/content/docs/api/utils/url-to/contents.lr b/content/docs/api/utils/url-to/contents.lr new file mode 100644 index 00000000..192b217f --- /dev/null +++ b/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. diff --git a/content/docs/content/urls/contents.lr b/content/docs/content/urls/contents.lr index 38149299..613b57f6 100644 --- a/content/docs/content/urls/contents.lr +++ b/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. -This makes it possible to easily host a website below a certain folder -without having to do anything special to make this work. However there are -some features which will require the use of an absolute URL. For instance -sitemaps or Atom feeds do not work with realtive URLs. In this case the -absolute URL path has to be configured. +Lektor by default will prefer relative URLs. This makes it possible to easily +host a website below a certain folder without having to do anything special to +make this work. However there are some features which will require the use of +an absolute or fully canonical (external) URL. For instance sitemaps or Atom +feeds do not work with realtive URLs. In this case the absolute URL path has +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. diff --git a/content/docs/project/file/contents.lr b/content/docs/project/file/contents.lr index 766aecf5..0bf30993 100644 --- a/content/docs/project/file/contents.lr +++ b/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: