Authoring Content • Yutong's Site

Docs content

Astro helps you author and present your content ↗. You can write a blog post directly in Astro using Markdown/MDX, or fetch your content from a headless CMS. Astro lets you build a site around your content: you can add a layout to your pages, create an index of posts, and set up an RSS feed to allow readers to subscribe.

Writing Content#

In Astro, you can author your content in a variety of ways:

In Markdown files (.md or alternative extensions ↗), designed to make it easy to write rich text content.
In MDX (.mdx) or Markdoc (.mdoc) files with an official integration ↗, which can include components and dynamic expressions in your document.
Using a third-party content management system (CMS) ↗, then pulling that content into a .astro page.
Other options (less commonly used for content-heavy pages) include .astro files ↗ and .html files ↗.

For this theme, .md and .mdx is suopported by default.

Markdown Authoring#

Markdown is a convenient syntax for writing rich text with basic formatting and common elements like headers, lists, and images. Astro has built-in support for Markdown files in your project.

Create and write a new .md file in your code editor or bring in an existing file written in your favorite Markdown editor. Some online Markdown editors like StackEdit ↗ and Dillinger ↗ will even allow you to edit and sync your work with your Astro repository stored on GitHub.

Let’s give you example of writing Markdown content in Astro ↗:

src/content/post/first-article.md

---
title: First Article (Required, max 60)
description: I like writing articles. (Required, 10 to 160)
publishDate: 2024-11-30 00:08:00 (Required, Date)
tags:
  - Markdown (Also can write format like next line)
heroImage: { src: './thumbnail.jpg', alt: 'an image targetting my article', color: '#B4C6DA' }
# thumbnail.jpg should be in the same folder as the article
draft: false (set true will only show in development)
language: 'English' (String as you like)
---

## This is a title

This is a paragraph.

markdown

If you have a lot of assets, you can create a folder for title like src/content/post/first-article/ and put all your assets in there. Of course, your content should be renamed to index.md or index.mdx and also be contained in this folder.

Too complex? Simple example just need these:

src/content/post/simple-article.md

---
title: Simple Article
description: Just another simple article.
publishDate: 2024-07-26
---

I like writing simple articles.

markdown

MDX Authoring#

This allows you to include UI elements such as a banner or an interactive carousel along with your text content.

Write and edit .mdx files directly in your code editor, alongside your project files. MDX files are a supported page file type ↗ in Astro, and may also be used as content collection entries ↗.

For integrated components, checkout User Components and Advanced Components.

Connect a CMS#

See Astro: Use a CMS with Astro ↗

Pages#

Astro uses file-based routing to generate your build URLs ↗ based on the file layout of your project src/pages/ directory.

Routes#

.astro page components ↗ as well as Markdown and MDX Files (.md, .mdx) within the src/pages/ directory automatically become pages on your website. Each page’s route corresponds to its path and filename within the src/pages/ directory.

# Example: Static routes
src/pages/index.astro        -> mysite.com/
src/pages/about.astro        -> mysite.com/about
src/pages/about/index.astro  -> mysite.com/about
src/pages/about/me.astro     -> mysite.com/about/me
src/pages/posts/1.md         -> mysite.com/posts/1

diff

Astro Pages#

Astro pages use the .astro file extension and support the same features as Astro components ↗.

src/pages/index.astro

---
---
<html lang="en">
  <head>
    <title>My Homepage</title>
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>

astro

A page must produce a full HTML document. If not explicitly included, Astro will add the necessary <!DOCTYPE html> declaration and <head> content to any .astro component located within src/pages/ by default. You can opt-out of this behavior on a per-component basis by marking it as a partial page.

To avoid repeating the same HTML elements on every page, you can move common <head> and <body> elements into your own layout components. You can use as many or as few layout components as you’d like.

And in this theme, luckly you can use BaseLayout.astro as your layout component.

src/pages/mypage.astro

---
import PageLayout from '@/layouts/BaseLayout.astro'

const meta = {
  title: 'My Page',
  description: 'My fav page',
}
const highlightColor = '#44AEF6' // Optional
---
<PageLayout {meta} {highlightColor}> 
  <p>My page content, wrapped in a layout!</p>
</MySiteLayout>

astro

Markdown/MDX Pages#

While .astro pages have some flexsible features and be friendly to inline / module scripts, .md and .mdx pages are more suitable for content-focused pages.

Astro also treats any Markdown (.md) files inside of src/pages/ as pages in your final website. If you have the MDX Integration installed ↗, it also treats MDX (.mdx) files the same way.

Markdown files can use the special layout frontmatter property to specify a layout component ↗ that will wrap their Markdown content in a full <html>...</html> page document.

This theme supports a good layout for .md and .mdx files:

src/pages/terms/privacy.md

---
layout: '@/layouts/IndividualPage.astro'

title: 'Privacy Policy'
description: 'Effective date: 2024-11-26'
language: 'En' # optional
back: '/terms/list' # optional, default to '/'
heroImage: { src: './thumbnail.jpg' } # will used to social-image
---

## Privacy Policy 1

This is the first section of the privacy policy.

markdown

HTML Pages#

Files with the .html file extension can be placed in the src/pages/ directory and used directly as pages on your site. Note that some key Astro features are not supported in HTML Components ↗.

See more docs