Merge branch 'improvement/custom-themes' of git://github.com/SgtSilvio/just-the-docs into SgtSilvio-improvement/custom-themes

pull/1/head
Patrick Marsceill 2 years ago
commit 59d4802ce3
No known key found for this signature in database
GPG Key ID: 286B93882D828F40
  1. 7
      .stylelintrc.json
  2. 5
      _config.yml
  3. 1
      _includes/css/custom.scss.liquid
  4. 7
      _includes/css/just-the-docs.scss.liquid
  5. 2
      _includes/head.html
  6. 2
      _layouts/table_wrappers.html
  7. 0
      _sass/color_schemes/light.scss
  8. 129
      _sass/custom/custom.scss
  9. 19
      _sass/modules.scss
  10. 3
      _sass/overrides.scss
  11. 45
      assets/css/dark-mode-preview.scss
  12. 3
      assets/css/just-the-docs-dark.scss
  13. 8
      assets/css/just-the-docs-default.scss
  14. 3
      assets/css/just-the-docs-light.scss
  15. 49
      assets/css/just-the-docs.scss
  16. 14
      assets/js/just-the-docs.js
  17. 21
      docs/configuration.md
  18. 68
      docs/customization.md

@ -1,7 +1,8 @@
{
"ignoreFiles": [
"assets/css/just-the-docs.scss",
"assets/css/dark-mode-preview.scss",
"ignoreFiles" : [
"assets/css/just-the-docs-default.scss",
"assets/css/just-the-docs-light.scss",
"assets/css/just-the-docs-dark.scss",
"_sass/vendor/**/*.scss"
],
"extends": ["stylelint-config-primer", "stylelint-config-prettier"],

@ -38,10 +38,11 @@ aux_links:
"Just the Docs on GitHub":
- "//github.com/pmarsceill/just-the-docs"
# Footer content
# Footer content
# appears at the bottom of every page's main content
footer_content: "Copyright &copy; 2017-2019 Patrick Marsceill. Distributed by an <a href=\"https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt\">MIT license.</a>"
<<<<<<< HEAD
# Footer last edited timestamp
last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html
@ -53,7 +54,7 @@ gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github U
gh_edit_branch: "master" # the branch that your docs is served from
gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
# Color scheme currently only supports "dark" or nil (default)
# Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
color_scheme: nil
# Google Analytics Tracking (optional)

@ -0,0 +1 @@
@import "./custom/custom";

@ -0,0 +1,7 @@
{% if site.logo %}
$logo: "{{ site.logo | absolute_url }}";
{% endif %}
@import "./support/support";
@import "./color_schemes/{{ include.color_scheme }}";
@import "./modules";
{% include css/custom.scss.liquid %}

@ -12,7 +12,7 @@
<link rel="shortcut icon" href="{{ 'favicon.ico' | absolute_url }}" type="image/x-icon">
<link rel="stylesheet" href="{{ '/assets/css/just-the-docs.css' | absolute_url }}">
<link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | absolute_url }}">
{% if site.ga_tracking != nil %}
<script async src="https://www.googletagmanager.com/gtag/js?id={{ site.ga_tracking }}"></script>

@ -4,4 +4,4 @@ layout: vendor/compress
{% assign content_ = content | replace: '<table', '<div class="table-wrapper"><table' %}
{% assign content_ = content_ | replace: '</table>', '</table></div>' %}
{{ content_ }}
{{ content_ }}

@ -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
//);

@ -0,0 +1,19 @@
//
// Import external dependencies
//
@import "./vendor/normalize.scss/normalize.scss";
//
// Modules
//
@import "./base";
@import "./layout";
@import "./content";
@import "./navigation";
@import "./typography";
@import "./labels";
@import "./buttons";
@import "./search";
@import "./tables";
@import "./code";
@import "./utilities/utilities";

@ -1,3 +0,0 @@
//
// Custom overrides from a user.
//

@ -1,45 +0,0 @@
---
# this ensures Jekyll reads the file to be transformed into CSS later
# only Main files contain this front matter, not partials.
---
{% if site.logo %}
$logo: "{{ site.logo | absolute_url }}";
{% endif %}
//
// Import external dependencies
//
@import "./vendor/normalize.scss/normalize.scss";
//
// Import Just the Docs scss
//
// Support
@import "./support/support";
//
// Import custom color scheme scss
//
@import "./color_schemes/dark.scss";
// Modules
@import "./base";
@import "./layout";
@import "./content";
@import "./navigation";
@import "./typography";
@import "./labels";
@import "./buttons";
@import "./search";
@import "./tables";
@import "./code";
@import "./utilities/utilities";
//
// Import custom overrides
//
@import "./custom/custom";

@ -0,0 +1,3 @@
---
---
{% include css/just-the-docs.scss.liquid color_scheme="dark" %}

@ -0,0 +1,8 @@
---
---
{% if site.color_scheme and site.color_scheme != "nil" %}
{% assign color_scheme = site.color_scheme %}
{% else %}
{% assign color_scheme = "light" %}
{% endif %}
{% include css/just-the-docs.scss.liquid color_scheme=color_scheme %}

@ -0,0 +1,3 @@
---
---
{% include css/just-the-docs.scss.liquid color_scheme="light" %}

@ -1,49 +0,0 @@
---
# this ensures Jekyll reads the file to be transformed into CSS later
# only Main files contain this front matter, not partials.
---
{% if site.logo %}
$logo: "{{ site.logo | absolute_url }}";
{% endif %}
//
// Import external dependencies
//
@import "./vendor/normalize.scss/normalize.scss";
//
// Import Just the Docs scss
//
// Support
@import "./support/support";
//
// Import custom overrides
//
@import "./custom/custom";
//
// Import custom color scheme scss
//
{% if site.color_scheme == "dark" %}
@import "./color_schemes/dark.scss";
{% endif %}
// Modules
@import "./base";
@import "./layout";
@import "./content";
@import "./navigation";
@import "./typography";
@import "./labels";
@import "./buttons";
@import "./search";
@import "./tables";
@import "./code";
@import "./utilities/utilities";
@import "./overrides";

@ -279,11 +279,25 @@ function initSearch() {
}
}
// Focus
function pageFocus() {
var mainContent = document.querySelector('.js-main-content');
mainContent.focus();
}
// Switch theme
jtd.getTheme = function() {
var cssFileHref = document.querySelector('[rel="stylesheet"]').getAttribute('href');
return cssFileHref.substring(cssFileHref.lastIndexOf('-') + 1, cssFileHref.length - 4);
}
jtd.setTheme = function(theme) {
var cssFile = document.querySelector('[rel="stylesheet"]');
cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | absolute_url }}' + theme + '.css');
}
// Document ready
jtd.onReady(function(){

@ -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
```
@ -88,12 +87,24 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t
## 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>
<script type="text/javascript" src="{{ "/assets/js/dark-mode-preview.js" | absolute_url }}"></script>
<script>
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>
See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more information.

@ -29,37 +29,77 @@ 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>
<script type="text/javascript" src="{{ "/assets/js/dark-mode-preview.js" | absolute_url }}"></script>
<script>
const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
## Specific visual customization
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>
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.
## Custom schemes
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.
### 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](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.

Loading…
Cancel
Save