mirror of https://github.com/docsifyjs/docsify.git synced 2025-12-08 19:55:52 +00:00

John Hildenbiddle 77d93fae78

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)

2024-07-19 15:34:51 +00:00

12 KiB

Raw Blame History

Themes

Core theme

The Docsify "core" theme contains all of the styles and theme properties needed to render a Docsify site. This theme is designed to serve as a minimalist theme on its own, in combination with theme add-ons, modified using core classes, and as a starting point for customization.

<!-- Core Theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/core.min.css" />

Theme add-ons

Theme add-ons are used in combination with the core theme. Add-ons contain CSS rules that modify theme properties values and/or add custom style declarations. They can often (but not always) be used with other add-ons.

!> Theme add-ons must be loaded after the core theme.

<!-- Core Theme -->
<link rel="stylesheet" href="..." />

<!-- Theme (add-on) -->
<link rel="stylesheet" href="..." />

Core Dark (Add-on)

Dark mode styles for the core theme. Styles can applied only when an operating system's dark mode is active by specifying a media attribute.

Preview Core Dark
Preview Core Dark (Dark Mode Only)

<!-- Core Dark (add-on) -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/addons/core-dark.min.css" />

<!-- Core Dark - Dark Mode Only (add-on) -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/addons/core-dark.min.css" media="(prefers-color-scheme: dark)" />

Vue theme (Add-on)

The popular Docsify v4 theme.

Preview Vue

<!-- Vue Theme (add-on) -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/addons/vue.min.css" />

Classes

The core theme provides several CSS classes for customizing your Docsify site. These classes should be applied to the <body> element within your index.html page.

<body class="...">

Loading

Display a loading animation while waiting for Docsify to initialize.

<body class="loading">

Sidebar chevrons

Display expand/collapse icons on page links in the sidebar.

Preview sidebar-chevron-right
Preview sidebar-chevron-left

<body class="sidebar-chevron-right">

<body class="sidebar-chevron-left">

To prevent chevrons from displaying for specific page links, add a no-chevron class as follows:

[My Page](page.md ':class=no-chevron')

Theme properties

:root {
  --sidebar-chevron-collapsed-color: var(--color-mono-3);
  --sidebar-chevron-expanded-color : var(--theme-color);
}

Sidebar groups

Add visual distinction between groups of links in the sidebar.

Preview sidebar-group-box
Preview sidebar-group-underline

<body class="sidebar-group-box">

<body class="sidebar-group-underline">

Sidebar link clamp

Limit multi-line sidebar links to a single line followed by an ellipses.

Preview sidebar-link-clamp

<body class="sidebar-link-clamp">

Sidebar toggle

Display a "hamburger" icon (three lines) in the sidebar toggle button instead of the default "kebab" icon.

Preview sidebar-toggle-chevron
Preview sidebar-toggle-hamburger

<body class="sidebar-toggle-chevron">

<body class="sidebar-toggle-hamburger">

Customization

Docsify provides theme properties for simplified customization of frequently modified styles.

Add a <style> tag after the theme stylesheet in your index.html.

<!-- Theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/core.min.css" />

<!-- Custom theme styles -->
<style>
  :root {
    /* ... */
  }
</style>

Theme properties can also be set on a per-page basis in markdown.

# My Heading

Hello, World!

<style>
  :root {
    /* ... */
  }
</style>

Set custom theme properties within a :root declaration.

:root {
  --theme-color: red;
  --font-size  : 15px;
  --line-height: 1.5;
}

Custom theme properties can be conditionally applied in light and/or dark mode.

/* Light and dark mode */
:root {
  --theme-color: pink;
}

/* Light mode only */
@media (prefers-color-scheme: light) {
  :root {
    --color-bg  : #eee;
    --color-text: #444;
  }
}

/* Dark mode only */
@media screen and (prefers-color-scheme: dark) {
  :root {
    --color-bg  : #222;
    --color-text: #ddd;
  }
}

Custom fonts can be used by adding web font resources and modifying --font-family properties as needed:

/* Fonts: Noto Sans, Noto Emoji, Noto Mono */
@import url('https://fonts.googleapis.com/css2?family=Noto+Color+Emoji&family=Noto+Sans+Mono:wght@100..900&family=Noto+Sans:ital,wght@0,100..900;1,100..900&display=swap');

:root {
  --font-family      : 'Noto Sans', sans-serif;
  --font-family-emoji: 'Noto Color Emoji', sans-serif;
  --font-family-mono : 'Noto Sans Mono', monospace;
}

?> Theme authors: Consider providing instructions for loading your recommended web fonts manually instead of including them in your theme using @import. This allows users who prefer a different font to avoid loading your recommended web font(s) unnecessarily.

Advanced styling may require custom CSS declarations. This is expected, however custom CSS declarations may break when new versions of Docsify are released. When possible, leverage theme properties instead of custom declarations or lock your CDN URLs to a specific version to avoid potential issues when using custom CSS declarations.
```
.sidebar li.active > a {
  border-right: 3px solid var(--theme-color);
}
```

Theme properties

The following properties are available in all official Docsify themes. Default values for the "Core" theme are shown.

?> Theme and plugin authors: We encourage you to leverage these custom theme properties and to offer similar customization options in your projects.

Common

Below are the most commonly modified theme properties. Advanced theme properties are also available for use but typically do not need to be modified.

TBD

Advanced

Advanced theme properties are also available for use but typically do not need to be modified. Values derived from common theme properties but can be set explicitly if preferred.