Including Files

As the HTML, CSS, or JavaScript on a page grows, managing all of the code in one file can become difficult.

Essepage lets you include content from another file directly at the current position in your code.

{{+ include : /includes/notice.essepage +}}

When the page is built, this expression is replaced with the contents of /includes/notice.essepage.

You can use includes to split long files into smaller files or manage CSS and JavaScript separately.

Components, Imports, and Includes

Components, imports, and includes all load code from another file, but they serve different purposes.

Components and imports are useful when you want to pass content through slots or create reusable structures.

Use an include when you want to insert the contents of a file at the current position without creating a separate element or slot.

Create Files to Include

A file used through an include is not a page that visitors access directly through a URL, so it does not need to be placed inside /public.

You can create an /includes folder at the project root and manage related files there.

/
├── public
│   └── +page.essepage
└── includes
    ├── notice.essepage
    └── contact-message.essepage

The /includes folder name is not required. You can also organize files according to their purpose.

/
├── public
│   └── +page.essepage
├── includes
│   └── notice.essepage
├── styles
│   └── site.css
├── scripts
│   └── site.js
└── content
    └── introduction.md

Keeping shared code and content files outside /public makes them easier to distinguish from page files.

Include a File

Create the following file.

/includes/notice.essepage

Add the following content.

<aside>
    <strong>Notice</strong>

    <p>This website is currently being updated.</p>
</aside>

On the page, add the following expression where you want the file contents to appear.

{{+ include : /includes/notice.essepage +}}

The complete page file looks like this.

<h1>Welcome to Our Website</h1>

{{+ include : /includes/notice.essepage +}}

<p>Explore our latest articles and services.</p>

When the page is built, the following HTML is generated.

<h1>Welcome to Our Website</h1>

<aside>
    <strong>Notice</strong>

    <p>This website is currently being updated.</p>
</aside>

<p>Explore our latest articles and services.</p>

The include expression does not remain in the generated HTML. It is replaced with the contents of the file.

Enter a File Path

Enter the path of the file to include between the colons (:).

{{+ include : /includes/notice.essepage +}}

Entering a file path manually can lead to mistakes in folder or file names.

It is more convenient to copy the path from the editor’s file explorer.

1. Find the file you want to include in the file explorer.
2. Right-click the file.
3. Select Copy Path.
4. Paste the copied path into the include expression.

For a file shared across multiple pages, a full path beginning with /, such as /includes/notice.essepage, is usually easier to understand.

Include File Contents Without Conversion

include inserts the contents of the specified file at the current position without converting them.

{{+ include : /includes/notice.essepage +}}

You can include HTML, plain text, and other file formats.

For CSS, JavaScript, and Markdown files that require type-specific processing, use the corresponding file type instead of include.

{{+ css : /styles/site.css +}}
{{+ javascript : /scripts/site.js +}}
{{+ markdown : /content/introduction.md +}}

When you specify a file type, Essepage processes the file appropriately for that type of code.

Include a CSS File

Long CSS can be separated into its own file.

Create the following file.

/styles/site.css

body {
    margin: 0;
    font-family: system-ui;
}

h1 {
    color: royalblue;
}

Include the CSS file inside the page’s <style> element.

<h1>Welcome to Our Website</h1>

<style>
    {{+ css : /styles/site.css +}}
</style>

If several pages use the same CSS, you can include the CSS file from a layout or shared component.

Include a JavaScript File

JavaScript can also be managed in a separate file.

Create the following file.

/scripts/site.js

const button = document.getElementById("messageButton");
const message = document.getElementById("message");

button.addEventListener("click", () => {
    message.textContent = "Hello from Essepage!";
});

Include the JavaScript file inside the page’s <script> element.

<button id="messageButton">Show Message</button>

<p id="message"></p>

<script>
    {{+ javascript : /scripts/site.js +}}
</script>

This approach is useful when you want to keep the HTML structure visible in the page file while managing JavaScript separately.

Include a Markdown File

You can manage Markdown content in a separate file and load it into a page.

Create the following file.

/content/introduction.md

## Welcome

This content was written in **Markdown**.

Add the following expression to the page.

{{+ markdown : /content/introduction.md +}}

The markdown type automatically converts a Markdown document to HTML, so you do not need to add a separate Markdown conversion library.

For more information about writing and styling Markdown, see Markdown and Styling Markdown.

Include a File in Alpine.js x-data

You can move the code used in an Alpine.js x-data attribute into a separate JavaScript file.

Create the following file.

/scripts/counter.alpine.js

() => ({
    count: 0,

    increase() {
        this.count++;
    }
})

Load it from the x-data attribute as follows.

<head>
    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>
</head>

<div x-data="{{+ x-data : /scripts/counter.alpine.js +}}">
    <p x-text="count"></p>

    <button type="button" @click="increase">
        Increase
    </button>
</div>

The x-data type processes the JavaScript file so that its contents can be used inside an HTML attribute.

When using Alpine.js, this makes it easier to manage x-data code in a separate file.

It can also reduce quote conflicts that may occur when JavaScript code is written directly inside an HTML attribute.

Include Types

Use the appropriate type for the file you want to include.

Includes and External File References

An include inserts the contents of a project file directly into the page.

<style>
    {{+ css : /styles/site.css +}}
</style>

The generated HTML contains the CSS code inside the <style> element.

In contrast, <link> and <script src> instruct the browser to request separate files.

To reference files this way, the actual files must be placed inside /public so visitors’ browsers can access them.

For example, suppose your project contains the following files.

/public/styles/site.css
/public/scripts/site.js

Enter their paths without /public in the URL.

<link rel="stylesheet" href="/styles/site.css">

<script src="/scripts/site.js"></script>

The two approaches work differently.

Use an include when you want to place code directly in the page. Use <link> or <script src> when you want the browser to load an independent file.

Edit and Check an Included File

An included file is used as part of a page, so check the result through a page that includes it.

1. Open the page that includes the file in the preview.
2. Edit the included file.
3. Save the file.
4. Reload the preview.
5. Confirm that the file contents appear in the correct position.

Includes rebuild the page when the file is saved, so Live Preview may not update the changes immediately.

If the changes do not appear, save the file and reload the preview.

Apply Changes to the Live Site

Saving an included file updates the development environment and preview. Saving alone does not change the live site.

If one file is used by multiple pages, changing that file may affect several pages.

After checking the relevant pages in the preview, use Apply All to apply the changes to the live site.

It may take up to one minute for the cache to update after applying the changes.

If a File Is Not Included

If the file contents do not appear or the code does not work as expected, check the following.

• Are the beginning and end of the include expression correct?
• Is the type name, such as include, css, or javascript, correct?
• Is the file path correct?
• Did you save the file being included?
• Does the page currently open in the preview actually use the file?
• Did you reload the preview after saving the file?
• If you are checking the live site, did you use Apply All?

If you are unsure whether the path is correct, use Copy Path in the file explorer and enter it again.

If the file appears but its CSS or JavaScript does not work as expected, make sure you used the appropriate include type.

Next Steps

After learning how to include files, continue with the following documents.

• Write content with Markdown: Markdown
• Style Markdown content: Styling Markdown
• Manage CSS and image files: CSS and Assets
• Create reusable elements: Components
• Use files as custom tags: Imports
• Apply shared-file changes across the site: Shared Files and Site-Wide Updates