Thanks! I've been thinking about this a bit, so it's helpful to get another persepective on this.

With the current state of x0, it tries to do the following:

1. Require near zero-effort to get started
2. Be fast to make some simple docs or other site
3. Have smart defaults that look better than Times New Roman
4. Be completely customizable, mostly via components

I think 1 & 2 are probably working well enough, but #3 could use some work.
The styles from Rebass come into play in two ways:

1. Default scope for MDX components
2. Built in styles for the SidebarLayout component

Right now, you can override all of the components with the ScopeProvider as you mentioned.
Most of the components (e.g. h1) won't wrap your component examples so they shouldn't really affect how they're rendered.

The LiveEditor and LivePreview components are used to render the fenced code block examples.
You can provide your own component as the code component (as is done here in the default scope), but that requires more work than I think it should.

As far as the SidebarLayout component goes, that's an optional thing and you can build your own layout component today, but I'd like to have a virtually unstyled version of that component as well.

My current thinking to make all this better to use is the following:

• Replace the Rebass components with simpler components that are part of the x0 package, similar to the components in mdx-deck, which can be completely styled via ThemeProvider.
• Remove any ThemeProviders from the core app in entry.js
• Move any default styles/themes into the current SidebarLayout
• Add a (mostly) unstyled version of the SidebarLayout as an option
• Make the LiveEditor less opinionated with styles, and easier to theme via ThemeProvider

Hope that helps with some of your questions, and would love to know if you have any thoughts on some of the potential things I mentioned above – or if you have any other specific use-cases that I might've missed

I think those steps would probably solve all the major concerns I have right now. The key for me is to have (officially blessed) access to an unstyled base that I can build on with my own CSS reset, components, etc.

Everything else is most likely solved by natural additions to the documentation, such as a more comprehensive explanation of ScopeProvider (eg what's a valid value for the scope prop? How exactly do I override the code fencing?) and details of things like route objects.

I'd consider breaking down SidebarLayout into lower-level components that people can build on if they want: for example, by using the SidebarLayout prev/next footer in their own custom layouts.

Also, perhaps formalise or recommend how to use page titles from MDX front matter, or how to define the logical structure of the guide by factors other than directory layout (logical structure !== disk layout, at least not necessarily).

Most of the components (e.g. h1) won't wrap your component examples so they shouldn't really affect how they're rendered.

I'm not sure I understand what you mean here. The style guide will include typography, so surely h1 etc would be relevant?

Thanks!

I'd consider breaking down SidebarLayout into lower-level components that people can build on if they want: for example, by using the SidebarLayout prev/next footer in their own custom layouts.

This should be fairly easy to do technically, but would require a lot more documentation to really make sense imo.

perhaps formalise or recommend how to use page titles from MDX front matter, or how to define the logical structure of the guide by factors other than directory layout

I have been thinking about a better solution for this – might be a prop on the SidebarLayout component that lets you specify route order as an array of route names.

The style guide will include typography, so surely h1 etc would be relevant?

If you have global CSS then they might affect the built-in components, but if that's the case, I'd almost recommend providing your own headings, etc in scope

This is exactly the use case I was hoping to use x0 for. I've tried out many tools but x0 seems to be the one with the least restrictions on the visuals. Allowing to opt-out of all default styles would make it the obvious choice for people looking for documenting design systems IMO. I love that we can start off with just a blank page and that things like Layout is opt-in. Removing the default styles would just be the icing on the cake for me.

@jxnblk what you described sound's perfect. Personally, I think I won't be needing less opinionated components with better theming support. Most likely I'd just replace them entirely with my own components but there might be use-cases that I don't see right now.

Anything you might use some help with? Happy to help to bring this to life 🙂

Based on some of the thinking in this issue and some other conversations, the current direction for building docs in a similar way to x0 can be found here: https://github.com/jxnblk/mdx-docs

It's still a work in progress and a little bit newer, but it should be a much more flexible way to build custom docs sites than other solutions out there and would love to hear thoughts on this approach

Instant reaction: I tried mdx with next.js a couple of weeks ago. I found that an mdx page couldn't import a component defined with flow types: the imports failed due to the type declarations in the component file. The flow preset was specified in my babelrc. I couldn't find any mistake in my config.

(I could import from the built components, which had the flowtypes stripped, but that destroyed the DX by forcing a rebuild on each change before I could see the effect.)

I'd be happy to use mdx-docs - I've built a couple of next.js sites - if it can work with flow.

I'll have a deeper look at mdx-docs tomorrow, hopefully.

I know next to nothing about build tooling for flow or ts – I assume that’s something that could be handled within the next.config.js file