diff --git a/.prettierignore b/.prettierignore index 41fbef8..5dc073f 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,8 +1,9 @@ package.json package-lock.json _site -assets/css/dark-mode-preview.scss -assets/css/just-the-docs.scss +assets/css/just-the-docs-default.scss +assets/css/just-the-docs-light.scss +assets/css/just-the-docs-dark.scss assets/js/vendor/lunr.min.js assets/js/search-data.json assets/js/just-the-docs.js diff --git a/.stylelintrc.json b/.stylelintrc.json index a14d920..329ca34 100644 --- a/.stylelintrc.json +++ b/.stylelintrc.json @@ -1,7 +1,8 @@ { "ignoreFiles": [ - "assets/css/just-the-docs.scss", - "assets/css/dark-mode-preview.scss", + "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"], diff --git a/_config.yml b/_config.yml index 92ab71e..0f6cac8 100644 --- a/_config.yml +++ b/_config.yml @@ -42,15 +42,28 @@ aux_links: nav_sort: case_insensitive # default, equivalent to nil # nav_sort: case_sensitive # Capital letters sorted before lowercase -# Footer content appears at the bottom of every page's main content +# Footer content +# appears at the bottom of every page's main content footer_content: "Copyright © 2017-2019 Patrick Marsceill. Distributed by an MIT license." -# Color scheme currently only supports "dark" or nil (default) +# 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 + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true # show or hide edit this page link +gh_edit_link_text: "Edit this page on GitHub." +gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo +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", "light"/nil (default), or a custom scheme that you define color_scheme: nil # Google Analytics Tracking (optional) # e.g, UA-1234567-89 ga_tracking: UA-2709176-10 +ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default) plugins: - jekyll-seo-tag diff --git a/_includes/css/custom.scss.liquid b/_includes/css/custom.scss.liquid new file mode 100644 index 0000000..2ad1576 --- /dev/null +++ b/_includes/css/custom.scss.liquid @@ -0,0 +1 @@ +@import "./custom/custom"; diff --git a/_includes/css/just-the-docs.scss.liquid b/_includes/css/just-the-docs.scss.liquid new file mode 100644 index 0000000..495cd6d --- /dev/null +++ b/_includes/css/just-the-docs.scss.liquid @@ -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 %} diff --git a/_includes/head.html b/_includes/head.html index eae6a5e..4f22497 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -2,17 +2,17 @@ - {% if site.plugins.jekyll-seo == nil %} + {% unless site.plugins contains "jekyll-seo-tag" %} {{ page.title }} - {{ site.title }} {% if page.description %} {% endif %} - {% endif %} + {% endunless %} - + {% if site.ga_tracking != nil %} @@ -21,7 +21,7 @@ function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); - gtag('config', "{{ site.ga_tracking }}"); + gtag('config', '{{ site.ga_tracking }}'{% unless site.ga_tracking_anonymize_ip == nil %}, { 'anonymize_ip': true }{% endunless %}); {% endif %} diff --git a/_includes/nav.html b/_includes/nav.html index ec6c786..6858dec 100644 --- a/_includes/nav.html +++ b/_includes/nav.html @@ -22,6 +22,7 @@ {%- assign children_list = pages_list | where: "parent", node.title -%} {%- endif -%} + {%- endunless -%} {%- endfor -%} {%- endif -%} diff --git a/_layouts/default.html b/_layouts/default.html index 1aa6ae1..d7ebc17 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -85,10 +85,29 @@ layout: table_wrappers {% endif %} - {% if site.footer_content != nil %} + {% if site.footer_content != nil or site.show_last_edit_time or site.show_gh_edit_link %}
{% endif %} diff --git a/_layouts/table_wrappers.html b/_layouts/table_wrappers.html index cc6187a..3f8f226 100644 --- a/_layouts/table_wrappers.html +++ b/_layouts/table_wrappers.html @@ -4,4 +4,4 @@ layout: vendor/compress {% assign content_ = content | replace: '', '' %} -{{ content_ }} \ No newline at end of file +{{ content_ }} diff --git a/_sass/color_schemes/light.scss b/_sass/color_schemes/light.scss new file mode 100644 index 0000000..e69de29 diff --git a/_sass/custom/custom.scss b/_sass/custom/custom.scss index 9ac503b..e69de29 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/modules.scss b/_sass/modules.scss new file mode 100644 index 0000000..dc94a4b --- /dev/null +++ b/_sass/modules.scss @@ -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"; diff --git a/_sass/overrides.scss b/_sass/overrides.scss deleted file mode 100644 index 21e9527..0000000 --- a/_sass/overrides.scss +++ /dev/null @@ -1,3 +0,0 @@ -// -// Custom overrides from a user. -// diff --git a/assets/css/dark-mode-preview.scss b/assets/css/dark-mode-preview.scss deleted file mode 100644 index c524e81..0000000 --- a/assets/css/dark-mode-preview.scss +++ /dev/null @@ -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"; diff --git a/assets/css/just-the-docs-dark.scss b/assets/css/just-the-docs-dark.scss new file mode 100644 index 0000000..ac92fb1 --- /dev/null +++ b/assets/css/just-the-docs-dark.scss @@ -0,0 +1,3 @@ +--- +--- +{% include css/just-the-docs.scss.liquid color_scheme="dark" %} diff --git a/assets/css/just-the-docs-default.scss b/assets/css/just-the-docs-default.scss new file mode 100644 index 0000000..63fde26 --- /dev/null +++ b/assets/css/just-the-docs-default.scss @@ -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 %} diff --git a/assets/css/just-the-docs-light.scss b/assets/css/just-the-docs-light.scss new file mode 100644 index 0000000..ac69688 --- /dev/null +++ b/assets/css/just-the-docs-light.scss @@ -0,0 +1,3 @@ +--- +--- +{% include css/just-the-docs.scss.liquid color_scheme="light" %} diff --git a/assets/css/just-the-docs.scss b/assets/css/just-the-docs.scss deleted file mode 100644 index 199ad89..0000000 --- a/assets/css/just-the-docs.scss +++ /dev/null @@ -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"; diff --git a/assets/js/dark-mode-preview.js b/assets/js/dark-mode-preview.js deleted file mode 100644 index bb3169f..0000000 --- a/assets/js/dark-mode-preview.js +++ /dev/null @@ -1,25 +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/assets/js/just-the-docs.js b/assets/js/just-the-docs.js index 2f6cea0..2edf7f4 100644 --- a/assets/js/just-the-docs.js +++ b/assets/js/just-the-docs.js @@ -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(){ diff --git a/docs/configuration.md b/docs/configuration.md index eb43a08..f3a7a02 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,26 +55,56 @@ 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 ``` ## Footer content ```yaml -# Footer content appears at the bottom of every page's main content +# Footer content +# appears at the bottom of every page's main content footer_content: "Copyright © 2017-2019 Patrick Marsceill. Distributed by an MIT license." + +# 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 + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true # show or hide edit this page link +gh_edit_link_text: "Edit this page on GitHub." +gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo +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 ``` +- the "page last modified" data will only display if a page has a key called `last_modified_date`, formatted in some readable date format +- `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime) +- `gh_edit_repository` is the URL of the project's GitHub repository +- `gh_edit_branch` is the branch that the docs site is served from; defaults to `master` +- `gh_edit_view_mode` is `"tree"` by default, which brings the user to the github page; switch to `"edit"` to bring the user directly into editing mode + ## 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 ``` - + See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more information. @@ -85,4 +114,5 @@ See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more # Google Analytics Tracking (optional) # e.g, UA-1234567-89 ga_tracking: UA-5555555-55 +ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default) ``` diff --git a/docs/customization.md b/docs/customization.md index 883c94c..cbcd38c 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -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 ``` - + -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. -## Override styles +### Use a custom scheme -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. +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 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. diff --git a/just-the-docs.gemspec b/just-the-docs.gemspec index a426d4e..239b479 100644 --- a/just-the-docs.gemspec +++ b/just-the-docs.gemspec @@ -2,7 +2,7 @@ Gem::Specification.new do |spec| spec.name = "just-the-docs" - spec.version = "0.2.8" + spec.version = "0.2.9" spec.authors = ["Patrick Marsceill"] spec.email = ["patrick.marsceill@gmail.com"] @@ -13,7 +13,7 @@ Gem::Specification.new do |spec| spec.files = `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README)}i) } spec.executables << 'just-the-docs' - spec.add_runtime_dependency "bundler", "~> 2.1.4" + spec.add_development_dependency "bundler", "~> 2.1.4" spec.add_runtime_dependency "jekyll", ">= 3.8.5", "< 4.1.0" spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.0" spec.add_runtime_dependency "rake", ">= 12.3.1", "< 13.1.0" diff --git a/package-lock.json b/package-lock.json index 91ae4af..c878f4f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "just-the-docs", - "version": "0.2.8", + "version": "0.2.9", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index a9fd8e1..c2ab5ff 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "just-the-docs", - "version": "0.2.8", + "version": "0.2.9", "description": "A modern Jekyll theme for documentation", "repository": "pmarsceill/just-the-docs", "license": "MIT",