feat: v5 style overhaul #2469
feat: v5 style overhaul #2469
Conversation
- Add custom properties for customization - Add default button styles - Add default form element styles - Add headerless tables - Add spinner helper - Update content font size (15px => 16px) - Update heading sizes and margins - Update task list styles - Update link styles - Update callout helper styles - Fix font consistency (e.g., search field) - Fix border radius consistency - Fix codeblock focus style - Fix scrollbars on macOS (use native) - Reduce unnecessarily high specificity
- Update example html page - Update sidebar with explicit bold - Update styles to accomodate UI kit - Rename “Writing more pages” - Add light/dark mode images - Add ins and samp styles (GFM compatibility)
- Add configurable max-width (Fix #2429) - Add z-index vars for maintainability - Fix .content style conflicts - Update navbar and GitHub corner styles
There was a problem hiding this comment.
@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.)
❤️
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 
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 I am open to renaming the option(s). Perhaps I can reduce it down to one option named something like 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 |
Never mind.
As I mentioned, I understand the scenario, but... I only see this when I raise the question.
After your clarify details, I know there may have other situation:
It sounds to solve where to Currently, the A little think overAdditional assumption is providing a single For default options with our default render result.
Customizer
The Thx for your patience on this @jhildenbiddle ！ I'm okay with it. |
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.
Goals
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.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.
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.
vue.cssand 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
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
mainbranch. For now, see_vars.cssand_vars-advanced.cssfor details.@mediaattribute on<link>element.kbdstyles<body>option)page-link,group, andgroup-titleCSS classes to sidebar markup.Documentation updates
themeColorandtopMarginMiscellaneous updates
insertBeforeandinsertAftergetAndRemoveDocisfyIgnoreConfigname type (nowDocisfy=>Docsify)hiddenSidebaristrueinBrowserconstant (SSR deprecated, so no longer needed)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: