Skip to content

Latest commit

 

History

History
425 lines (328 loc) · 11.5 KB

themes.md

File metadata and controls

425 lines (328 loc) · 11.5 KB

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.

  1. 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>

  2. 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;
  }
}

  3. 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:[email protected]&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.

  4. 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.

TBD

Community

See Awesome Docsify for additional community themes.

<script> (function () { const toggleElms = Docsify.dom.findAll( 'input:where([data-class], [data-sheet])', ); const previewSheets = Docsify.dom.findAll( 'link[rel="stylesheet"][data-sheet]', ); function handleChange(e) { const elm = e.target.closest('[data-class], [data-sheet]'); const value = elm.value; const groupVal = elm.getAttribute('data-group'); const radioGroupName = elm.matches('[type="radio"]') ? elm.name : undefined; // Toggle class if (elm.matches('[data-class]')) { document.body.classList.toggle(value, elm.checked); } // Toggle sheet else { const themeSheet = previewSheets.find( sheet => sheet.getAttribute('data-sheet') === value, ); themeSheet && (themeSheet.disabled = !elm.checked); } if (!elm.checked || (!groupVal && !radioGroupName)) { return; } // Group elements & values const groupElms = toggleElms.filter(elm => groupVal ? groupVal === elm.getAttribute('data-group') : radioGroupName === elm.name, ); const groupVals = groupElms.map(elm => elm.value); if (groupElms.length <= 1) { return; } if (groupVal) { // Uncheck other group elements groupElms.forEach(groupElm => { if (groupElm !== elm) { groupElm.checked = false; } }); } // Remove group classes if (elm.matches('[data-class]')) { groupVals.forEach(className => { if (className !== value) { document.body.classList.remove(className); } }); } // Disable group sheets else { const otherSheets = groupVals .map(val => previewSheets.find(sheet => sheet.getAttribute('data-sheet') === val), ) .filter(sheet => sheet && sheet.getAttribute('data-sheet') !== value); const disableSheets = otherSheets.length ? otherSheets : previewSheets; disableSheets.forEach(sheet => sheet.disabled = true); } } // Toggle active elms toggleElms.forEach(elm => { const value = elm.value; // Class toggle if (elm.matches('[data-class]')) { elm.checked = document.body.classList.contains(value); } // Sheet toggle else { const previewSheet = previewSheets.find( sheet => sheet.getAttribute('data-sheet') === value, ); elm.checked = previewSheet && !previewSheet.disabled; } }); toggleElms.forEach(elm => elm.addEventListener('change', handleChange)); })(); </script>