Make it easier to fork/customize `nextra-theme-docs`

[gkaemmer]

We've been using Nextra at Oso and it's been working well. Thanks for putting so much effort into it :).

There are increasingly many requirements that pull us farther from the off-the-shelf docs theme, but there's still a lot of functionality from the docs theme that we don't want to maintain ourselves. The main things we value about nextra-theme-docs

• The sidebar nav: parsing nextra's file tree and meta.json to build a usable tree in the sidebar
• Parsing the markdown to build a TOC on the right
• (soon) flexsearch functionality

But there are a lot of things we want to customize, like:

• Buttons in the top navbar (both on the left and the right sides)
• Which folders in the sidebar are default open/closed (as well as hiding some behind a "More" toggle)
• Sidebar styling things, specifically to more clearly differentiate sections of docs ("separators" don't really work for us)
• "Index" pages that link to all of their children

I'm sure that list will grow as time goes on. To do that stuff, right now we maintain a fork of nextra but it's a bit tedious to maintain. We only really need a fork of nextra-theme-docs, but because nextra is a monorepo we have to fork the whole thing. (you can see the diff here). I suspect most users of nextra-theme-docs will eventually need to similarly fork the theme to add little customizations here and there.

Some things that might make this easier:

• Put nextra-theme-docs in it's own repo so that it's easier to fork (that way, we'd only need to maintain a fork of the code that we're actually interested in customizing, not the whole nextra library)
• Somehow make it easier to completely override sections of the page (by providing, say, a custom Navbar component, or a custom Folder component for the sidebar). This seems like it'd be hard, but would make nextra-theme-docs more powerful without needing to fork.

Also interested in other folks' solutions to this problem!

[dimaMachina]

For the things to customization, please create separate issues with screenshots if possible, this will be easy to keep track and approve

And for about

Put nextra-theme-docs in it's own repo...

Because it’s a step back, this will be harder for us to maintain

[shuding]

Some of these require significant architectural changes and that's a long way ahead, I think that also applies to other UI or design system libraries. Because a theme has to be opinionated (there's no way for a UI library to be highly customizable), we have to either to make it headless (https://www.radix-ui.com, https://github.com/pacocoursey/cmdk ?), or make it easier to fork.

Agreed with @B2o5T that we can't make the theme a standalone repo. We can look into this in the future while adding more reasonable configurations:

Somehow make it easier to completely override sections of the page (by providing, say, a custom Navbar component, or a custom Folder component for the sidebar). This seems like it'd be hard, but would make nextra-theme-docs more powerful without needing to fork.

That said, our current focus is to fix bugs and make it stable for the 2.0 release. The built-in theme should be elegant, stable and well-tested. Then, we can look into extensibility features and refactor accordingly.

[ryan-williams]

Echoing @gkaemmer, it would be nice to decouple the very useful Next plugins here (md/mdx support, sitemap/TOC generation, etc.) from the specific theming/CSS.

npm run local-theme in Oso fork?

It seems like we're missing a way to point Nextra at an arbitrary theme repo or directory. @gkaemmer I tried to follow your README instructions, but I'm stuck at

In the Oso Cloud Docs folder, run:

npm run local-theme

Then, you should be able to make changes to packages/nextra-theme-docs and see those changes reflected in the Oso Cloud Docs.

Can you share the implementation of npm run local-theme? I'm not finding that anywhere.

My failed attempts

In my $PROJECT that uses Nextra, I've tried:

// next.config.js
const withNextra = require('nextra')({
  theme: '$NEXTRA/packages/nextra-theme-docs',  // $NEXTRA is just short-hand for this issue, I'm actually using a literal absolute path to my local nextra clone here
  themeConfig: './theme.config.js',
})

with some local changes in '$NEXTRA/packages/nextra-theme-docs', but I get errors running next build in $PROJECT:

cd $PROJECT
next build
# …
# Module not found: Can't resolve '$NEXTRA/packages/nextra-theme-docs' in '$PROJECT/pages'

That's all after versions of:

cd $NEXTRA/packages/nextra && npm run build && npm pack
cd $NEXTRA/packages/nextra-theme-docs && npm run build && npm pack
cd $PROJECT && npm i $NEXTRA/packages/nextra-theme-docs/nextra-theme-docs-2.0.0-beta.26.tgz && npm i $NEXTRA/packages/nextra/nextra-2.0.0-beta.26.tgz
next build  # ❌ try to build against a modified nextra-theme-docs, but fail

Guidance would be much appreciated, this is a really cool project, thanks!

[aazf]

@ryan-williams

I try to find way to custom theme, But can not found it.
After 3 hours, i got this, hope can help you.

https://github.com/zzci/nextra/blob/main/next.config.js#L4