Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nuejs/nue/llms.txt

Use this file to discover all available pages before exploring further.

Nue treats content as the primary artifact of a website. Rather than assembling pages from JavaScript components, you write Markdown — using the Nuemark format — and let layout modules and a CSS design system handle structure and presentation. This separation makes content portable, editable by non-developers, and naturally SEO-friendly, since there is no client-side JavaScript required to render any text.

​
What is a content site?

Content sites are any project where pages are driven by Markdown documents rather than programmatic UI. This includes:

Documentation

Reference guides, API docs, tutorials — hierarchical content where readers navigate by topic.

Blogs

Time-ordered posts with metadata like date, author, and tags that drive feeds and indexes.

Marketing pages

Landing pages and product pages with rich layouts, responsive images, and calls to action.

Front pages

Home pages that pull content from multiple sections of the site using content collections.

​
Nuemark: content-first Markdown

Nue uses Nuemark as its Markdown format. It is a superset of CommonMark with built-in structures for modern web content. Standard Markdown gives you paragraphs, headings, lists, and links. Nuemark adds:
  • Automatic layout structures — sections, grids, stacks, and columns through indentation-based syntax, without any <div> tags in your content
  • Built-in components — responsive images, videos, tables, and expandable elements that work out of the box
  • Front matter — YAML metadata at the top of each file that drives page titles, dates, authors, and collection filtering
  • Custom tags — developers define reusable tags once; content authors use them without any implementation knowledge
A typical blog post looks like this: 
---
title: Why semantic HTML matters
date: 2024-03-15
author: Jane Smith
tags: [html, accessibility]
description: Semantic HTML improves accessibility, SEO, and maintainability without adding any extra tooling.
---

## The problem with div soup

Modern frameworks encourage building UIs from generic `<div>` containers...

[image src="/img/dom-comparison.png" alt="Semantic vs generic DOM tree"]

## Benefits of semantic elements

Writing `<article>`, `<nav>`, and `<aside>` instead of styled divs gives browsers, screen readers, and search engines real information about your content.

​
Layout modules

Layout modules are HTML files that define the structure wrapping your content. They live in @shared/ui/ (global) or in a ui/ subdirectory within an app directory (scoped). A layout module receives your parsed Markdown content and page data as inputs, and returns a full HTML document: 
<!-- @shared/ui/layout.html -->
<html>
  <head>
    <title>{ page.title } — { site.title }</title>
  </head>
  <body>
    <header>
      <nav>
        <a :for="item in nav.links" :href="item.url">{ item.label }</a>
      </nav>
    </header>

    <main>
      <article>
        <h1>{ page.title }</h1>
        <slot />
      </article>
    </main>

    <footer>
      <p>{ site.footer_text }</p>
    </footer>
  </body>
</html>
The <slot /> element is replaced by your rendered Markdown content. Everything else in the layout is driven by data from YAML files and front matter.
Layout modules are server-rendered. There is no client-side JavaScript involved in assembling the page structure. The browser receives complete, ready-to-read HTML.

​
Directory structure for a blog

my-site/
  site.yaml
  index.md                    ← home page
  @shared/
    design/
      tokens.css              ← design tokens
      type.css                ← typography
      blog.css                ← blog-specific styles
    ui/
      layout.html             ← site-wide layout
      header.html
      footer.html
  blog/
    app.yaml                  ← blog config and collection definitions
    index.md                  ← blog index (lists posts via collection)
    2024-03-15-first-post.md
    2024-03-22-second-post.md
    2024-04-01-third-post.md
    ui/
      post-card.html          ← card component for index page
      author-bio.html

​
Content collections

Collections let you aggregate Markdown pages matching a pattern and expose them as structured data for use in layouts and index pages. You define collections in app.yaml (or site.yaml for site-wide collections): 
# blog/app.yaml
collections:
  posts:
    include: [blog/]
    sort: date desc
    require: [title, date]
    tags: [tutorial]
The collection configuration supports:
KeyDescription
includePath patterns for pages to include
sortField and direction, e.g. date desc
requireFront matter fields that must be present
tagsOnly include pages with matching tags
skipFront matter fields that cause a page to be excluded
In your layout or index page, the collection is available as a variable: 
<!-- blog/ui/post-card.html -->
<ul>
  <li :for="post in posts">
    <a :href="post.url">{ post.title }</a>
    <time>{ post.date }</time>
    <p>{ post.description }</p>
  </li>
</ul>

​
CSS design system

Content sites in Nue use a global CSS design system to handle all visual presentation. There are no inline styles, no CSS-in-JS, and no component-scoped stylesheets. Your Markdown content outputs clean semantic HTML, and your design system decides how it looks. Global CSS files live in @shared/design/ and are automatically included on every page: 
/* @shared/design/tokens.css */
:root {
  --font-body: 'Inter', system-ui, sans-serif;
  --font-heading: 'Cal Sans', var(--font-body);
  --color-text: #1a1a1a;
  --color-muted: #6b7280;
  --space-content: 65ch;
}

/* @shared/design/blog.css */
article {
  max-width: var(--space-content);
  font-family: var(--font-body);
  color: var(--color-text);
}

article h1, article h2 {
  font-family: var(--font-heading);
}

article time {
  color: var(--color-muted);
  font-size: 0.875rem;
}
Because styles are global and cascade-aware, you can retheme an entire site by changing a handful of CSS custom properties.

​
Sitemap and RSS feed generation

Nue generates sitemap.xml and feed.xml automatically during a build when you enable them in site.yaml.

​
Sitemap

# site.yaml
site:
  origin: https://myblog.com

sitemap:
  enabled: true
  skip: [draft, hidden]   # skip pages with these front matter fields
Nue walks all Markdown files in your project, skips any with matching front matter fields, and writes a standard sitemap.xml to .dist/. Each entry includes the page URL and its last-modified timestamp derived from the file’s mtime.

​
RSS feed

# site.yaml
rss:
  enabled: true
  collection: posts        # must match a collection defined under collections:
  title: My Blog Feed
  description: The latest posts from My Blog
The RSS feed is built from a content collection. It reads each matched page’s title, description, date (or pubDate), and url, then writes a standard RSS 2.0 feed.xml to .dist/.
Both sitemap and feed generation require site.origin to be set in site.yaml. Without it, Nue will warn at build time and generate relative URLs.
Add draft: true to the post’s front matter, then list draft in the sitemap.skip array in site.yaml. Nue will omit any page whose front matter contains a field listed in skip.
Yes. Collections are defined independently, and a page can match multiple include patterns across different collection definitions. Each collection resolves separately.
Create 404.md at your project root. Nue builds it to .dist/404.html. Most hosting platforms serve this file automatically for unmatched routes.

Build docs developers (and LLMs) love

Get started for freeTalk to us