shuding / nextra

Simple, powerful and flexible site generation framework with everything you love from Next.js.

Nextra

Simple, powerful and flexible site generation framework with everything you love from Next.js.

Documentation

https://nextra.site

Development

Installation

The Nextra repository uses PNPM Workspaces and Turborepo. To install dependencies, run pnpm install in the project root directory.

Build Nextra Core

cd packages/nextra
pnpm build

Watch mode: pnpm dev

Build Nextra Theme

cd packages/nextra-theme-docs
pnpm build

Command	Description
pnpm dev	Watch mode
pnpm dev:layout	Watch mode (layout only)
pnpm dev:tailwind	Watch mode (style only)

Development

You can also debug them together with a website locally. For instance, to start examples/docs locally, run

cd examples/docs
pnpm dev

Any change to example/docs will be re-rendered instantly.

If you update the core or theme packages, a rebuild is required. Or you can use the watch mode for both nextra and the theme in separated terminals.

nextra's Issues

Better ways of sorting & naming pages

Hey, I'm enjoying nextra a lot, here's a couple of nitpicks and things I'd like to suggest about sorting & naming.

Right now, order of entries meta.json is what sets the order & title of the page. This means that I could name my pages like:

01-intro.mdx
02-getting-started.md
03-end.md

This also sorts them correctly in the editor and filesystems

They'd already be sorted alphabetically in the menu, but I'd still have to manually create a meta.json with the renames.

My proposal is, while leaving everything as is, adding the ability to rename via frontmatter, I noticed that I can use

---
title: Intro
---

to change the <title /> of the page, it would be convenient if this, or another key, were used to also set the name in the nav.

Thanks anyway for your time and kudos on the project!

Make sure the sidebar layout is stable when navigating

Noticed the bug on https://docs.react2025.com, the sidebar scroll position isn't stable.

Hide the sidebar

Make the sidebar toggleable in desktop screen size.

Getting an error when starting the local website

When running yarn dev in examples/doc I'm seeing

ReferenceError: Slugger is not defined

How should I fix this?

Thanks!

Search input is wrongly styled in dark mode

Customization via custom components

I think that it's a common requirement to heavily customize the appearance of documentation.
Now I should create a local copy of nextra-theme-docs and customize the style with all the @apply Tailwind directives.
In this way I loose the ability to keep my project updated with nextra-theme-docs new features and the style can become quite messy.

Wouldn't it be better to have nextra-theme-docs more "headless", just creating the structure and accepting as config components for H1, H2, SidebarLink etc?
Since I already have Tailwind in my project, I could create these components already styled and dark-mode ready and pass them to the headless nextra-theme-docs.

What do you think about it?

Loader should reuse the page map in production build

It’s fine to watch all, access fs and trigger updates in dev environment. But for production build (NODE_ENV=production) we should reuse the page map.

This ensures prod build is O(n) instead of O(n^2).

Ability to configure theme for react-prism-renderer

The theme for react-prism-renderer is hardcoded in the nextra-theme-docs/src/misc/theme.js file.
It would be great to be able to pass a theme object (for example NightOwl).

Sorry for all the issues opened: we are starting using Nextra for the upcoming ReactBricks v2 docs ;)

Thank you,
Matteo

Cool project

I opened this issue just to let you know I am developing a similar solution called dokz, it would be cool to join the efforts if you want

It also has a playground to preview react components

I would love to have your opinion on the project

Thank you for your awesome work at @vercel

Monorepo

examples
  docs
  blog
packages
  nextra
  nextra-theme-docs
  nextra-theme-blog

Locale from jsx/tsx files

It seems to me from reading the file loader.js inside nextra that jsx files, such as no.en.jsx, are allowed. But even though No appears on the navigation sidebar, clicking it leads to 404 (since the route is no). If however only no.jsx is created Nextjs takes over and it renders correctly.

I don't know what the real intention here is. It seems to me if a file ends with jsx or tsx then the locale problem is perhaps treated directly by some logic inside the file itself (instead of having different files with essentially the same logic, layout etc.)? In that case would it be better to remove jsx as currently done inside loader.js?

On the other hand, if something such as no.en.jsx is indeed what's wanted then some fix should be done, and tsx should be allowed also. I've played a bit with the code and here's
the branch:

https://github.com/gr-qft/nextra/tree/fix/jsx-tsx-files

Please let me know.

custom mdx components arn't rendering properly for nextra-theme-blog

title.

Even though theres custom mdx theme in mdx-theme.js, it doesn't seem to pick it up properly. Cloning @shuding 's site and you'll see that anchor tags don't work for all h{@number} tags.

Anyone know why?

<code> should be inline instead of inline-block

It doesn’t wrap if the content is too long.

In-site search

Gatsby supports it using plugins https://www.gatsbyjs.com/docs/adding-search/

I am not sure what's the right path to approach this feature (plugin, some reasonable default impl, or just not impl this at all), but feel it is useful.

Thank you.

nextLink always redirects to the same page (index.md)

The nextLink below each page always redirects to the same page (index.md). It should redirect to the next page outlined on the meta.json file.

Page exclusion from docs

Hi Shu,
I'd like to have the docs root in /pages/docs, but have a content site in the /pages root folder.
So I'd like to have a way to exclude pages from the docs navigation or set the documentation root folder.

What do you think?
Matteo

How to render table of contents

Example: see https://using-remark.gatsbyjs.org/hello-world-kitchen-sink/

Thank you!

Versioned docs

Kind of like next.js docs load the route manifest file from github version tags, would be rad to use same technique somehow.

Error when compiling

I started receiving this error on a Nextra project: I tried deleting almost any file and the error is still there (either with Node 12.x or 14.x).
I tried also removing the .next folder, the node_modules folder and the yarn.lock file and reinstalling modules, but I still get the error.

The repo is here:
https://github.com/ReactBricks/react-bricks-docs

Thank you,
Cecilia

(node:11513) UnhandledPromiseRejectionWarning: TypeError: Cannot read property '1' of null
    at removeExtension (/Users/cecilia/Documents/Development/react-bricks-docs-v2-nextra/node_modules/nextra/dist/loader.js:70:32)
    at /Users/cecilia/Documents/Development/react-bricks-docs-v2-nextra/node_modules/nextra/dist/loader.js:90:42
    at Array.map (<anonymous>)
    at getFiles (/Users/cecilia/Documents/Development/react-bricks-docs-v2-nextra/node_modules/nextra/dist/loader.js:88:44)
    at async getPageMap (/Users/cecilia/Documents/Development/react-bricks-docs-v2-nextra/node_modules/nextra/dist/loader.js:143:11)
    at async Object.loader (/Users/cecilia/Documents/Development/react-bricks-docs-v2-nextra/node_modules/nextra/dist/loader.js:177:26)
(node:11513) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 2)
(node:11513) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

Make anchor links smaller in the sidebar

This looks better:

Customizable nextra-theme-blog

I wonder if there'll be support for customizable style.

For example, to allow configuration of readMore and footer in https://github.com/shuding/nextra/blob/core/packages/nextra-theme-blog/src/index.js, and the css in https://github.com/shuding/nextra/blob/core/packages/nextra-theme-blog/src/style.css

Thank you.

Use @tailwind/typography

Let's use https://tailwindcss.com/docs/typography-plugin for article styling.

Edit in Github link is a little dumb

It's generated with

const filepath = route.slice(0, route.lastIndexOf('/') + 1)
const filepathWithName = filepath + filename

(config.siteGithub || config.github) + '/tree/master/pages' + filepathWithName

Which means there are 2 issues, don't respect the main-branch from github and doesn't respect the possibility to have the docs from another folder.

It would be a good idea to add a field inside config to represent that or have a way to know where's the git folder.

Let me know what fits best and I can try to have some time to fix it!

Thanks

Add utterances support to nextra-theme-blog

https://utteranc.es/ is a popular comments "plugin" that manages comment data in GitHub repo. Would be great to have it built-in to nextra-theme-blog, or allow users to easily add it

Docs on how to customize/create your own themes

https://twitter.com/benoror/status/1336354020357705734

prevLink does not render at all

The prevLink below the page does not get rendered at all despite being set to true on the theme.config.js file. Moreover, an empty div is rendered on the compiled HTML.

Overall design improvement

It’s currently using Tailwind’s default styles + Inter, and it feels not that great/special. Here’re some ideas:

• use a theme color as the identity
• adjust rounded corners to be sharper
• experiment with another typeface which is more noticeable and suitable for a lot of content
• great typesetting
• motion

Compiling error on latest 0.3.1 & React 17

SyntaxError: /Users/benoror/code/baseql-docs/pages/index.md: pragma and pragmaFrag cannot be set when runtime is automatic

Dependencies versions:

  {
    "next": "^10.0.3",
    "nextra": "^0.3.1",
    "nextra-theme-docs": "^0.3.1",
    "react": "^17.0.1",
    "react-dom": "^17.0.1"
  }

No syntax hilight for code block

I cloned this repo, run yarn add . and then yarn dev, code blocks in localhost website does not have highlights.

Path resolving error in Windows

vercel/swr-site#44

Highlight anchor links on scroll

markdown inline codeblock not rendered as expected

Hi @shuding I use your site https://github.com/shuding/site as a starting point to adopt next-theme-blog, and run into below problem.

.md file:

你只需要配置 RemoteActorRefProvider(译者注：在最新版本的 Akka 中，只需设为`cluster`即可)。

rendered as:

Note the cluster is not rendered as a normal markdown inline codeblock. Do you know why?

nextra-theme-blog nested support

Would it make sense to allow similar structure as in nextra-theme-docs?

Rather than

• posts (multiple articles)
  • index.md
  • blog1.md
• readings.md (single page)
• about.md (single page)

Maybe

posts

• blogs (multiple articles)
  • index.md
  • blog1.md
• readings (multiple articles)
  • index.md
  • review1.md
• about (single page)
  • index.md

to allow nested structure? Because in the readings part I am also interested in having several articles, rather than a single page.

Thank you!

I18n routes

Deletion of `.mdx` files under folders doesn't trigger webpack compilation

To reproduce add some pages in the root pages folder and nest some pages under a folder. Deleting root pages results in Webpack recompilation and nav tree updated, but if you delete a page under folder there is no update.
Seems like the fix is to add addContextDependency not only for pages but every child directory within it as well (ideally using a glob like pages/**).

Link to rss

Example: https://overreacted.io/rss.xml

Not able to find one in https://shud.in/. Do you think it'd a great feature to have built-in the framework? Thanks.

MDX Pages under folders do not render properly.

I'm selecting only the second page.

Don't require _app.tsx and global stylesheet

Maybe we can remove step 4:

by just scope everything and use CSS Modules, including Tailwind (but under a :global scope ?)

Chinese title anchor support ?

Actually, this is slugify not support chinese.

Hi shu.
Is there any good choice that can elegant support chinese anchor?

---

Can add a check before use slugify to generate a slug?

• If this is a chinese title, just use it as raw. otherwise use slugify. Also use a random hexstring instead of it.

Hope you can reply. ^_^

markdown codeblock not colored correctly for scala lang

Hi @shuding I use your site https://github.com/shuding/site as a starting point to adopt next-theme-blog, and run into below problem.

.md file.

It is rendered as:

Note that this is no color highlighting. Though it works for my javascript codeblock 🤔

Any help? Thanks!

Allow functions inside theme config

Essentially for transforming

  footerText: 'MIT 2020 © Shu Ding.',

into

  footerText: () => `MIT ${new Date().getFullYear()} © Shu Ding.'`,

What do you think? 🙂

Formatting like links in headings breaks page title

Having a Markdown link in the h1 causes [object Object] in the page title. Would expect it to remove formatting & use plaintext/the text content for the title.

mdx syntax highlight: more language support

I try to highlight my Scala code block with nextra-theme-blog and it doesn't work.

According to mdx-js/mdx#1411, this is because prism-react-renderer doesn't support Scala by default. However, there seems to be a way to add support, as in https://github.com/FormidableLabs/prism-react-renderer#faq

Can you help add the support if it makes sense to you? Thank you

SkipNavContent is not working

It seems SkipNavContent is not working: on pressing tab right after loading a page or right after clicking on the navigation menu (to get focus there), SkipNavContent does not show up. I think it's expected to be used with SkipNavLink.

How to render filesystem images in markdown

In Gatsby, people can put images under a folder and reference the image in markdown.

Demo: https://overreacted.io/preparing-for-tech-talk-part-2-what-why-and-how/
Code: https://github.com/gaearon/overreacted.io/tree/master/src/pages/preparing-for-tech-talk-part-2-what-why-and-how

Is there a way to do so with nextra?

Source code for https://site-icp9uk8zq.vercel.app

Are they available somewhere in the repo? I search by the content such as 博尔赫斯 (https://site-icp9uk8zq.vercel.app/posts/labyrinth-of-borges) but I was not able to find it.

Some guidance on how to use nextra to build a blog, or the source code of the example blog will be very helpful.

Console warning when running local website

I'm seeing the following warning:

This doesn't seem to affect anything but it'd be great to understand and be able to remove it.

Multiple sidebars

It would be great to be able to extend Nextra to support multiple sidebars.

I think it's possible to do this a few ways. One would be to specify root json files in a theme config.

// theme.config.js
export default {
  ...
  sidebars: {
   reference: "reference.json"
   docs: "docs.json"
  }
}

Another way would be to use a filename prefix for the route's metadata files. If found, and if matching the prefix, it would then look for matches during the traversal.

- index.md
- meta.json  
- docs-meta.json
-- docs/
--- docs-meta.json
--- index.md
--- guides/
----- docs-meta.json
----- index.md

Tables do not render correctly

[I18n] `direction: rtl` in RTL languages

Is it possible to get the main paragraphs on the page with the correct applied direction when in RTL.

https://developer.mozilla.org/en-US/docs/Web/CSS/direction