Skip to content

themes.md

Latest commit

History

History
433 lines (337 loc) · 11.9 KB

themes.md

File metadata and controls

433 lines (337 loc) · 11.9 KB
Raw

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 --><linkrel="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.

[!IMPORTANT] Theme add-ons must be loaded after the core theme.

<!-- Core Theme --><linkrel="stylesheet" href="..." /><!-- Theme (add-on) --><linkrel="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) --><linkrel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/addons/core-dark.min.css" />
<!-- Core Dark - Dark Mode Only (add-on) --><linkrel="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) --><linkrel="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.

<bodyclass="...">

Loading

Display a loading animation while waiting for Docsify to initialize.

<bodyclass="loading">

Sidebar chevrons

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

Root group titles display chevrons only when collapsibleSidebarGroups is enabled.

Preview sidebar-chevron-right
Preview sidebar-chevron-left
Hide root-level chevrons with sidebar-chevron-root-hidden
<bodyclass="sidebar-chevron-right">
<bodyclass="sidebar-chevron-left">

To hide chevrons on all root-level page links and group titles while retaining chevrons on nested page links, add the sidebar-chevron-root-hidden class:

<bodyclass="sidebar-chevron-right sidebar-chevron-root-hidden">

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
<bodyclass="sidebar-group-box">
<bodyclass="sidebar-group-underline">

Sidebar link clamp

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

Preview sidebar-link-clamp
<bodyclass="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
<bodyclass="sidebar-toggle-chevron">
<bodyclass="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 --><linkrel="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 */@importurl('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;
}

    [!TIP] 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.

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

[!TIP] 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.

_vars.css

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.

_vars-advanced.css

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>