Snippets Groups Projects

2 years ago

docs: Mention caveat about variable dependencies (#555) · 26fad7dd

Waldir Pimenta authored 2 years ago

Looking at how the variables are defined in _variables.scss, with various dependencies between them aimed at ensuring a consistent color scheme, one might expect that redefining a given variable would affect the remaining styles that depend on it.

This is not the case, however, due to the order in which the files are processed. This PR edits the documentation to mention the non-propagating behavior of redefined variables, to better guide users that wish to customize the site using custom themes, and call their attention to the need to redefine the dependency relations as well.

Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Patrick Marsceill <pmarsceill@users.noreply.github.com>

26fad7dd

docs: Mention caveat about variable dependencies (#555)

Waldir Pimenta authored 2 years ago

Looking at how the variables are defined in _variables.scss, with various dependencies between them aimed at ensuring a consistent color scheme, one might expect that redefining a given variable would affect the remaining styles that depend on it.

This is not the case, however, due to the order in which the files are processed. This PR edits the documentation to mention the non-propagating behavior of redefined variables, to better guide users that wish to customize the site using custom themes, and call their attention to the need to redefine the dependency relations as well.

Co-authored-by: Matt Wang <matt@matthewwang.me>
Co-authored-by: Patrick Marsceill <pmarsceill@users.noreply.github.com>

customization.md 5.05 KiB

layout: default
title: Customization
nav_order: 6

Customization

{: .no_toc }

Table of contents

{: .no_toc .text-delta }

TOC {:toc}

Color schemes

{: .d-inline-block }

New {: .label .label-green }

Just the Docs supports two color schemes: light (default), and dark.

To enable a color scheme, set the color_scheme parameter in your site's _config.yml file:

Example

{: .no_toc }

# Color scheme supports "light" (default) and "dark"
color_scheme: dark

Preview dark color scheme

Custom schemes

Define a custom scheme

You can add custom schemes. If you want to add a scheme named foo (can be any name) just add a file _sass/color_schemes/foo.scss (replace foo by your scheme name) where you override theme variables to change colors, fonts, spacing, etc.

Available variables are listed in the _variables.scss file.

For example, to change the link color from the purple default to blue, include the following inside your scheme file:

Example

{: .no_toc }

$link-color: $blue-000;

Keep in mind that changing a variable will not automatically change the value of other variables that depend on it. For example, the default link color ($link-color) is set to $purple-000. However, redefining $purple-000 in a custom color scheme will not automatically change $link-color to match it. Instead, each variable that relies on previously-cascaded values must be manually reimplemented by copying the dependent rules from _variables.scss — in this case, rewriting $link-color: $purple-000;.

Note: Editing the variables directly in _sass/support/variables.scss is not recommended and can cause other dependencies to fail. Please use scheme files.

Use a custom scheme

To use the custom color scheme, only set the color_scheme parameter in your site's _config.yml file:

color_scheme: foo

Switchable custom scheme

If you want to be able to change the scheme dynamically, for example via javascript, just add a file assets/css/just-the-docs-foo.scss (replace foo by your scheme name) with the following content:

{% raw %} --- --- {% include css/just-the-docs.scss.liquid color_scheme="foo" %} {% endraw %}

This allows you to switch the scheme via the following javascript.

jtd.setTheme("foo")

Override and completely custom styles

For styles that aren't defined as variables, you may want to modify specific CSS classes. Additionally, you may want to add completely custom CSS specific to your content. To do this, put your styles in the file _sass/custom/custom.scss. This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied.

For example, if you'd like to add your own styles for printing a page, you could add the following styles.

Example

{: .no_toc }

// Print-only styles.
@media print {
  .side-bar,
  .page-header {
    display: none;
  }
  .main-content {
    max-width: auto;
    margin: 1em;
  }
}

Override includes

The site can be modified by overriding any of the custom Jekyll includes provided by default in the theme.

To do this, create an _includes directory and make a copy of the specific file you wish to modify. Any content added to this file will override the theme defaults. You can learn more about this process in the Jekyll docs for Overriding theme defaults.

The following includes were made available to you:

Custom Footer

_includes/footer_custom.html

This content appears at the bottom of every page's main content. More info for this include can be found in the Configuration - Footer content.

Custom Head

_includes/head_custom.html

Any HTML added to this file will be inserted before the closing <head> tag. This might include additional <meta>, <link>, or <script> tags.

Custom Header

_includes/header_custom.html

Content added to this file appears at the top of every page's main content between the site search and auxiliary links if they are enabled. If search_enabled were set to false and aux_links were removed, the content of header_custom.html would occupy the space at the top of every page.

Custom Nav Footer

_includes/nav_footer_custom.html

Any content added to this file will appear at the bottom left of the page below the site's navigation. By default an attribution to Just the Docs is displayed which reads, This site uses Just the Docs, a documentation theme for Jekyll..