<li><ahref="#external-and-absolute-urls">External and Absolute URLs</a></li>
</ul>
</div>
</div>
<divclass="col-sm-9 doc-styling">
<h1>URLs and Slugs</h1>
<ulclass=page-meta>
</ul>
<p>Lektor's URLs in general mirror what happens on the file system as much as
possible. There are however various cases in which this behavior can be
changed.</p>
<h2id="a-url-is-composed-of-slugs">A URL Is Composed of Slugs</h2><p>Each page in Lektor is associated with a string called a <em>slug</em>. The full
URL of a page is its own slug concatenated with the slug of each its parents.</p>
<p>The default slug is the ID of the page. So the page
<code>content/foo/bar/contents.lr</code> has the default slug <code>bar</code>, its parent has the
default slug <code>foo</code>, and its default URL would be <code>/foo/bar/</code>.</p>
<h2id="slug-customization">Slug Customization</h2><p>Slugs can be customized. They can even contain slashes (see below). There are
three systems that control what the slug looks like:</p>
<h3id="folder-name">Folder Name</h3><p>The name of the folder that contains the <code>contents.lr</code> file is the ID of the
page and thus the default slug (unless changed by the model — more about that
later). This means that you could for instance just rename the folder to
get a different slug. This is the recommended way for the majority of pages
to adjust the slug.</p>
<h3id="the-slug-system-field">The <code>_slug</code> System Field</h3><p>The second option is to use the <code>_slug</code> system field. This field is available
for all models automatically and overrides the slug explicitly. This is
particularly useful to force a slug that could not be represented on the file
system (for instance because it should contain a slash) or because you want
to change the slug for a different <ahref="../alts/"class="ref">Alternative</a>. As
an example a page translated to German might want to translate the slug as well.</p>
<h3id="implied-slug-configuration">Implied Slug Configuration</h3><p>The last part is a system that controls the implied slugs. In particular it
means that the model of the parent page can override the default slug for all
of the children below it. This for instance can be used to automatically add
the date of a blog post into the slug. For more information about this
feature see <ahref="../../models/children/"class="ref">Children & Pagination</a>.</p>
<h2id="slugs-containing-slashes">Slugs Containing Slashes</h2><p>Slugs can indeed contain slashes. It's perfectly valid for a page to have
<code>2015/5/demo</code> as slug, and it will still be incorporated into URLs as described
above. What's not possible is for a page to pretend that it belongs to a
different parent. The parent paths are always added to it. So once a page
has a parent page <code>/foo</code> its URL path will always begin with the URL path of
the page <code>foo</code>.</p>
<h2id="extensions-and-file-types">Extensions and File Types</h2><p>The default behavior for a page is to build into a hidden <code>index.html</code> file.
This means that if you have a page called <code>foo/bar/contents.lr</code> it will
build into a file named <code>foo/bar/index.html</code>. Web servers typically look for
an <code>index.html</code> file in a folder which is why you can just access <code>/foo/bar/</code>
and the page will render.</p>
<p>If however the last path component contains a period (<code>.</code>) then the last path
component is assumed to be a filename directly. This means that if you set
the slug of a page to <code>404.html</code> for instance, the page will indeed render
into <code>404.html</code> and not <code>404/index.html</code>.</p>
<p>However you need to be careful with this as web servers pick the “mimetype”
of a file based on the extension. So if you name a file <code>foo.html</code> it will
behave very differently compared to a file named <code>foo.txt</code>. So do not name
your files in ways that would be incompatible with what the web server
renders. This however also allows you to generate files that are not
HTML. For instance you could render into a <code>.xml</code> file if that is what
you want.</p>
<p>This feature is called “Dotted Slugs” and there are some specifics with
regards to how these are handled.</p>
<h2id="content-below-dotted-slugs">Content Below Dotted Slugs</h2><p>One specific behavior of a path component that contains a dotted slug is that
content below that path need to move to a different location. Imagine for
instance you named the page <code>404.html</code> but that page has an attachment. As
<code>404.html</code> is now a file it's impossible for a folder with the same name to
exist. This means that the attachments have to be stored elsewhere. The
convention for this in Lektor is to prefix the path with an underscore. So
if <code>404.html</code> has an attachment named <code>foo.jpeg</code> it will move into
<code>_404.html/foo.jpeg</code>.</p>
<h2id="external-and-absolute-urls">External and Absolute URLs</h2><p>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 relative URLs. In this case the absolute URL path has
to be configured.</p>
<p>You can pick the default for URL generation in the project configuration.
Please enable JavaScript to view the <ahref="https://disqus.com/?ref_noscript"
rel="nofollow">comments powered by Disqus.</a>
</noscript>
</div>
</div>
</div>
</div>
</div>
<divclass="bottomsummary">
<divclass="container">
</div>
</div>
<footer>
<divclass="container">
<divclass="row">
<divclass="col-sm-4 icon-bar">
<ahref="https://github.com/lektor/lektor/"title="Lektor on GitHub"
><iclass="fa fa-github"></i></a>
<ahref="https://github.com/lektor/lektor/issues/"title="Report Issues for Lektor"
><iclass="fa fa-bug"></i></a>
<ahref="https://twitter.com/getlektor"title="Find Lektor on Twitter"
><iclass="fa fa-twitter"></i></a>
<ahref="https://gitter.im/lektor/lektor"title="Chat on Gitter"
><iclass="fa fa-comment"></i></a>
<ahref="https://github.com/lektor/lektor-website/tree/master/content/docs/content/urls/contents.lr"title="View source for this page"><iclass="fa fa-code"></i></a>
