Markdown Live Preview

When you save a file, the preview page reloads so you can check the changes.

This is sufficient when editing a short page. However, when writing a long Markdown document or repeatedly revising its content, saving the file and waiting for the page to reload can interrupt your workflow.

Markdown Live Preview lets you see the converted result in the preview while writing Markdown, without saving the file.

Essepage supports Markdown Live Preview in the following two ways:

Before You Begin

To use Live Preview, the page you want to check must be open in the preview.

Essepage can open published pages in the preview. If you created a new page or Article File, save and publish it first.

1. Find the page file in the file explorer.
2. Right-click the file.
3. Select Preview.
4. Edit the Markdown while the preview is open.

If you want to use the preview without displaying the page on the published site, publish the page and then hide it while you work.

See Saving, Publishing, and Applying to learn how to publish and hide a page.

Live Preview for Inline Markdown

When using <essepage-markdown> inside HTML, start the id of the element wrapping the Markdown with an underscore (_).

<article id="_live">
    <essepage-markdown>
# About Us

We create tools that help people build websites.

## Our Strengths

- Easy to use
- Works in the browser
- No server setup
    </essepage-markdown>
</article>

In this example, the id of the <article> is set to _live.

<article id="_live">

Essepage recognizes an area with an id beginning with an underscore as a Live Preview target.

Open the page in the preview and edit a heading or list inside <essepage-markdown>. The converted HTML result appears in the preview without saving the file.

You can choose any name for the id, but it must begin with an underscore.

<article id="_markdown">

<section id="_article-content">

If a page contains multiple Live Preview areas, assign a different id to each one.

Live Preview for Article Files

An Article File such as @title.md does not contain an HTML element that wraps its content.

The Markdown in an Article File is converted to HTML and displayed at the <essepage-slot> position in a layout. To use Live Preview with an Article File, you need to connect the file to the layout element where its Markdown content is displayed.

Consider the following file structure:

/public
└── docs
    ├── +layout.essepage
    └── @title.md

• /public/docs/@title.md: An Article File written in Markdown
• /public/docs/+layout.essepage: The layout applied to the Article File

Configuring the Article File

Add the following comment near the top of /public/docs/@title.md.

<!-- {{! article_live_preview_parent_id : docs-main-content !}} -->

# Getting Started

Welcome to our documentation.

## Introduction

This guide will help you get started.

For article_live_preview_parent_id, enter the id of the layout element where the Markdown content is displayed.

The value used in this example is:

docs-main-content

The setting is written inside an HTML comment, so it does not appear in the content of the published page.

Configuring the Layout

In /public/docs/+layout.essepage, wrap <essepage-slot> in an element and assign it the same id.

<header>
    <a href="/">My Documentation</a>
</header>

<article id="docs-main-content">
    <essepage-slot></essepage-slot>
</article>

<footer>
    <p>© My Documentation</p>
</footer>

The article_live_preview_parent_id in the Article File must exactly match the id of the layout element.

article_live_preview_parent_id in @title.md
             ↓
matching id in +layout.essepage
             ↓
<essepage-slot> inside that element

Essepage uses this setting to find the area in the preview where the converted Markdown from the Article File should appear.

For Inline Markdown, the id of the Live Preview area begins with an underscore. However, the id of the layout element connected to an Article File through article_live_preview_parent_id does not need to begin with an underscore.

Checking Live Preview for an Article File

After completing the setup, check Live Preview as follows:

1. Save the @title.md file.
2. Save the +layout.essepage file.
3. Publish the Article File if it has not been published.
4. Right-click the Article File.
5. Select Preview.
6. Edit the Markdown in the Article File while the preview is open.

When you edit a heading, paragraph, or list, the docs-main-content area in the layout updates in real time.

When adding or changing the setup for the first time, save the files and reload the preview page once. You can then see the result in real time while editing the Markdown.

Using Live Preview with Multiple Article Files

Multiple Article Files in the same folder can use the same layout.

/public
└── docs
    ├── +layout.essepage
    ├── @introduction.md
    ├── @installation.md
    └── @configuration.md

You can add the same setting to each Article File.

<!-- {{! article_live_preview_parent_id : docs-main-content !}} -->

In the layout, assign the corresponding id to the element where the Markdown content is displayed.

<article id="docs-main-content">
    <essepage-slot></essepage-slot>
</article>

Open each Article File in the preview to use Markdown Live Preview in the same layout area.

Saving Your Work

Live Preview is a feature for quickly checking your work while writing.

Even if your changes appear in the preview, the file is not saved automatically. Make sure to save the file when you finish working.

When Live Preview Does Not Work

If Markdown Live Preview does not work, check the following.

Inline Markdown

• The page you want to check is open in the preview
• An element wraps <essepage-markdown>
• The id of the wrapping element begins with an underscore (_)
• The same id is not used more than once on the page

Article Files

• The Article File contains a article_live_preview_parent_id setting
• The setting syntax is used:

<!-- {{! article_live_preview_parent_id : docs-main-content !}} -->

• The value of article_live_preview_parent_id exactly matches the id of the layout element
• Uppercase and lowercase letters match
• The element wraps <essepage-slot>
• The layout is actually applied to the Article File
• The same id is not used more than once on the page
• The Article File is published and open in the preview

Next Steps

Now that you understand how to use Markdown Live Preview, continue with the following documents:

• Learn the three ways to use Markdown: Markdown
• Understand how Live Preview works: Editing and Preview
• Apply a shared structure and design to Article Files: Layouts
• Save your work and apply it to the published site: Saving, Publishing, and Applying