Astro JS - Markdown Contents

What is Markdown?

Markdown is a lightweight markup language with plain text formatting syntax. It is designed so that it can be converted to HTML and many other formats using a tool by the same name. Markdown is commonly used for formatting readme files, for writing messages and it is highly optimized for SEO results.

Astro includes built-in support for Markdown files that can also include frontmatter YAML (or TOML) to define custom properties such as a title, description, and tags. You can keep markdown files(.md) anywhere inside /src directory. Markdown files located within src/pages/ will automatically generate Markdown pages on your site.

Markdown Example

Astro supports markdown files as pages. The markdown files are converted to HTML and rendered as static HTML files. You can easily create markdown pages using any text editor. Here is an example of a markdown page.

---
    title: 'My Markdown page'
---
# Title

This is my page, written in **Markdown.**

Output

The output is shown below. You can see that markdown page is converted as HTML page at client side.

Astro Dynamic JSX Expressions

After importing or querying Markdown files, you can write dynamic HTML templates in your .astro components that include frontmatter data and body content. Let's See an example

Example

Consider the following markdown file. Here we have a frontmatter that includes the title and author of a post.

---
title: 'The greatest post of all time'
author: 'Ben'
---

Here is my _great_ post!

Now, we can import this file into an .astro component and use the frontmatter data in our template.

<!-- src/pages/blog.astro -->

---
import * as greatPost from './posts/great-post.md';
const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
---

<p>{greatPost.frontmatter.title}</p>
<p>Written by: {greatPost.frontmatter.author}</p>

<p>Post Archive:</p>
<ul>
    {posts.map(post => 
        <li><a href={post.url}>
            {post.frontmatter.title}
        </a></li>)}
</ul>

Output

When you run this code, you will see the title and author of the post displayed in the template. You can also use the body content of the markdown file in your template by accessing greatPost.default.

Markdown Frontmatter

Frontmatter is metadata that can be included at the top of a Markdown file. It is written in YAML or TOML format and is used to define custom properties such as a title, description, and tags. Frontmatter is commonly used to define the title of a page, the author of a post, or any other custom data that you want to include in your Markdown file.

Imports in Markdown File

Astro not only supports importing on frontmatter, but also supports a couple of properties. The following exported properties are available in your .astro component when importing Markdown using import or import.meta.glob():

• file - The absolute file path (e.g. /home/user/projects/.../file.md).
• url - The URL of the page (e.g. /en/guides/markdown-content).
• frontmatter - Contains any data specified in the file’s YAML (or TOML) frontmatter.
• <Content /> - A component that returns the full, rendered contents of the file.
• rawContent() - A function that returns the raw Markdown document as a string.
• compiledContent() - An async function that returns the Markdown document compiled to an HTML string.
• getHeadings() - An async function that returns an array of all headings (<h1> to <h6>) in the file with the type: { depth: number; slug: string; text: string }[]. Each heading’s slug corresponds to the generated ID for a given heading and can be used for anchor links.

Example

Consider the following markdown file. It is an example Markdown blog post may pass the above Astro.props objects:

Astro.props = {
    file: "/home/user/projects/.../file.md",
    url: "/en/guides/markdown-content/",
    frontmatter: {
      title: "Astro 0.18 Release",
    },
    getHeadings: () => [
      {"depth": 1, "text": "Astro 0.18 Release", "slug": "astro-018-release"},
    ],
    compiledContent: () => "<h1>Astro 0.18 Release</h1>
    \n<p>A little over a month ago, the first public beta [...]</p>",
}