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.

site.yaml is the single configuration file for a Nue project. It sits at the project root and controls everything from server port to sitemap generation and per-page metadata. Configuration cascades from the site level down through app-level app.yaml files to individual pages, with more specific files overriding broader ones.

​
File location

my-project/
├── site.yaml          ← site-wide defaults
├── blog/
│   ├── app.yaml       ← blog-specific overrides
│   └── post.md
└── index.md
If site.yaml is absent, Nue looks for an index.md or index.html in the root to confirm it is a Nue project. If neither exists, the CLI exits with Not a Nue directory.

​
Site-only keys (SITE_CONF)

These keys are read once at startup and are not merged down to app or page level:
​
site
object
Global site settings. Currently supports one sub-key:
​
design
any
Design-system settings. Reserved for the design-system pipeline; the exact sub-keys are defined by your active design system.
​
server
object
Development-server settings.
​
collections
object
Named content collections. Each key is a collection name; the value describes where to find its source files. Collections are used to assemble blog roll pages, product catalogs, and other list-based views.
collections:
  posts:
    include: [blog/]
    sort: "date desc"
    require: [title, date]
  products:
    include: [store/products/]
    sort: "title asc"
​
production
object
Key–value pairs merged into meta only during production builds (nue build). Use this to set production-specific meta tags such as analytics IDs or CDN URLs without exposing them during development.
production:
  google_analytics: G-XXXXXXXXXX
  cdn_url: https://cdn.example.com
At build time, Object.assign(conf.meta, conf.production) is applied and the production key is deleted from the configuration.
​
port
number
default:"4000"
Default port for nue serve and nue preview. Overridden at the CLI level with --port.
port: 4000
​
sitemap
boolean | object
Controls sitemap generation. Set to true to emit a sitemap.xml with defaults, or provide an object for fine-grained control.
sitemap: true
​
links
object
Site-wide reference-link definitions used by Nuemark. Each key is a link label; the value is a URL string or { href, title } object. These links are available in every Markdown file.
links:
  docs: /docs
  github: https://github.com/nuejs/nue
  changelog: { href: /changelog, title: "See what's new" }

​
Cascading keys (ALL_CONF)

These keys exist in SITE_CONF (above) plus the additional keys below. All of them can appear in site.yaml, app.yaml, or page front-matter. App-level values override site-level values; page-level front-matter overrides app-level values.
​
include
string[]
Extra CSS or JS files to include on every page (or every page in an app). Paths are relative to the project root or to the app directory.
include: [prism.css, analytics.js]
​
exclude
string[]
Files to exclude from the build for this app or page. Useful for removing a site-level include on a specific page.
exclude: [analytics.js]
​
meta
object
HTML <meta> tag values and page-level data available in templates. Sub-keys are merged (not replaced) at each level — app meta is layered on top of site meta, and page meta on top of app meta.
meta:
  author: Ada Lovelace
  og_image: /img/og-default.png
  twitter_card: summary_large_image
In app or page YAML, additional keys are merged in:
# blog/app.yaml
meta:
  og_image: /img/og-blog.png   # overrides site default
  section: Blog                # added for this app
​
content
object
Structured content blocks injected into the page. Like meta, content objects are merged at each level. Values are available in layout templates.
content:
  hero_title: Build faster websites
  hero_cta: Get started
​
import_map
object | string
Browser import-map configuration. Defines bare module specifiers resolved in the browser.
import_map:
  imports:
    lodash: https://cdn.skypack.dev/lodash
​
svg
object
SVG sprite settings. Controls how inline SVG symbols are assembled and injected.

​
App-level overrides with app.yaml

Place an app.yaml file in any subdirectory to create an application scope. Configuration in app.yaml is merged on top of site.yaml using mergeConf: 
store/
├── app.yaml      ← store-specific configuration
├── index.md
└── products/
    └── widget.md

# store/app.yaml
meta:
  section: Store
  og_image: /img/store-og.png
include: [cart.js, product.css]
Site-only keys (site, design, server, collections, production, port, sitemap, links) defined in app.yaml are silently ignored by mergeValue. Only the cascading keys are merged.

​
Page front-matter

Individual Markdown and HTML files may include YAML front-matter that overrides app and site configuration for that page alone: 
---
title: Widget Pro — Store
description: The most powerful widget for your workflow.
meta:
  og_image: /img/widget-og.png
include: [widget-demo.js]
---

# Widget Pro

...
Front-matter is processed by mergeData, which reads only non-configuration keys as page data. Configuration keys (include, exclude, meta, content, import_map, svg) are handled separately by mergeValue.

​
The merge cascade

Configuration is assembled in three passes:
1

Site configuration — site.yaml

readSiteConf reads site.yaml from the project root. Applies the production block (if nue build), appends default skip patterns, and sets dist = .dist.
2

App configuration — app.yaml

mergeConf(site_conf, app_conf) performs a structural clone of the site config and merges each app key. The meta and content keys are object-merged; all other cascading keys are replaced.
3

Page data — front-matter

mergeData(dataset) collects data from the chain of YAML files. Keys that are in ALL_CONF are handled by mergeValue; all other keys become page-level template variables.
Merge rules summary:
Key categoryMerge strategy
meta, contentDeep merge — each level adds/overrides individual sub-keys
include, excludeReplace — app or page value replaces the parent’s value
import_map, svgReplace
Site-only keys in app.yamlIgnored silently
Non-ALL_CONF keysBecome template data variables

​
Complete site.yaml example

# Site-wide settings
port: 4000

site:
  skip: [drafts, private]

server:
  dir: @shared/server

# Navigation links for Nuemark
links:
  docs: /docs
  blog: /blog
  github: https://github.com/nuejs/nue

# Default meta tags
meta:
  author: Acme Inc.
  og_image: /img/og-default.png
  twitter_card: summary_large_image

# Content available in all layout templates
content:
  footer_copy: "© 2025 Acme Inc."
  nav_logo: /img/logo.svg

# Production-only meta (analytics, CDN, etc.)
production:
  google_analytics: G-XXXXXXXXXX
  cdn_prefix: https://cdn.acme.com

# Sitemap
sitemap: true

# Global CSS and JS included on every page
include: [main.css, app.js]

# Blog collection
collections:
  posts:
    include: [blog/]
    sort: "date desc"
    require: [title, date]

# blog/app.yaml — overrides for the blog section
meta:
  section: Blog
  og_image: /img/blog-og.png
include: [blog.css, reading-time.js]

---
title: My First Post
description: A short description for search engines.
meta:
  og_image: /img/first-post-og.png
---

# My First Post
...

Build docs developers (and LLMs) love

Get started for freeTalk to us