search

docsifyjs / docsify

🃏 A magical documentation site generator.
https://docsify.js.org
MIT License
27.82k stars 5.68k forks source link

feat: v5 style overhaul #2469

Closed jhildenbiddle closed 4 months ago

jhildenbiddle commented 4 months ago

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

Documentation updates

Miscellaneous updates

Related issue, if any:

What kind of change does this PR introduce?

Bugfix Feature Code style update Docs Build-related changes

For any code change,

Does this PR introduce a breaking change?

Yes

Tested in the following browsers:

vercel[bot] commented 4 months ago

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Comments Updated (UTC)
docsify-preview ✅ Ready (Inspect) Visit Preview 💬 Add feedback Jul 18, 2024 8:40pm
jhildenbiddle commented 4 months ago

@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 commented 4 months ago

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:

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.

Customizer

css selector

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!