Pages
Pages are the most essential components of our platform, that define content displayed at a given path. All pages have to be located in the views/pages directory. Each page is represented by a single file with liquid extension.
Each page is accessible on the URL indicated by its location in the codebase if not otherwise specified in the page configuration slug property. For example, the page app/views/pages/get-started/hello-world.liquid deployed to the domain https://example.com will be automatically accessible at https://example.com/get-started/hello-world.
Note
In examples, we often add the slug property to show where the page will be accessible, even if it would not be required because it is the same as the default.
Page configuration
All page configuration is optional, but you can use page configuration to overwrite defaults.
See below a sample page configuration file:
app/views/pages/my-page.md.liquid
---
layout_name: my_custom_layout
converter: markdown
---
# Welcome to My Page
A paragraph explaining what I do.
Explanation:
layout_name: my_custom_layout: The page uses the layoutviews/layouts/my_custom_layout.liquid.converter: markdown: It converts markdown in the body of the page to HTML.searchable: true: It is indexed and accessible via GraphQL query.
Available properties
| Property | Description | Options | Default | Required |
|---|---|---|---|---|
| authorization_policies | Array of authorization policies run before rendering the page | No | ||
| converter | markdown | No | ||
| handler | No | |||
| layout_name | Defines which layout from views/layouts/ you would like to use for pages with html format. If you don't want to use any layout, set it to an empty string. It will be equivalent to just rendering page content. Note: Currently, excluding this property altogether will cause the page to use the layout last used for the current page. If no layout has been used, it will use the default application layout. |
application |
No | |
| max_deep_level | Defines what is the intended nesting level of the slug. For example, if the slug is test and you set max deep level to 1, then path like /test/something will raise 404. However, if you set it to 2, then it will render the page. This is useful for SEO to avoid duplicated content. |
positive integer | No | |
| metadata | Object that you can define and access via context.page.metadata in different places |
No | ||
| method | get post put delete |
get | No | |
| redirect_code | Status that should be added to http response | 301 302 |
302 | No |
| redirect_to | URL to a page you want to redirect | No | ||
| response_headers | JSON object that you can define to override most of the http headers | No | ||
| searchable | Indication that this page should be indexed and accessed via GraphQL query | true | false | No |
| slug | Use the slug property to overwrite the default slug. |
The default slug is automatically created based on the page's location in the codebase. For example, a page app/views/pages/get-started/hello-world.liquid has the default slug get-started/hello-world. |
No |
Everything after the front matter is the body of the page.
Homepage
The Homepage slug is /, which will work for both https://example.com and https://example.com/. The slug of the file app/views/pages/home.liquid defaults to /. See this sample file for configuring the home page:
app/views/pages/home.html.liquid
<h1>Welcome to my home page</h1>
<p>A paragraph explaining what we do</p>
Formats
To define which format the endpoint will be available for, place .<format> before the file extension.
| Format name | Example filename |
|---|---|
| html | about-us.html.liquid |
| xml | orders.xml.liquid |
| csv | users-report.csv.liquid |
| json | coordinates.json.liquid |
| rss | feed.rss.liquid |
| css | datepicker.css.liquid |
| js | server-constants.js.liquid |
| purchase-order.pdf.liquid | |
| txt | notes.txt.liquid |
| ics | calendar.ics.liquid |
Warning
For PDF it is only possible to render plain text. We are working on enhancing this feature by allowing to include images.Accessing different formats
You can have multiple pages with the same slug, but with different formats, and access them at the same time.
For example, you can have both html, pdf and txt version of a page with Hello world:
app/views/pages/hello.html.liquid
Will be accessible under URL: https://example.com/hello
Hello world
app/views/pages/hello.pdf.liquid
Will be accessible under the URL: https://example.com/hello.pdf
Hello world
app/views/pages/hello.txt.liquid
Will be accessible under the URL: https://example.com/hello.txt
Hello world
Note that the html format is implicit, default, you don't need to specify it in the URL.