[Doc Next] Todos for the VitePress Next integration

[kiaking]

Based on discussion we had here, this is the thread to list all todos for the VitePress Next integration, and discuss on each topics.

Since there are lot more to do, until we get to the stage where things are more stable, we can manage issues here.

VitePress todos

There are more issues on VitePress side but here I'll list anything that directly affect Vite website.

• Add Home Page feature
• Style custom markups (Tips, warning and such)
• Inline code don't get proper line break (for example at /config/#build-options)
• Style 404 page
• Add "mini" sponsors component
  • To add sponsors on docs page.
• Add Carbon Ads feature
• Change header or update code block bg and fg colors on light mode
  • ref [Doc Next] Todos for the VitePress Next integration #8262 (comment)
  • Conclusion: Not going to do this since it's a bit hard to do this with new syntax highlight plugin Shiki.
• The header backdrop-filter doesn't apply in Safari
  • ref [Doc Next] Todos for the VitePress Next integration #8262 (comment)
• Pages contains process.env.NODE_ENV !== 'production' report 404 error
  • Not that easy to fix. Discussion going on involving Vite team as well.
  • See: pages contains process.env.NODE_ENV !== 'production' report 404 error vuejs/vitepress#419
  • Currently we're working around this issue. Not 100% fixed, but it's enough to be released.

Vite Docs todos

• Decide what to do with the pages don't have sidebar (Config, Plugins). More on this later.
  • PR: docs: split config pages and more #8270
• Style custom audio icon at /guide/ (Vite pronounce)
• Adjust overall brand colors
  • Feels too dark in dark theme. Might want to brighten up a bit.
• Add sponsors to docs page
• Add index page for config (base on this idea)

Config page sidebar issue

Due to VitePress next showing in page outline at page right, currently it doesn't have sidebar: 'auto' feature anymore, where previously it was generating sidebar based on in page outline.

Currently, the issue is that outline only shows h2 headings, and it would be nicer if we can list h3 items as well so users can see all config options. Now actually, VitePress already can do that by adding deep option to the outline.

However, Vite's config page is quite big, and because page "with sidebar" looks kinda nicer on design perspective, I would like to suggest splitting up the config page into multiple pages. In this case, we split the page by current h2 section.

I'm planning to test this and open PR to see how it goes 🤔

At the end, maybe we might still want to have sidebar: 'auto' feature in VitePress, but combining with the new outline feature, it might be a little confusing in configuration point of view 👀

[userquin]

I will be adding problems that I find, I'll check it also on vite plugin pwa docs:

• change header or update code block bg and fg colors on light mode (inverting colors for example): https://imgur.com/NtDzedP

[kiaking]

Thanks! Hah, good point 👀 I was thinking to keep the code block background to be balck in both light and dark theme, but maybe we should make it light in light mode 😅

Though this happens only when user scrolls pages, and not sure how much it's going to bother them. Because the reason why keeping dark bg on light mode is because we did some survey while ago when we re-designed Vue.js website, and seems like everybody liked dark bg even on light mode.

However, Vue.js website doesn't have this "blur header", so things are bit different. Let's see how it goes 👀

[kiaking]

OK I think I would like to drop this, because the new syntax highlight plugin Shiki, injects styles directly to the tags and not possible to override it via css 👀

[bluwy]

I found a small issue (not sure if this is the place to report). The header backdrop-filter doesn't apply in Safari, it'd need the -webkit- prefix. I assume we won't be using autoprefixer here since it's bulky (?).

[kiaking]

Thanks! I thought we had autoprefixer but seems like not 👀 Well yeah since VitePress only targets modern browsers, I think autoprefixer is overkill here. Let's just add prefix manually 👍

[kiaking]

This has been fixed in latest next-theme branch on VitePress 🚀