November 14, 2024

Nue 1.0 (RC) — Can it outshine Next.js?

Nue is a static site generator (SSG) built from the ground up to offer faster tooling, cleaner codebases, and better results. Today, we’re releasing the first version of Nue that earns the release candidate (RC) status.

This major update introduces a range of improvements while simplifying the system. The documentation has been greatly enhanced, and we've built a completely new Markdown parser from the ground up, specifically designed to bring Nue’s content-first vision to life.

But better than Next.js?!

I know, it might sound a bit over the top... but hear me out. Let’s break it down into three concrete points:

1. Design engineering

Nue is an ambitious engineering project designed to simplify web development through separation of concerns and progressive enhancement. This approach fundamentally redefines how websites are developed:

What once required a React specialist and a large amount of JavaScript can now be achieved with clean, standards-based code:

This means you’re no longer bogged down with debugging complex algorithms and data structures. Instead, you can put all that focus on content, layout, and design systems—making a natural transition from JavaScript engineering to Design engineering.

2. Tooling experience

One of Nue’s standout features is its hot-reloading mechanism, and with this version, the diff/patch system is stronger than ever. By instantly detecting changes in content, data, layouts, styles, components, and islands, Nue applies updates directly to your browser. This creates a smooth, lightning-fast feedback loop that makes the development process more exciting and fluid.

With the new Markdown parser and the absence of unnecessary JavaScript abstractions and dependencies, Nue is incredibly lean and fast, consistently outperforming monolithic web frameworks:

3. Resulting sites

Nue helps developers create fast and user-friendly websites with features like turbolinking, CSS view transitions, interactive islands, and CSS inlining:

Surprisingly, these rich, interactive sites remain exceptionally lightweight, comparable to text-only websites. To give you an idea, here’s how Nue documentation area compares to Next.js documentation:

Nue documentation

27kB of HTML/CSS/JS

Next.js documentation

645kB of HTML/CSS/JS

New Markdown parser

In earlier versions of Nue, we used the Marked library to handle basic formatting for our extended Markdown syntax — known as Nuemark. While Marked is a solid, general-purpose Markdown parser with excellent performance, it became clear that it couldn't fully support the direction we wanted for Nue, particularly with our content-first development model.

The main issue with Marked was its lack of a mutable abstract syntax tree (AST). The AST is a structured representation of the Markdown content, allowing it to be easily analyzed, manipulated, and extended before rendering to HTML. With Marked, the structure was essentially immutable—meaning it wasn't possible to add new nodes, elements, or link references before rendering the document.

Moreover, the API for creating custom extensions was overly complex, particularly for advanced features that needed to understand the document’s structure and modify parts of the syntax tree. This made implementing the more advanced components of Nue impossible.

To overcome these limitations, we built an entirely new parser from scratch. This new parser implements a mutable AST, offering greater flexibility, performance, and control over the content structure. With this foundation, we were able to add all the required features, enabling the creation of rich, interactive content and making it easier to integrate custom elements into the rendering process.

[accordion]

  ## New features
  1. New Markdown parser
  2. New formatting options
  3. New components

  ## Improvements
  1. Web component fallbacks
  2. Markdown <slot/> support
  3. Improved HMR error reporting

New parser features

The new parser introduces several powerful features to enhance your Markdown experience:

• New formatting options: You can now use custom syntaxes like |highlighted| to highlight text, •bolded• for bold text, and /italics/ for italics, in addition to the standard Markdown **strong** and _emphasized_.

• Variables and expressions: You can now use variables and expressions within your documents, such as { package.name } to display dynamic content or { foo.bar[0].name } to access specific elements from complex data structures.

• Common Markdown extensions: The parser now supports popular extensions like footnotes and tables, allowing you to create more interactive and well-structured documents without custom solutions.

• Explicit heading IDs and class names: You can now define custom IDs and class names for headings using the syntax ## Hello { #world.epic }, making it easier to add specific styles or create anchor links for better navigation.

• Automatic section splitting: Documents will now automatically split into sections by analyzing the document’s structure. When an h2 or --- is encountered, a new section is created, making it easier to organize and navigate large documents.

• Inline components: Custom tags can now be inlined directly within the content, like A inlined [custom-tag] is here. This allows you to add dynamic or reusable components within the text flow, offering more flexibility in structuring your content.

New tags

• New [accordion] tag: The tag allows you to create collapsible panels without the need for complex syntaxes or additional JavaScript. Using the AST, the parser automatically treats h2 or h3 headers as new accordion panels. This makes it easy to create interactive content sections simply by structuring your Markdown with headers.

• New [define] tag: The tag is designed for creating description lists, such as glossaries or key-value pairs. Similar to the tag, it leverages the AST to automatically structure and render the content, offering a clean and consistent way to display terms and descriptions without requiring extra HTML markup.

• Updated [tabs]: The [tabs] tags has been improved to now be based on the accordion tag and HTML <summary>/<details> elements. This means that tabs can be created with no JavaScript required, using the same simple, semantic structure, offering a native HTML solution for tabbed content.

• Generic blocks: New generic blocks like [.features] allow you to easily define content blocks with nested sections. This takes advantage of the AST to create flexible layouts using native CSS features like flexbox and grid. Essentially, this provides a content-first approach to complex layouts, making it easier to organize and structure your content visually.

• Popovers: You can now add popovers, overlays, and popover trigger buttons directly into your Markdown content using the [button popovertarget] and [#my-overlay popover] syntax. This allows for simple integration of interactive elements, such as tooltips or modal dialogs, without needing extra JavaScript or external libraries.

• [table] tag improvements: The [table] tag has received several enhancements, including the ability to render external data and a more convenient syntax to handle tables with long columns, where traditional Markdown table syntax can be unwieldy. These updates make it easier to work with data-heavy tables and present them cleanly in your content.

Performance

Marked is well-known for its performance, especially in handling basic Markdown parsing. However, Nue significantly outperforms Marked, offering around 20-50% faster processing for basic operations. As you introduce more complex features like tables, footnotes, and curly smart brackets, the performance gap becomes even more pronounced — with Nue being roughly 2-5 times faster in these scenarios.

These performance improvements stem from Nue's more efficient internal architecture, designed to handle both simple and advanced Markdown features with minimal overhead. While these results come from basic, informal tests conducted on my laptop, I encourage you to test them for yourself. It would be great to see real-world benchmarks and eventually share them on this website to provide a more accurate comparison for the community.

Other improvements and changes

Full list of improvements and breaking changes on this release: