Feedbacks on nextra-theme-docs

[nihgwu]

I've been watching this project for a long time, and right now I'm experimenting to migrate a Docusaurous based React UI Library to Nextra, I've made most of the parts work seamlessly as before, some feedbacks:

• [x] Make heading as normal heading and only add a to #, the problem is that we have link in heading and nesting link is invalid and will cause SSR error https://github.com/shuding/nextra/pull/897

• [x] Can we extract title from markdown (both H1 and frontmatter.title), so we don't need to config for each file in meta.json, we have hundreds of markdown files, and it would a nightmare to maintain meta.json manually https://github.com/shuding/nextra/pull/755

  Note: was made only for frontMatter.title

• [x] We also maintain blogs, however the articles are in ASC order by date, seems we have to use meta.json to change the order, can we respect the frontmatter.date and list in descending order https://github.com/shuding/nextra/pull/894

• [ ] Style isolation. My website is for Design System, so it's crucial that the style should not be affected by the external resources. a. The whole app should add isolation: isolate so the header and sidebar want overlay the modals from user space b. Try to avoid using preflight, and try to not using atomic classnames, as it will clash with user space style if they are using tailwind in their components with another config

• [x] Not Nextra related probably, it's super slow when navigating to a new page, seems my local package is not cached and rebuild every time if it's not visited, I'm using next-transpile-modules to work with local package, for comparison, it's hardly to feel the compiling for new page with Docusaurous

  Note: was moved to track here https://github.com/shuding/nextra/issues/753

Thanks for the great project 👍

UPDATE:

• [x] Update style or TOC to use the same custom scrollbar as side menu https://github.com/shuding/nextra/pull/756

• [x] We should skip navigating by tab if the submenu is hidden, right now if we tab on side menu items, it goes deep to collapsed items where I can't see the focus ring at all https://github.com/shuding/nextra/pull/805

• [x] Can we use agnostic terms, like github, we don't use Github but other hosting services https://github.com/shuding/nextra/pull/734

  Note: github was removed here, more info here https://github.com/shuding/nextra/issues/826#issue-1368578794

• [x] Theme toggle style since 2.0.0-beta.21, it worked well before. BTW can we have an option to move it to the top right conner if there is no 18n select, it's a bit confusing at first glance https://github.com/shuding/nextra/pull/763

• [x] Esc stays after pressed Esc https://github.com/shuding/nextra/pull/780

• [x] site title is hidden in small viewport https://github.com/shuding/nextra/pull/896

• [x] Empty space at the bottom of right menu

  can't reproduce

[shuding]

Thanks for writing these amazing feedback! Agree with 2) and we have an open issue for that already, while the real blocker is performance. 3) is basically the same issue as 2). 4) is partially solved with our new layout implementation where normal .js/.ts pages will have isolated styles from .mdx pages. Not sure what's happen for 5), we should investigate that and do you mind creating a separate issue so we can track it better? Thanks again!

[dimaMachina]

I think I can improve 2 and 3, will work on it when I’ll have some time

About 4 - can you add some example in nextra about atomic classnames?

[nihgwu]

@B2o5T I mean for the following classNames, can we simply use something like nextra-heading The problem is obvious, if we use TailwindCSS in our our components but with different configuration, there will be clash, Nextra should isolate it's styles from pollute user space, I think css reset is fine, but preflight is not, now my button has no style at all

[nihgwu]

So does that means you don't think the first one is a problem?

[dimaMachina]

@B2o5T I mean for the following classNames, can we simply use something like nextra-heading The problem is obvious, if we use TailwindCSS in our our components but with different configuration, there will be clash, Nextra should isolate it's styles from pollute user space, I think css reset is fine, but preflight is not, now my button has no style at all

Encapsulating all of the classes will be the hell

So does that means you don't think the first one is a problem?

I don’t think the first one is a problem, links in headings looks ugly

[nihgwu]

@B2o5T it won't be a hell if you use CSS Modules, I wanted to build a Nextra similar library, and I would use CSS Modules or similar solutions which will produce unique classNames, even if you use TailwindCSS, you can use @apply to create nextra-Block_Element--Modifier, I don't think we have too many classNames in Nextra

I don’t think the first one is a problem, links in headings looks ugly

TBH before I raised the issue I checked how the other docs websites look like, I haven't found a second one use use the whole heading as a link, as I said, link in heading is valid, and sometimes we would use link in h2 or h3..., at least I use it a lot

[dimaMachina]

@B2o5T it won't be a hell if you use CSS Modules, I wanted to build a Nextra similar library, and I would use CSS Modules or similar solutions which will produce unique classNames, even if you use TailwindCSS, you can use @apply to create nextra-Block_Element--Modifier, I don't think we have too many classNames in Nextra

I don't like the idea of refactoring all classes to use CSS modules, actually, it's because your tailwind config conflicts with nextra tailwind classes, so it's on your side to adjust it

TBH before I raised the issue I checked how the other docs websites look like, I haven't found a second one use use the whole heading as a link, as I said, link in heading is valid, and sometimes we would use link in h2 or h3..., at least I use it a lot

nextra-theme-docs is opinioned docs theme where headings are anchors and where your links in headings will not works

[nihgwu]

🤷

[shuding]

It's very tricky, "You should almost never use it (apply)" from Tailwind's author: https://twitter.com/adamwathan/status/1226511611592085504. To solve the conflict problem, I guess we can probably add prefix to Nextra's Tailwind config (https://tailwindcss.com/docs/configuration#prefix). What do you think?

[nihgwu]

Ionic finding, link in heading in Nextra's readme Opinionated doesn't mean it should go against standard

[nihgwu]

@shuding yes I also read that tweet, so if I start a project like this I won't use TailwindCSS, I think prefix could solve the problem, though it's not a problem for me, I don't use it in our DS, but at least we should disable preflight

[dimaMachina]

@nihgwu many thanks for finding issues, I just updated your post to keep track of fixing them!

[nihgwu]

@shuding @B2o5T can we make a decision of the 1) as it's currently a blocker for me, or I'll have to create my own headings

[dimaMachina]

I already explained what I think about 1 here https://github.com/shuding/nextra/issues/747#issuecomment-1229971718

@shuding what do you think?

[nihgwu]

@B2o5T I aslo replied here, don't think changing the default semantic is a good idea, it's a heading not an anchor

[dimaMachina]

@nihgwu let’s wait for @shuding through

[shuding]

@B2o5T @nihgwu I'm ok with changing that behavior, because putting links inside headings sounds like a valid use case and styling should be less important than functionality.

[dimaMachina]

👍 will change it for both themes

[dimaMachina]

3. We also maintain blogs, however the articles are in ASC order by date, seems we have to use meta.json to change the order, can we respect the frontmatter.date and list in descending order

https://github.com/shuding/nextra/pull/894

[dimaMachina]

8. Can we use agnostic terms, like github, we don't use Github but other hosting services

github was removed here https://github.com/shuding/nextra/pull/734, more info here https://github.com/shuding/nextra/issues/826#issue-1368578794

[dimaMachina]

Empty space at the bottom of the right menu

can't reproduce, even when set editLink: { component: null }, for which space do you talk exactly? For space below the border? In my side border is hidden

[dimaMachina]

site title is hidden in small viewport

https://github.com/shuding/nextra/pull/896

[dimaMachina]

Make heading as normal heading and only add a to #, the problem is that we have link in heading and nesting link is invalid and will cause SSR error

https://github.com/shuding/nextra/pull/897

[henriqemalheiros]

Hey, @B2o5T!

I'm also using Nextra as a design system documentation and having trouble with styling, specifically because of the usage of a preflight (tailwindcss/base) and global styles (like the focus ring around inputs).

This is happening because my styles are being imported before Nextra styles and, in some cases, they have the same specificity — winning whichever comer later. In the case of a button:

/* My preflight */
/* 0-0-1, 0-1-0 */
button, [type="button"] {
  background-color: transparent;
}

/* My styles */
/* 0-1-0 */
.button {
  background-color: purple;
}

/* Nextra's preflight */
/* 0-0-1, 0-1-0 */
button, [type="button"] {
  background-color: transparent;
}

My .button class wins over my preflight because it has a specificity greater than button and equal to [type="button"]. Nextra's preflight wins because its [type="button"] has the same specificity as my .button.

If it's not possible to solve the import order, I think a good solution would be to scope every global style under a class, like .nx-element, and add it to every component (header, sidebar, TOC, etc) but not to the main content.

[dimaMachina]

Closing since all problems were fixed, feel free to create new issues for new one