Overview

Integrating markdown files into a Nuxt 3 application for article rendering is a common requirement.

Understanding the Problem

Static assets are typically placed in the public directory. However, the official documentation clarifies an important limitation:

During SSR (Server-Side Rendering), Nuxt cannot use fetch to access files in the public directory from the server context. While client-side JavaScript can access these files directly via fetch, this approach has drawbacks.

Solution: @nuxt/content Module

Nuxt provides a dedicated content module that functions as a file-based CMS. Although it doesn't offer direct file reading capabilities, it can render markdown content seamlessly and integrates beautifully with Nuxt applications. Documentation indicates full Nuxt 3 compatibility.

Many localized documentation sites often lag behind the official documentation. The English documentation is typically more up-to-date and comprehensive. Relying on the official source is generally recommended.

Installation and Setup

Follow the official installation guide at content.nuxt.com

npx nuxi module add content

Create a content directory in your project root. This serves as the base path for all content references with in the module.

Rendering Markdown

The ContentDoc component handles markdown rendering automatically:

<ContentDoc path="/articles/getting-started" />

The left side represents the actual file location, while the right side shows the path used in your code. Consult the official documentation for detailed path mapping rules.

Styling can be applied using custom CSS or a markdown styling library of your choice.

Alternative: Using Node.js fs Module

For more traditional file reading, the Node.js fs module can be used:

import { readFile } from 'node:fs/promises';

// Nuxt employs universal rendering, meaning setup code executes on both server and client.
// Since client-side environments lack access to server files and Node APIs,
// this check prevents runtime errors.
if (!import.meta.client) {
  const articlePath = 'content/articles/tech-overview.md';
  const content = await readFile(articlePath, 'utf-8');
  console.log('Article content:', content);
}

Important: When using the fs module, Nuxt has no awareness of the file paths being accessed. This means the build process will not automatically bundle these files. You must manually copy the content directory to the .output directory (the deployment root, where ecosystem.config.cjs, server, and public reside).

Recommendasion

The @nuxt/content module is the preferred approach for most use cases. It offers tighter integration with Nuxt's ecosystem, eliminates the need for manual file deployment, and provides additional features like content querying and caching. For simple requirements, the content module handles everything without the complexity of manual file management.