Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shuding/nextra/llms.txt

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

Nextra enhances both images and links beyond standard Markdown defaults. Images are automatically optimized through Next.js’s built-in <Image> component, giving you lazy loading and blur-up placeholders for free. Links to other pages in your site are silently upgraded to Next.js <Link> elements that prefetch the destination and navigate without a full page reload.

​
Images

​
Standard Markdown Syntax

The most common way to include images is the standard Markdown syntax: 
![Alt text](/demo.png)
By default Nextra’s staticImage: true config option automatically wraps this with next/image, so you don’t need to specify width and height — they are inferred from the file at build time.

​
Static Assets in public/

Place images in your project’s public/ directory and reference them with an absolute path: 
![Nextra logo](/logo.png)
You can also reference images by relative path from your content file if you prefer to co-locate assets: 
![Screenshot](../public/screenshots/dashboard.png)
Relative path imports are resolved at build time and benefit from the same automatic Next.js Image optimization as public/ assets.

​
Next.js Image Optimization

When staticImage is enabled (the default), every ![]() image in your MDX is rendered via next/image, which provides:
  • Automatic resizing — the image is served at the exact dimensions needed.
  • Modern formats — Next.js serves WebP or AVIF where the browser supports it.
  • No layout shift — width/height are known at build time, so the page doesn’t jump.
  • Blur placeholder — a low-quality blurry preview is shown while the image loads.
To use Next.js Image with explicit dimensions or additional props, import the component directly: 
import Image from 'next/image'

<Image src="/demo.png" alt="Hello" width={500} height={500} />

​
Image Zoom

By default, Nextra wraps images with a zoom handler so users can click to expand them. To disable zoom for a specific image, use the <Image> component from nextra/components instead of the Markdown syntax: 
import { Image } from 'nextra/components'

<Image src="/demo.png" alt="No zoom" />
To enable zoom on a single image when it’s disabled globally, use <ImageZoom>: 
import { ImageZoom } from 'nextra/components'

<ImageZoom src="/demo.png" alt="Zoom enabled" />
To disable zoom globally in nextra-theme-docs or nextra-blog-theme, replace the default img component in your mdx-components.js file: 
import { useMDXComponents as getDocsMDXComponents } from 'nextra-theme-docs'
import { Image } from 'nextra/components'

const docsComponents = getDocsMDXComponents()

export const useMDXComponents = components => ({
  ...docsComponents,
  img: props => <Image {...props} />,
  ...components
})
Use standard Markdown link syntax to link between pages in your site: 
Click [here](/about) to read more.
[Getting Started](/docs/getting-started)
Nextra automatically converts every relative link into a next/link element: 
import Link from 'next/link'

Click <Link href="/about">here</Link> to read more.
This means the destination page is prefetched when the link enters the viewport, and clicking navigates client-side — no full page reload, just a fast SPA-style transition. Links to external URLs (starting with http:// or https://) are rendered with target="_blank" and rel="noopener noreferrer" automatically, so they open in a new browser tab without leaking your page’s referrer. 
[Nextra on GitHub](https://github.com/shuding/nextra)
When building an internationalized site, Nextra uses an internal remark-link-rewrite plugin to prefix relative links with the current locale. The unstable_shouldAddLocaleToLinks option in your Nextra config controls whether locale prefixes are added to links in the page map: 
import nextra from 'nextra'

const withNextra = nextra({
  unstable_shouldAddLocaleToLinks: true
})

export default withNextra({
  i18n: {
    locales: ['en', 'zh'],
    defaultLocale: 'en'
  }
})
unstable_shouldAddLocaleToLinks is useful when you don’t want to use Nextra’s built-in middleware function for automatic locale detection and redirect.

Build docs developers (and LLMs) love

Get started for freeTalk to us