feat: v5 style overhaul

[jhildenbiddle]

Summary

This PR contains a UI refresh and complete rewrite of the CSS used to style Docsify sites. Additional changes have been made to support that effort.

Note: These changes have been tested extensively by both myself and @paulhibbitts on multiple Docsify projects.

Goals

1. Modernize Docsify's user interface, CSS source, CSS dependencies, and CSS build processes
   The previous Docsify design (v4) was created in 2017 and has remained mostly unchanged since then. The CSS was authored to support legacy browsers like IE10/11 in a format that requires tools which have long since fallen out of favor (Stylus).

   This update includes visual design changes, UX-related enhancements, and best practices that better align with modern expectations. The basic layout remains the the same but default styles have been updated, bugs have been fixed, new features have been added, and accessibility has been improved. The new CSS has been authored using modern CSS syntax (custom properties, nested selectors, :has, :is, :where, etc.) and build tools (PostCSS) that balance forward-looking CSS authoring with real-world browser compatibility.

2. Simplify and expedite style/theme customization and maintenance
   Docsify v4 offered multiple themes, but only one theme ("Vue") was widely used and consistently updated by the Docsify team. Official Docsify v4 themes offered only one configurable "theme"-related option (theme color). A few third-party themes have been created by the community, but these are typically just copies of outdated versions of the "Vue" theme with a few minor changes (mostly color). A noteworthy exception is docsify-themeable which is a full CSS rewrite for use with Docsify v4 that provides a large number of configurable "theme properties" (CSS custom properties) that can be used for customization.

   This update contains CSS which addresses all of the issues outlined above and takes into considerations lessons learned from the success of docsify-themeable: Docsify's "core" styles have been separated from "theme" styles (now referred to as theme "add-ons"), CSS custom properties have been added to provide fast and simple customization without having to navigate CSS rules, site administrators can mix-and-match the official "core" theme with multiple third-party add-ons as preferred, and the rarely used legacy themes have been removed so that Docsify maintainers have only one "core" stylesheet to maintain and test.

3. Prioritize Docsify v4 plugin compatibility (as much as possible)
   While this update contains signficant changes to the CSS that styles Docsify sites, the structure and class names used have remain largely unchanged. This is a conscience decision intended to limit the number of community plugins affected.

Changes

New "core" theme and theme "add-ons"

This is a simple but impactiful change to how we handle first- and third-party themes.

Docsify now offers one "core" theme. This theme contains all of the styles and theme properties needed to render a Docsify site. It is is designed to serve as a minimalist theme on its own, in combination with theme add-ons, and as a starting point for customization by applying class names or modifying theme properties.

Separating the "core" styles needed to render a Docsify site from the "add-on" styles typically associated with theming provides several important benefits.

1. For the Docsify team, having only one "core" theme significantly reduces the maintenance and testing burden that comes with offering multiple independant themes. With v4, the default "Vue" theme received many updates while other "official" themes were neglected. With v5, there will be only one theme for the team to focus on.
2. For site administrators, a single "core" theme designed to work with multiple third-party theme "add-ons" provides both stability and flexibility: core styles are alway maintained by the Docsify team while third-party "add-ons" modify only the parts they need to (color, typography, iconography, etc). Site administrators are free to mix-and-match various theme add-ons as preferred: one add-on can change the color scheme, another can change the syntax highlighting theme, while another can add iconography to various parts of the site.
3. For community contributors, the separation simplifies and expedites the deliver of new customizations with significantly less code. Instead of expecting theme authors create their own "core" theme (which most did by copying vue.css and making a few changes), community members are now encouraging to let the Docsify team handle the "core" CSS while they focus only on the styles they need to change. For example, the v5 "Vue" theme add-on transforms the v5 core theme to look nearly identical to the v4 theme but is less than 1kb in size. This transformation is done by changing 22 theme properties and adding only 3 new CSS rulesets.

Details

• New "core" theme serves as base for all other themes (official and third-party)
• New CSS custom properties for simplified customization of "core" theme
  Note: List of available properties will be made available in documentation by embedding soruce CSS in docs after merge. Merge is required because embedded CSS needs to be in main branch. For now, see _vars.css and _vars-advanced.css for details.
• New theme "add-ons" modify core theme properties and/or add custom declarations as needed.
• New Prism.js theme support
• New configurable sidebar toggle design
• New typography defaults to system sans-serif and monospace fonts instead of relying on external web font.
• New "Core Dark" theme addon provide dark theme styles. Can optionally be applied based on operating system's light/dark setting using @media attribute on <link> element.
• New "Vue" theme addon. Closely replicated popular v4 theme while allowing for v5 enhancements.
• New CSS class names available for adding loading indicators, adding sidebar expand/collapse icons, adding sidebar group styles, clamping sidebar links to a single line with ellipses, and changing the sidebar toggle icon.
• New auto-generated gradient background for cover page (ensure gradient hue is > 50 degree apart, use OKLCH color if supported, randomize grandient angle, reduce brightness in dark mode)
• New button styles (basic, primary, secondary)
• New form element styles (text input, radio, checkbox, )
• New "callouts" (previously "important" and "tip" helpers)
• New default syntax highlighting theme (from docsify-themeable)
• New auto-generated theme color shade and tint colors
• New auto-generated monochromatic color palette
• New form element styles (fields, legend, text input, text area, checkbox, radio, toggles, and select)
• New "headerless" tables
• New kbd styles
• New task list style
• New merged navbar styles (consistent with sidebar nav styles)
• New search plugin styles and keyboard shortcut indicators
• Add ability restore previously focused content element after hiding sidebar
• Add "focus trap" when sidebar is visible on mobile (accessibility)
• Add ability for sidebar links to wrap by default (previous single-line w/ ellipsis display available as CSS class on <body> option)
• Add sidebar page-link, group, and group-title CSS classes to sidebar markup.
• Add reduced motion media query to set all animation/transition timings to zero
• Update Google Font imports (use new variable vs older fixed width fonts)
• Update primary/secondary button order on coverpage (primary should be first)
• Fix missing merged navbar when loading at desktop resolution then resizing to mobile
• Fix inverted open/close sidebar visibility state at desktop/mobile resolutions
• Fix overflow setting to prevent clipping of element focus ring
• Fix safe area inset margins on mobile in landscape orientation
• Fix inverted "tip" and "warn" class names
• Fix scroll padding to prevent headers from touching top edge of viewport when scrolled to
• Remove Stylus dependency (now using only PostCSS)
• Remove legacy themes "Buble", "Dark", "Dolphin", and "Pure".

Documentation updates

• New "UI Kit" page showcasing all elements styled by Docsify
• Update "Quick Start" page template
• Update "Adding pages" page with information on how to properly create sidebar group titles and navbar drop-down menus
• Update "Themes" page with theme and class toggles
• Update "Configuration" page with deprecation warnings for themeColor and topMargin
• Move "Edit Page" link to footer
• Remove docsify-themeable endorsement (currently not compatible with v5 and future is unknown)

Miscellaneous updates

• New search plugin options: insertBefore and insertAfter
• Add PostCSS config file
• Update BrowserSync config (disable "ghost" mode)
• Update tests
• Fix Jest + Prettier 3 conflict
• Fix getAndRemoveDocisfyIgnoreConfig name type (now Docisfy => Docsify)
• Fix execution of sidebar-generating code when hiddenSidebar is true
• Remove inBrowser constant (SSR deprecated, so no longer needed)

Related issue, if any:

• Reset .markdown-section max-width to 800px #2429
• Visually display customizable search keyboard shortcut to user #2391
• Feature: Change 'X' button style  #2287
• Feature request: Improve Positioning of the Hamburger Menu on Mobile #2205
• CSS Style code improvements #2112
• Links text and buttons UI are Overlapping with Zoom 200%, 400%, Text Scaling & High Dpi #1853
• Sidebar render issue #1836
• Sidebar logo occasionally glitches #1796
• Resizable sidebar #1522
• Hidden sidebar causing other plugins issues #1392
• Ability to disable the showing of the navigation bar on the cover #1375
• Integration of docsify-themeable (v5) #1212
• Better sidebar markup: distinguish content with and without sub sections. #1181
• Better markup for sidebar menu items #1170
• Change the pre-processor for css  #1167
• Search plugin: replace image and use button tag #528

What kind of change does this PR introduce?

Bugfix
Feature
Code style update
Docs
Build-related changes

For any code change,

• Related documentation has been updated, if needed
• Related tests have been added or updated, if needed

Does this PR introduce a breaking change?

Yes

Tested in the following browsers:

• Chrome
• Firefox
• Safari
• Edge

[Koooooo-7]

@jhildenbiddle bravo！

I go through all the styling changes, they looks good (not exactly check every css items).

Btw, what does the search options stands for?

// Location in sidebar (default: prepended as first child)
      // Optionally specify insertAfter or insertBefore (not both)
      insertAfter: '.app-name', // CSS selector in .sidebar scope
      insertBefore: '.sidebar-nav', // CSS selector in .sidebar scope

Regarding the changes of the insertElm, my understanding is that it will indicate where the search plugin place location within the sidebar.
I don't real get it for now since the search box we can not make it located in the any place of the page (if so, we could put it in the top, the top right corner ...etc) or popup as a modal, but it is stuck in the sidebar box now.
Personally, I think it is no much places to go besides the top, although we could put it either up or down to the .app-name.
Therefore, to me, it is not that necessary to expose this options individually for now.

(correct me for my bias If I miss something.)

[jhildenbiddle]

@jhildenbiddle bravo！

❤️

Btw, what does the search options stands for?

The goal was to allow end users to position the search field where they want in the sidebar. For example, here is the default first position (appended to sidebar as first child):

Here is how the search bar renders with insertAfter: '.app-name':

Positioning the search field below the app name is the layout I used in docsify-themeable. I wanted to replicate the layout as an option. Providing both insertAfter and insertBefore options ensures that search field can be positioned when elements are not rendered (like the app name/logo) or unknown sidebar content has been added by a plugin (like an ad).

I am open to renaming the option(s). Perhaps I can reduce it down to one option named something like sidebarOrder or insertOrder that accepts a number with 1 (default) meaning first child, 2 meaning immediately after the first sidebar element (likely the app name), etc.? Remember, we have to account for thing like the app name not being rendered (it's optional, so we can't use something like insertAfterName) and for unknown sidebar content (like the ads we show on docsify.js.org).

Regarding moving the search field to other locations, we can do it but I'd prefer to handle that as a separate enhancement (which I assume would be a low priority issue). To be honest, I think the current search design works well with the layout we have. If/when we ever revisit the Docsify layout (v6?), I think that would be a better time to explore new search designs as well.

Let me know if anyone has a preference on renaming the search plugin's new insertAfter and insertBefore options. Thx!

[Koooooo-7]

Regarding moving the search field to other locations, we can do it but I'd prefer to handle that as a separate enhancement (which I assume would be a low priority issue).

Never mind.
I didn't mean we need do the search place enhancement, I meant if we have the functions, the place config could make more sense to me. Put this enhancement in v6 or future all be fine.

---

The goal was to allow end users to position the search field where they want in the sidebar. For example, here is the default first position (appended to sidebar as first child):

As I mentioned, I understand the scenario, but... I only see this when I raise the question.

Personally, I think it is no much places to go besides the top, although we could put it either up or down to the .app-name.

---

After your clarify details, I know there may have other situation:

• Other extra DOMs inserted in sidebar, hence we need to place the search box.
• No default target to us such as .app-name to mount the search box.

It sounds to solve where to mount the search box on, and also it includes the relation problems to the target dom (before/after/ other?).

Currently, the insertAfter and insertBefore is straightforward to me and I think we can use it for now.

---

A little think over

Additional assumption is providing a single mountOn config in further, which support text, css selector, search DOM consumer option such as other mixed Type options and we parse the option to decide how to resolve it.
Possible cases:

For default options with our default render result.

• ' '
  pure default as appName.
• appName
  before the appName
• sidebarNav
  after the appName

---

Customizer

css selector

• [before] .app-name
  same to current insertBefore
• [after] #foo
  same to current insertAfter

search DOM consumer
full customized where to put the searchElm in the sidebarElm.

  (sidebarElm)=>{ 
 const insertElm = sidebarElm.querySelector( ANY_TARGET_YOU_WANT );
 sidebarElm.insertBefore(
   searchElm,
   insertElm
 );
}

The insertBefore and afterBefore can convert to [before] and [after] in future for compatibility.

---

Thx for your patience on this @jhildenbiddle ！ I'm okay with it.
LGTM!