<li><ahref="#alternatives-and-paths">Alternatives and Paths</a></li>
</ul>
</div>
</div>
<divclass="col-sm-9 doc-styling">
<h1>Paths</h1>
<ulclass=page-meta>
</ul>
<divclass="admonition admonition-info"><p>This refers mostly to Lektor 2.0. If you are using an older version of
Lektor the virtual path feature is not implemented yet and a lot of this just
does not apply.</p></div><p>Lektor attempts to map the paths from the content folder as closely as possible
to the final URLs (at least in the default configuration). There are various
ways in which this can be customized (see <ahref="../urls/"class="ref">URLs and Slugs</a>) and
there are situations in which Lektor needs to render out content that does not
actually directly correspond to a path on the file system.</p>
<p>Here we try to explain how the path system in Lektor works and what it means.</p>
<h2id="what-is-a-path">What is a Path</h2><p>A path in Lektor is a string that uniquely identifies a <ahref="../../api/db/obj/"class="ref">Source Object</a>. For the most part these directly point to
<code>content.lr</code> files or attachments therein. These paths always use forward
slashes, no matter on which platform Lektor runs. So for instance if you
have a file named <code>projects/my-project/contents.lr</code> then the path for this
record will be <code>/projects/my-project</code>. Thereby it does not matter if the
slug or final URL was changed, the path is always the same.</p>
<p>Lektor uses paths to refer to records by default in all cases. This means that
if you use the <ahref="../../api/templates/filters/url/"class="ref">url filter</a> for instance
it will operate on paths and not URLs!</p>
<p>But what about sources that do not directly correspond to something on the
file system? This is where virtual paths come in. Virtual paths are
separated from physical paths with an at (<code>@</code>) sign. Virtual paths are always
attached to a record and point to things that are not actually coming from the
content folder but something else.</p>
<p>Virtual paths are for instance used to refer to paginated pages or to some
resources that plugins add.</p>
<h2id="virtual-paths">Virtual Paths</h2><p>Virtual paths are added behind physical paths and are separated by an at
sign (<code>@</code>). The only virtual path that is supported by Lektor out of the box
is the special numeric virtual path which can be used to refer to specific
pages for a pagination. For instance <code>/blog@1</code> refers to the first page of
the <code>blog</code> page, <code>/blog@2</code> to the second etc. There are however plugins that
add virtual paths to refer to their own resources. For instance a plugin can
register <code>/blog@feed</code> to refer to a RSS/Atom feed for the blog.</p>
<h2id="relative-paths">Relative Paths</h2><p>Now that we talked a bit about paths, we should probably cover how relative
paths work. Relative paths work similar to how you expect them to work on
most operating systems but they can operate on the virtual as well as the
physical path. There is also some special behavior with regards to the numeric
virtual path for pagination.</p>
<p>For the most part <code>.</code> refers to the same page and <code>..</code> refers to the page one
level up. If you use a path that just contains of a virtual path, then it's
attached to the current page to replace the active virtual path.</p>
<table>
<thead><tr>
<th>Current</th>
<th>Relative</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>/blog</code></td>
<td><code>..</code></td>
<td><code>/</code></td>
</tr>
<tr>
<td><code>/blog</code></td>
<td><code>.</code></td>
<td><code>/blog</code></td>
</tr>
<tr>
<td><code>/blog/post</code></td>
<td><code>..</code></td>
<td><code>/blog</code></td>
</tr>
<tr>
<td><code>/blog</code></td>
<td><code>@2</code></td>
<td><code>/blog@2</code></td>
</tr>
<tr>
<td><code>/blog@2</code></td>
<td><code>@1</code></td>
<td><code>/blog@1</code></td>
</tr>
<tr>
<td><code>/blog@feed</code></td>
<td><code>recent</code></td>
<td><code>/blog@feed/recent</code></td>
</tr>
<tr>
<td><code>/blog@feed</code></td>
<td><code>..</code></td>
<td><code>/blog@feed</code></td>
</tr>
</tbody>
</table>
<p>However! The numeric path is special with regards because it's considered to
belong to the current page:</p>
<table>
<thead><tr>
<th>Current</th>
<th>Relative</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>/blog@2</code></td>
<td><code>.</code></td>
<td><code>/blog@2</code></td>
</tr>
<tr>
<td><code>/blog@2</code></td>
<td><code>..</code></td>
<td><code>/</code></td>
</tr>
</tbody>
</table>
<h2id="alternatives-and-paths">Alternatives and Paths</h2><p>If you have used Lektor a bit you might be wondering how <ahref="../alts/"class="ref">Alternatives</a> work with paths. The answer might be surprising but it's
basically that they don't really work with paths. Alternatives are
implemented on a level higher than paths. If you have a page that exists
in both German and English alternative then they will have the same path.
The alternative code is supplied separately.</p>
<p>This is done so that you can later start introducing alternatives to sites
that were never aware of them without having to go everywhere and start
passing alternative information around. While there are indeed some places
where you might have to perform some changes (especially if you perform
manual queries in the templates) for the most part adding alternatives to an
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/paths/contents.lr"title="View source for this page"><iclass="fa fa-code"></i></a>
