Advanced Markdown Guide
Markdown is a markup language that can be used with plain text to add formatting elements like bulleted lists, headings, links and images.
Propcart's CMS uses Markdown in many of our page templates.
This article discusses some advanced concepts and implementation details for using Markdown on Propcart page templates.
Before reading on, familiarize yourself with the Markdown Cheatsheet.
Why Markdown?
And why not a WYSIWYG ("what you see is what you get") editor or HTML?
- Markdown is easier to write, debug and style than HTML or WYSIWYGs.
- Most people can learn Markdown source more easily than HTML.
- Markdown was easier and safer for us to implement.
Don't like Markdown? Read About the CMS.
Where you can use Markdown
These fields take full Markdown:
- The body of the Basic, Blog Post, Forms & FAQs, Service, Project, Collection and Category Guide templates
- The body of a Markdown Section
- The Message Label of a Contact Us Section
The Description of a What We Do Section or What We Do Video Section takes only bold text and links: **bold** and [link text](/path).
Every other field shows text exactly as you type it.
HTML isn't supported
Markdown fields show HTML as typed. For example, <b>Note</b> appears on the page with its angle brackets.
- Use Markdown for formatting, like
**Note**for bold text. - Use
::: embedfor maps, videos and PDFs. - On a Sections page, use an HTML Section when you need HTML that Markdown can't write.
The one exception is <br>, which adds a line break. See Line breaks.
Line breaks
Markdown joins lines that are separated by a single line break. Leave a blank line between paragraphs.
To break a line without starting a new paragraph, end it with a backslash \:
Monday to Friday\
9am to 5pm
or two spaces:
Monday to Friday
9am to 5pm
Inside a table cell, where each row must stay on one line, use <br>:
| Seat type | Pitch |
| ----------------------------- | ------------ |
| Coach<br>(economy class rows) | 34in. / 86cm |
Embedding maps, videos and PDFs
Put the address of the map, video or PDF after ::: embed, and close the block with ::: on its own line:
::: embed https://www.google.com/maps/embed?pb=!1m18!1m12!1m3...
:::
The embed fills the width of the page at a 16:9 ratio. PDFs are taller, shaped like a page.
You can embed:
| Source | The address to use |
|---|---|
| Google Maps | In Google Maps, choose Share, then Embed a map, and copy the address between the quotes in src="...". It starts with https://www.google.com/maps/embed. Google My Maps addresses work too: https://www.google.com/maps/d/embed?mid=... |
| Vimeo | https://player.vimeo.com/video/{videoId} |
| Panoraven 360° tours | https://panoraven.com/en/embed/{tourId} |
| PDFs, and MP4 or WebM videos, uploaded to Propcart | The file's address from your page's Assets tab. It starts with https://cdn.propcart.com/, or https://cdn-au, cdn-br or cdn-eu outside North America. |
For YouTube, use ::: youtube instead. It loads faster.
Any other address shows as a link instead of an embed. Only https:// addresses embed.
If a site gives you HTML code to embed, like <iframe src="https://player.vimeo.com/video/76979871" ...></iframe>, copy only the address inside src="...".
Adding a caption
Anything between the two lines shows below the embed, formatted with Markdown. This PDF gets a download link underneath:
::: embed https://cdn.propcart.com/your-folder/public/checklist.pdf
[Download the checklist](https://cdn.propcart.com/your-folder/public/checklist.pdf)
:::
Adding a YouTube video
Our YouTube video Markdown implementation initially displays only the video thumbnail with a play button. Once that thumbnail is clicked, the YouTube iframe loads the embedded YouTube video. By loading the YouTube video only when there is a user intent to watch the video, this speeds up the page load time.
The video address must start with https://.
General Example
::: youtube https://www.youtube.com/embed/{videoId}
:::
Specific Example
Here's how we placed the YouTube video at the top of the Propcart About Us page.
::: youtube https://www.youtube.com/embed/deC0smBajYQ
{width=632 height=340}
:::
renders HTML as:
<details>
<summary>
<p>
<img
src="https://cdn.propcart.com/thumbnails/about-us1_1708024521510.jpg"
alt="Propcart Marketplace Video"
width="632"
height="340"
/>
</p>
<button>Play button</button>
</summary>
<div>
<iframe
title="YouTube video"
width="600"
height="338"
data-src="https://www.youtube.com/embed/deC0smBajYQ?rel=0&autoplay=1"
src="about:blank"
allow="accelerometer;autoplay;fullscreen;encrypted-media;gyroscope;picture-in-picture"
allowfullscreen=""
></iframe>
</div>
</details>
IDs added to H tags automatically
The HTML id attribute is used to specify a unique id for an HTML element. The value of the id attribute should be unique within the HTML document.
Our Markdown implementation automatically adds ID attributes to all H tags (<h1>, <h2>, <h3> etc.) using the text inside the H tag in strikethrough case.
Example
This Markdown:
## This H2 tag gets an ID
renders HTML as:
<h2 id="this-h2-tag-gets-an-id" tabindex="-1">This H2 tag gets an ID</h2>
IDs in <h*> tags allow you to create anchor points on a webpage, enabling direct linking to specific sections for easy navigation and reference. This is useful for creating a table of contents or allowing users to bookmark or share links that lead directly to a particular part of a page.
For the Basic page template, you can enable the Show table of contents? switch to add a sticky table of contents links on the right side of the page.
Adding Attributes like Classes
Our Markdown implementation supports adding attributes to Markdown elements by appending curly brackets {...} to the end of the element and then adding any attributes within the curly brackets using the attribute=value format.
These attributes are supported: class, id, width, height, loading, style, target and rel. Any other attribute is left out of the page.
Here are some examples:
General Example
This Markdown:
Some example text{ class=intro style="text-align: center" }
renders HTML as:
<p class="intro" style="text-align: center">Some example text</p>
There is a common shorthand for class and id attributes that use a dot . for classes and a hashtag # for ids:
Adding a Class
This Markdown:
This is text below a title{.subtitle}
This also works{class=subtitle}
renders HTML as:
<p class="subtitle">This is text below a title</p>
<p class="subtitle">This also works</p>
Adding an ID
This Markdown:
This is a unique paragraph{#one-of-a-kind}
This is also unique{id=snowflake}
renders HTML as:
<p id="one-of-a-kind">This is a unique paragraph</p>
<p id="snowflake">This is also unique</p>
Adding other attributes
Let's add some common attributes to an image.
This Markdown:
{.grid-image width=783 height=359 loading=lazy}
renders HTML as:
<img
src="https://cdn.propcart.com/help/test-image.jpg"
alt="Test image"
class="grid-image"
width="783"
height="359"
loading="lazy"
/>
Create a Grid of Images
Using the attributes feature above, we can create an image gallery grid.
This Markdown creates an unordered list of images:
- 
- 
- 
- 
{.grid}
and renders HTML as:
<ul class="grid">
<li>
<img src="https://cdn.propcart.com/help/test-image.jpg" alt="image 1" />
</li>
<li>
<img src="https://cdn.propcart.com/help/test-image.jpg" alt="image 2" />
</li>
<li>
<img src="https://cdn.propcart.com/help/test-image.jpg" alt="image 3" />
</li>
<li>
<img src="https://cdn.propcart.com/help/test-image.jpg" alt="image 4" />
</li>
</ul>
In your page's Advanced tab in the Style field, you can then define the styles for your .grid class:
ul.grid {
display: grid;
gap: 20px;
grid-template-columns: 1fr 1fr;
list-style-type: none;
padding: 0;
}
@media (max-width: 480px) {
ul.grid {
grid-template-columns: 1fr;
}
}
In this example, the grid has two columns of images on desktop screens and one column of images on mobile screens.
