One of the two ways to author posts in the Twilight blog system. This approach is ideal for simple posts that do not require managing many images or assets.

⚠️ Using the single-file workflow prevents RSS from resolving local image paths correctly. If your posts rely on RSS with local media, choose the folder-based workflow instead. (Remote image hosts are fine.)

Create a Post

1. Inside src/content/posts, create a new Markdown file with a descriptive name, for example my-first-post.md.
2. Add frontmatter—the metadata block at the top of the file. At minimum, include title and description:

---
title: Markdown Tutorial
directoryTitle: MD Tutorial  # Custom name in sidebar directory (optional)
published: 2025-01-20
updated: 2025-01-20     # Update date (optional)
pinned: true
description: A simple example of a Markdown blog post.
tags: [Markdown, Blogging]
category: Examples
licenseName: "Unlicensed"
author: emn178
sourceLink: "https://github.com/emn178/markdown"
draft: false
cover: 'https://example.com/image.jpg'
copyProtection:
    blockSelection: true
    blockClipboard: false
    blockContextMenu: true
    blockDevTools: false
---

3. Write the article content beneath the frontmatter using standard Markdown syntax.

Frontmatter Field Reference

Supported fields include:

Required

• title: Post title.
• description: Short summary used in listings and SEO.

Publishing

• published: Publication date (YYYY-MM-DD).
• updated: Update date (optional).
• draft: Set to true to hide the post in production.

Taxonomy & Positioning

• directoryTitle: Custom name displayed in the sidebar directory tree (falls back to title if not set).
• tags: Array of tags describing the topic.
• category: Broad classification for the post.
• pinned: When true, pin the article to the top of lists.

Author & Licensing

• author: Display name of the author.
• licenseName: License identifier, e.g. MIT, CC BY 4.0.
• sourceLink: Link to the original source or repository.

Cover

• cover: Post cover image URL.

Copy Protection

• copyProtection: Object that enables granular page-level copy protection. Each sub-option defaults to false:
  • blockSelection: Disable text selection (user-select: none).
  • blockClipboard: Block copy, cut, and paste events.
  • blockContextMenu: Block the right-click context menu.
  • blockDevTools: Block F12, Ctrl+U (view source), and Ctrl+S (save page).

Markdown Learning Resources

Need a refresher on Markdown? Start here:

📚 Recommended reading: Runoob Markdown Tutorial

This guide covers:

• Markdown basics
• Headings, paragraphs, line breaks
• Emphasis (bold/italic)
• Lists, links, images
• Code blocks, tables
• Advanced features

Master the fundamentals and you will be ready to craft polished articles.

Frontmatter Best Practices

Date Formats

Use ISO 8601 (YYYY-MM-DD):

published: 2025-01-20
updated: 2025-01-20

Tags & Categories

• Choose specific, relevant tags.
• Use categories for broader organization.

Example:

tags: [Vue.js, JavaScript, Frontend, Tutorial]
category: Web Development

Draft Management

• draft: true hides the post in production builds.
• draft: false publishes it normally.

License Suggestions

Common values include:

• MIT
• Apache-2.0
• CC BY 4.0
• CC BY-SA 4.0
• Unlicensed

Copy Protection

Enable the protections you need individually:

copyProtection:
    blockSelection: true
    blockClipboard: true
    blockContextMenu: true
    blockDevTools: true

All sub-options default to false.

Full Example

---
title: "Vue.js 3 Composition API Guide"
directoryTitle: "Vue 3 Comp. API Guide"
published: 2025-01-20
pinned: false
description: "Deep dive into Vue 3's Composition API, covering setup, reactivity, and lifecycle hooks."
tags: [Vue.js, JavaScript, Frontend, API]
category: "Web Development"
licenseName: "CC BY 4.0"
author: "Jane Doe"
sourceLink: "https://github.com/janedoe/vue3-guide"
draft: false
cover: 'https://example.com/vue3-cover.jpg'
copyProtection:
    blockSelection: true
    blockClipboard: false
    blockContextMenu: true
    blockDevTools: false
---

# Vue.js 3 Composition API Guide

In this article we explore Vue 3's Composition API in depth...

Previewing Posts

After saving the file, preview it in the browser. Append the filename (without .md) to your dev URL.

Example: if your dev server runs at http://localhost:4321/ and the file is my-first-post.md, open http://localhost:4321/posts/my-first-post.

If the post does not exist or the path is incorrect, you will see a 404. Console output can help diagnose missing content.

Linking to Posts

Use standard HTML anchors to link to posts:

<a href="/posts/my-first-post/">My first post</a>

Ensure the href points to the correct slug.

Adding Images

Place images inside the public directory and reference them with absolute paths:

![Cover description](/images/my-image.png)

Creating Multiple Posts

You can keep multiple Markdown files in src/content/posts/:

src/content/posts/
├── my-first-post.md
├── my-second-post.md
└── my-third-post.md

Each file corresponds to a unique post, and the filename becomes the URL path.

Linking Multiple Posts

Create an index list elsewhere on your site:

<ul>
  <li><a href="/posts/my-first-post/">My first post</a></li>
  <li><a href="/posts/my-second-post/">My second post</a></li>
  <li><a href="/posts/my-third-post/">My third post</a></li>
</ul>

Maintain accurate href values for each article.

Notes

• Filenames become URL slugs; keep them descriptive and avoid special characters.
• The date field is optional—missing values fall back to the file creation time.
• Single-file mode is suited to lightweight posts. For media-heavy articles, switch to the folder workflow to keep assets organized and RSS-friendly.