feat: v5 style overhaul (#2469)

Style updates: - 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](https://jhildenbiddle.github.io/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](https://jhildenbiddle.github.io/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)
docsifyjs · Jul 19, 2024 · 77d93fa · 77d93fa
1 parent 90c0b02
commit 77d93fa
Show file tree

Hide file tree

Showing 74 changed files with 4,964 additions and 3,036 deletions.
diff --git a/.npmignore b/.npmignore
@@ -1,4 +1,3 @@
 .eslintignore
-.eslintrc.cjs
 .github
 .gitignore
diff --git a/.prettierignore b/.prettierignore
@@ -4,6 +4,8 @@ dist
 lib
 
 # Files
+_vars.css
+_vars-advanced.css
 CHANGELOG.md
 emoji-data.*
-HISTORY.md
+HISTORY.md
diff --git a/docs/README.md b/docs/README.md
@@ -1,4 +1,4 @@
-## docsify
+# docsify
 
 > A magical documentation site generator.
 

diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -1,12 +1,17 @@
+<!-- markdownlint-disable first-line-h1 -->
+
 ![logo](_media/icon.svg)
 
 # docsify <small>4.13.0</small>
 
-> A magical documentation site generator.
+> A magical documentation site generator
 
 - Simple and lightweight
-- No statically built html files
+- No statically built HTML files
 - Multiple themes
 
+[Get Started](#docsify)
 [GitHub](https://github.com/docsifyjs/docsify/)
-[Getting Started](#docsify)
+
+<!-- ![color](#f0f0f0) -->
+<!-- ![](/_media/icon.svg) -->
diff --git a/docs/_media/example.html b/docs/_media/example.html
@@ -1 +1,31 @@
-<h1>To infinity and Beyond!</h1>
+<style>
+ html,
+ body {
+ margin: 0;
+ padding: 0;
+ min-height: 100%;
+ }
+
+ body {
+ background-color: #4158d0;
+ background-image: linear-gradient(
+ 43deg,
+ #4158d0 0%,
+ #c850c0 46%,
+ #ffcc70 100%
+ );
+ color: #fff;
+ font-family: sans-serif;
+ }
+
+ main {
+ display: flex;
+ justify-content: center;
+ align-items: center;
+ height: 100vh;
+ }
+</style>
+
+<main>
+ <p>Example HTML Page</p>
+</main>
diff --git a/docs/_media/moon.svg b/docs/_media/moon.svg
diff --git a/docs/_media/sun.svg b/docs/_media/sun.svg
diff --git a/docs/_navbar.md b/docs/_navbar.md
@@ -1,4 +1,7 @@
+<!-- markdownlint-disable first-line-h1 -->
+
 - Translations
+
  - [:uk: English](/)
  - [:cn: 简体中文](/zh-cn/)
  - [:de: Deutsch](/de-de/)

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -1,9 +1,11 @@
+<!-- markdownlint-disable first-line-h1 -->
+
 - Getting started
 
  - [Quick start](quickstart.md)
- - [Writing more pages](more-pages.md)
- - [Custom navbar](custom-navbar.md)
+ - [Adding pages](adding-pages.md)
  - [Cover page](cover.md)
+ - [Custom navbar](custom-navbar.md)
 
 - Customization
 
@@ -23,6 +25,7 @@
  - [CDN](cdn.md)
  - [Offline Mode (PWA)](pwa.md)
  - [Embed Files](embed-files.md)
+ - [UI Kit](ui-kit.md)
 
 - [Awesome docsify](awesome.md)
 - [Changelog](changelog.md)
diff --git a/docs/more-pages.md → docs/adding-pages.md b/docs/more-pages.md → docs/adding-pages.md
@@ -1,4 +1,4 @@
-# More pages
+# Adding pages
 
 If you need more pages, you can simply create more markdown files in your docsify directory. If you create a file named `guide.md`, then it is accessible via `/#/guide`.
 
@@ -46,7 +46,23 @@ Create the `_sidebar.md`:
 <!-- docs/_sidebar.md -->
 
 - [Home](/)
-- [Guide](guide.md)
+- [Page 1](page-1.md)
+```
+
+To create section headers:
+
+```markdown
+<!-- docs/_sidebar.md -->
+
+- Section Header 1
+
+ - [Home](/)
+ - [Page 1](page-1.md)
+
+- Section Header 2
+
+ - [Page 2](page-2.md)
+ - [Page 3](page-3.md)
 ```
 
 You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore.

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -376,7 +376,7 @@ window.$docsify = {
 
 Website logo as it appears in the sidebar. You can resize it using CSS.
 
-!> Logo will only bee visible if `name` prop is also set. See [name](#name) configuration.
+!> Logo will only be visible if `name` prop is also set. See [name](#name) configuration.
 
 ```js
 window.$docsify = {
@@ -917,17 +917,9 @@ If you have a link to the homepage in the sidebar and want it to be shown as act
 
 For more details, see [#1131](https://github.com/docsifyjs/docsify/issues/1131).
 
-## themeColor (_deprecated_)
+## themeColor ⚠️
 
-> **Warning** Deprecated. Use the CSS var `--theme-color` in your `<style>` sheet. Example:
->
-> ```html
-> <style>
-> :root {
-> --theme-color: deeppink;
-> }
-> </style>
-> ```
+!> Deprecated as of v5. Use the `--theme-color` [theme property](themes#theme-properties) to [customize](themes#customization) your theme color.
 
 - Type: `String`
 
@@ -939,16 +931,18 @@ window.$docsify = {
 };
 ```
 
-## topMargin
+## topMargin ⚠️
 
-- Type: `Number`
+!> Deprecated as of v5. Use the `--scroll-padding-top` [theme property](themes#theme-properties) to specify a scroll margin when using a sticky navbar.
+
+- Type: `Number|String`
 - Default: `0`
 
-Adds a space on top when scrolling the content page to reach the selected section. This is useful in case you have a _sticky-header_ layout and you want to align anchors to the end of your header.
+Adds scroll padding to the top of the viewport. This is useful when you have added a sticky or "fixed" element and would like auto scrolling to align with the bottom of your element.
 
 ```js
 window.$docsify = {
- topMargin: 90, // default: 0
+ topMargin: 90, // 90, '90px', '2rem', etc.
 };
 ```
 

diff --git a/docs/cover.md b/docs/cover.md
@@ -6,58 +6,61 @@ Activate the cover feature by setting `coverpage` to **true**. See [coverpage co
 
 Set `coverpage` to **true**, and create a `_coverpage.md`:
 
-```html
-<!-- index.html -->
-
-<script>
- window.$docsify = {
- coverpage: true,
- };
-</script>
-<script src="//cdn.jsdelivr.net/npm/docsify@5/dist/docsify.min.js"></script>
+```js
+window.$docsify = {
+ coverpage: true,
+};
 ```
 
 ```markdown
 <!-- _coverpage.md -->
 
 ![logo](_media/icon.svg)
 
-# docsify <small>3.5</small>
+# docsify
 
-> A magical documentation site generator.
+> A magical documentation site generator
 
 - Simple and lightweight
-- No statically built html files
+- No statically built HTML files
 - Multiple themes
 
 [GitHub](https://github.com/docsifyjs/docsify/)
 [Get Started](#docsify)
 ```
 
-## Custom background
+## Customization
 
-The background color is generated randomly by default. You can customize the background color or a background image:
+The cover page can be customized using [theme properties](themes#theme-properties):
 
-```markdown
-<!-- _coverpage.md -->
+<!-- prettier-ignore -->
+```css
+:root {
+ --cover-bg : url('path/to/image.png');
+ --cover-bg-overlay : rgba(0, 0, 0, 0.5);
+ --cover-color : #fff;
+ --cover-title-color: var(--theme-color);
+ --cover-title-font : 600 var(--font-size-xxxl) var(--font-family);
+}
+```
 
-# docsify <small>3.5</small>
+Alternatively, a background color or image can be specified in the cover page markdown.
 
-[GitHub](https://github.com/docsifyjs/docsify/)
-[Get Started](#quick-start)
+```markdown
+<!-- background color -->
 
+![color](#f0f0f0)
+```
+
+```markdown
 <!-- background image -->
 
 ![](_media/bg.png)
-
-<!-- background color -->
-
-![color](#f0f0f0)
 ```
 
 ## Coverpage as homepage
 
-Normally, the coverpage and the homepage appear at the same time. Of course, you can also separate the coverpage by [onlyCover option](configuration.md#onlycover).
+Normally, the coverpage and the homepage appear at the same time. Of course, you can also separate the coverpage by [`onlyCover`](configuration.md#onlycover) option.
 
 ## Multiple covers
 

diff --git a/docs/custom-navbar.md b/docs/custom-navbar.md
@@ -40,6 +40,17 @@ Alternatively, you can create a custom markdown-based navigation file by setting
 - [chinese](/zh-cn/)
 ```
 
+To create drop-down menus:
+
+```markdown
+<!-- _navbar.md -->
+
+- Translations
+
+ - [En](/)
+ - [chinese](/zh-cn/)
+```
+
 !> You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore.
 
 `_navbar.md` is loaded from each level directory. If the current directory doesn't have `_navbar.md`, it will fall back to the parent directory. If, for example, the current path is `/guide/quick-start`, the `_navbar.md` will be loaded from `/guide/_navbar.md`.
@@ -59,6 +70,7 @@ You can create sub-lists by indenting items that are under a certain parent.
  - [Cover page](cover.md)
 
 - Configuration
+
  - [Configuration](configuration.md)
  - [Themes](themes.md)
  - [Using plugins](plugins.md)