From 03979bf8fc9c0fbb42221dc736f23828d97136c9 Mon Sep 17 00:00:00 2001
From: Silvio Giebl <silvio.giebl@hivemq.com>
Date: Wed, 27 Nov 2019 11:15:57 +0100
Subject: [PATCH] Added documentation for custom color schemes and custom css
---
_sass/custom/custom.scss | 129 ---------------------------------
_sass/overrides.scss | 3 -
assets/js/dark-mode-preview.js | 23 ------
docs/configuration.md | 9 ++-
docs/customization.md | 56 ++++++++++----
5 files changed, 48 insertions(+), 172 deletions(-)
delete mode 100644 _sass/overrides.scss
delete mode 100644 assets/js/dark-mode-preview.js
diff --git a/_sass/custom/custom.scss b/_sass/custom/custom.scss
index 9ac503b6..e69de29b 100644
--- a/_sass/custom/custom.scss
+++ b/_sass/custom/custom.scss
@@ -1,129 +0,0 @@
-////
-//// Typography
-////
-
-//$body-font-family: -apple-system, BlinkMacSystemFont, "helvetica neue", helvetica, roboto, noto, "segoe ui", arial, sans-serif;
-//$mono-font-family: "SFMono-Regular", Menlo, Consolas, Monospace;
-//$root-font-size: 16px; // Base font-size for rems
-//$body-line-height: 1.4;
-//$content-line-height: 1.5;
-//$body-heading-line-height: 1.15;
-
-////
-//// Colors
-////
-
-//$white: #fff;
-
-//$grey-dk-000: #959396;
-//$grey-dk-100: #5c5962;
-//$grey-dk-200: #44434d;
-//$grey-dk-250: #302d36;
-//$grey-dk-300: #27262b;
-
-//$grey-lt-000: #f5f6fa;
-//$grey-lt-100: #eeebee;
-//$grey-lt-200: #ecebed;
-//$grey-lt-300: #e6e1e8;
-
-//$purple-000: #7253ed;
-//$purple-100: #5e41d0;
-//$purple-200: #4e26af;
-//$purple-300: #381885;
-
-//$blue-000: #2c84fa;
-//$blue-100: #2869e6;
-//$blue-200: #264caf;
-//$blue-300: #183385;
-
-//$green-000: #41d693;
-//$green-100: #11b584;
-//$green-200: #009c7b;
-//$green-300: #026e57;
-
-//$yellow-000: #ffeb82;
-//$yellow-100: #fadf50;
-//$yellow-200: #f7d12e;
-//$yellow-300: #e7af06;
-
-//$red-000: #f77e7e;
-//$red-100: #f96e65;
-//$red-200: #e94c4c;
-//$red-300: #dd2e2e;
-
-//$body-background-color: $white;
-//$sidebar-color: $grey-lt-000;
-//$search-background-color: $white;
-//$table-background-color: $white;
-//$code-background-color: $grey-lt-000;
-
-//$body-text-color: $grey-dk-100;
-//$body-heading-color: $grey-dk-300;
-//$search-result-preview-color: $grey-dk-000;
-//$nav-child-link-color: $grey-dk-100;
-//$link-color: $purple-000;
-//$btn-primary-color: $purple-100;
-//$base-button-color: #f7f7f7;
-
-////
-//// Spacing
-////
-
-//$spacing-unit: 1rem; // 1rem == 16px
-
-//$spacers: (
-//sp-0: 0,
-//sp-1: $spacing-unit * 0.25,
-//sp-2: $spacing-unit * 0.5,
-//sp-3: $spacing-unit * 0.75,
-//sp-4: $spacing-unit,
-//sp-5: $spacing-unit * 1.5,
-//sp-6: $spacing-unit * 2,
-//sp-7: $spacing-unit * 2.5,
-//sp-8: $spacing-unit * 3,
-//sp-9: $spacing-unit * 3.5,
-//sp-10: $spacing-unit * 4
-//);
-
-//$sp-1: map-get($spacers, sp-1); // 0.25 rem == 4px
-//$sp-2: map-get($spacers, sp-2); // 0.5 rem == 8px
-//$sp-3: map-get($spacers, sp-3); // 0.75 rem == 12px
-//$sp-4: map-get($spacers, sp-4); // 1 rem == 16px
-//$sp-5: map-get($spacers, sp-5); // 1.5 rem == 24px
-//$sp-6: map-get($spacers, sp-6); // 2 rem == 32px
-//$sp-7: map-get($spacers, sp-7); // 2.5 rem == 40px
-//$sp-8: map-get($spacers, sp-8); // 3 rem == 48px
-//$sp-9: map-get($spacers, sp-9); // 4 rem == 48px
-//$sp-10: map-get($spacers, sp-10); // 4.5 rem == 48px
-
-////
-//// Borders
-////
-
-//$border: 1px solid;
-//$border-radius: 4px;
-//$border-color: $grey-lt-100;
-
-////
-//// Grid system
-////
-
-//$gutter-spacing: $sp-6;
-//$gutter-spacing-sm: $sp-4;
-//$nav-width: 264px;
-//$nav-width-md: 248px;
-//$content-width: 800px;
-//$header-height: 60px;
-//$search-results-width: 500px;
-
-////
-//// Media queries in pixels
-////
-
-//$media-queries: (
-//xs: 320px,
-//sm: 500px,
-//md: $content-width,
-//lg: $content-width + $nav-width,
-//xl: 1400px
-//);
diff --git a/_sass/overrides.scss b/_sass/overrides.scss
deleted file mode 100644
index 21e9527d..00000000
--- a/_sass/overrides.scss
+++ /dev/null
@@ -1,3 +0,0 @@
-//
-// Custom overrides from a user.
-//
diff --git a/assets/js/dark-mode-preview.js b/assets/js/dark-mode-preview.js
deleted file mode 100644
index b9ad81ef..00000000
--- a/assets/js/dark-mode-preview.js
+++ /dev/null
@@ -1,23 +0,0 @@
-document.addEventListener("DOMContentLoaded", function(){
-
- const toggleDarkMode = document.querySelector('.js-toggle-dark-mode')
- const cssFile = document.querySelector('[rel="stylesheet"]')
- const originalCssRef = cssFile.getAttribute('href')
- const darkModeCssRef = originalCssRef.replace('just-the-docs.css', 'dark-mode-preview.css')
- const buttonCopy = ['Return to the light side', 'Preview dark color scheme']
- const updateButtonText = function(toggleDarkMode) {
- toggleDarkMode.textContent === buttonCopy[0] ?
- toggleDarkMode.textContent = buttonCopy[1] :
- toggleDarkMode.textContent = buttonCopy[0]
- }
-
- jtd.addEvent(toggleDarkMode, 'click', function(){
- if (cssFile.getAttribute('href') === originalCssRef) {
- cssFile.setAttribute('href', darkModeCssRef)
- updateButtonText(toggleDarkMode)
- } else {
- cssFile.setAttribute('href', originalCssRef)
- updateButtonText(toggleDarkMode)
- }
- })
-})
diff --git a/docs/configuration.md b/docs/configuration.md
index 939b6ae7..26db5b57 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -38,7 +38,6 @@ search_enabled: true
# Enable support for hyphenated search words:
search_tokenizer_separator: /[\s/]+/
-
```
## Aux links
@@ -56,7 +55,7 @@ aux_links:
# Heading anchor links appear on hover over h1-h6 tags in page content
# allowing users to deep link to a particular heading on a page.
#
-# Supports true (default) or false/nil
+# Supports true (default) or false
heading_anchors: true
```
@@ -70,8 +69,8 @@ footer_content: "Copyright © 2017-2019 Patrick Marsceill. Distributed by an
## Color scheme
```yaml
-# Color scheme currently only supports "dark" or nil (default)
-color_scheme: "dark"
+# Color scheme supports "light" (default) and "dark"
+color_scheme: dark
```
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
@@ -81,8 +80,10 @@ const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
jtd.addEvent(toggleDarkMode, 'click', function(){
if (jtd.getTheme() === 'dark') {
jtd.setTheme('light');
+ toggleDarkMode.textContent = 'Preview dark color scheme';
} else {
jtd.setTheme('dark');
+ toggleDarkMode.textContent = 'Return to the light side';
}
});
</script>
diff --git a/docs/customization.md b/docs/customization.md
index 9848ad37..cbcd38cc 100644
--- a/docs/customization.md
+++ b/docs/customization.md
@@ -29,8 +29,8 @@ To enable a color scheme, set the `color_scheme` parameter in your site's `_conf
{: .no_toc }
```yaml
-# Color scheme currently only supports "dark" or nil (default)
-color_scheme: "dark"
+# Color scheme supports "light" (default) and "dark"
+color_scheme: dark
```
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
@@ -40,36 +40,66 @@ const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
jtd.addEvent(toggleDarkMode, 'click', function(){
if (jtd.getTheme() === 'dark') {
jtd.setTheme('light');
+ toggleDarkMode.textContent = 'Preview dark color scheme';
} else {
jtd.setTheme('dark');
+ toggleDarkMode.textContent = 'Return to the light side';
}
});
</script>
-## Specific visual customization
+## Custom schemes
-To customize your site’s aesthetic, open `_sass/custom/custom.scss` in your editor to see if there is a variable that you can override. Most styles like fonts, colors, spacing, etc. are derived from these variables. To override a specific variable, uncomment its line and change its value.
+### Define a custom scheme
-For example, to change the link color from the purple default to blue, open `_sass/custom/custom.css` and find the `$link-color` variable on line `50`. Uncomment it, and change its value to our `$blue-000` variable, or another shade of your choosing.
+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](https://github.com/pmarsceill/just-the-docs/tree/master/_sass/support/_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 }
```scss
-// ...
-//
-// $body-text-color: $grey-dk-100;
-// $body-heading-color: $grey-dk-300;
$link-color: $blue-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:
+```yaml
+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.
+
+```js
+jtd.setTheme('foo');
+```
-## Override styles
+## Override and completely custom styles
-For styles that aren't defined as a variables, you may want to modify specific CSS classes. To add your own CSS overrides at the end of the cascade, edit `_sass/overrides.scss`. This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied.
+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.
--
GitLab