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 uses a file-based model where your directory layout directly drives what gets built and how. Instead of configuring entry points and asset graphs by hand, you place files in the right locations and Nue infers the rest. A project can be as minimal as a single index.html or index.md file, and scale to a multi-app site with shared layouts, global CSS, and content collections — all without changing how you configure the build.

​
Entry points

Nue recognizes two valid entry points for a project:
  • site.yaml — Presence of this file at the project root identifies the directory as a Nue site and provides global configuration. Nue reads this file first when starting the dev server or build.
  • index.html or index.md — When no site.yaml exists, Nue looks for one of these files at the root. If neither is found, the directory is not treated as a Nue project.
# site.yaml — global site configuration
site:
  origin: https://example.com
  title: My Site

server:
  port: 8080

sitemap:
  enabled: true

rss:
  enabled: true
  collection: posts

​
Directory conventions

@shared/

Global assets used across all pages and apps. Nue automatically includes files from @shared/design/, @shared/ui/, and @shared/data/ in every page.

App directories

Any subdirectory containing an index.html or Markdown files is treated as a self-contained app. Assets in that directory are scoped to its pages.

.dist/

The output directory for all builds. Generated automatically at the project root. Never commit this directory to version control.

Root-level files

CSS, JS, and HTML files placed directly at the project root are treated as global assets and are included in every page.

​
The @shared/ directory

The @shared/ directory has several well-known subdirectories, each with a specific role: 
@shared/
  design/       ← global CSS, design tokens, typography
  ui/           ← layout components and HTML modules (auto-included)
  data/         ← YAML/JSON data files and JS data transformers
  server/       ← server-side only code (excluded from client builds)
  test/         ← test utilities (excluded from builds)
  lib/          ← utility libraries (not auto-included)
  app/          ← shared app code (not auto-included)
@shared/design/, @shared/ui/, and @shared/data/ are auto-included in every page. The server/ and test/ subdirectories are excluded from all builds.

​
Example directory tree

A typical content site with a blog looks like this: 
my-site/
  site.yaml               ← global config
  index.md                ← home page
  @shared/
    design/
      tokens.css          ← CSS custom properties
      typography.css
    ui/
      layout.html         ← site layout component
      header.html
      footer.html
    data/
      nav.yaml            ← navigation data
  blog/
    index.md              ← blog index page
    app.yaml              ← blog-level config
    first-post.md
    second-post.md
  docs/
    index.md
    getting-started.md
  .dist/                  ← build output (generated)
A single-page app lives in its own directory and uses index.html as the entry point: 
my-app/
  site.yaml
  @shared/
    design/
      app.css
  dashboard/
    index.html            ← SPA entry point
    main.js               ← business logic
    ui/
      sidebar.html        ← UI components
      chart.html

​
File discovery with fswalk

When Nue starts, it walks the entire project tree using fswalk, then hands the list of paths to sortAssets before creating asset objects from each file. The sort order determines which files are processed first and how style/component precedence is resolved. Asset priority is assigned as follows:
PriorityRuleExample
0 (highest)Files in @shared/@shared/design/tokens.css
1Files in subdirectoriesblog/post.md
2 (lowest)Root-level filesindex.md, global.css
Within the same priority tier, files are sorted alphabetically. This ensures shared design tokens and layout components are always processed before page-level assets.

​
The skip list

Nue ignores certain files during the walk. The default skip list is: 
node_modules   .toml   .rs   .lock   package.json
.lockb         README.md     Makefile
You can extend the skip list in site.yaml: 
site:
  skip:
    - drafts/
    - _private.md
Files that match the skip list are invisible to Nue’s dependency resolver. They will not be built, served, or included in any page — even if they are referenced from other files.

​
App-level configuration

Each app directory can contain an app.yaml file to override site-level settings for pages in that directory. Configuration is merged, with app-level values taking precedence over site-level values for include, exclude, meta, and content keys. 
# blog/app.yaml
collections:
  posts:
    include: [blog/]
    sort: date desc
    require: [title, date]

meta:
  author: Jane Smith

​
How dependencies are resolved

When Nue renders a page, it calls listDependencies from deps.js to compute the full set of assets needed for that page. The rules are:
1

Root-level files are global

Any .html, .js, .ts, .yaml, or .css file placed directly at the project root is included in every page.
2

@shared/ subdirectories are auto-included

Files under @shared/design/, @shared/ui/, and @shared/data/ are always included. Files under @shared/lib/, @shared/app/, and @shared/server/ are not.
3

SPAs use their entire directory tree

For index.html SPA entry points, all assets in the same directory and its subdirectories are included.
4

Content pages use hierarchical ui/ directories

Markdown pages include assets from ui/ directories in each parent directory, all the way up to the root.

​
The .dist/ output directory

All build output goes to .dist/ at the project root. The output mirrors the source directory structure, with these transformations applied:
  • .md files are compiled to .html
  • .ts files are compiled to .js
  • .html files containing dynamic components (is_dhtml: true) are compiled to .html.js
  • CSS is minified in production builds
  • sitemap.xml and feed.xml are generated when enabled in site.yaml
.dist/
  index.html          ← from index.md
  blog/
    index.html        ← from blog/index.md
    first-post.html
  @nue/               ← Nue runtime files
  sitemap.xml         ← when sitemap.enabled: true
  feed.xml            ← when rss.enabled: true
Run nue build --dryrun to see which files Nue would build without writing any output. This is useful for debugging your project structure.

Build docs developers (and LLMs) love

Get started for freeTalk to us