From d13f34b84e1fc6163505034950eeeaced2e00c69 Mon Sep 17 00:00:00 2001 From: oleibman <10341515+oleibman@users.noreply.github.com> Date: Sat, 19 Sep 2026 19:57:45 -0700 Subject: [PATCH] More Documentation Tweaks Special handling in javascript and css for any image whose `alt` value starts with `Logo`, rather than targeting one specific value. Remove 2 no-longer relevant statements from `extra.css`. Add css member for `mkdocs` theme. Add link to PhpSpreadsheet site to the bottom line of each page for `readthedocs` and `mkdocs` themes. In theory, these links should already exist, and they do locally, but not, for some reason, when run on readthedocs.io. This link is different from the `Edit on Github` link at the top, which is a kind of interesting feature. Add a bookmarklet on the main page for toggling images to dark mode, which would probably be the preference for users employing dark mode. Images are usually left unchanged in dark mode, but almost all our images are screenshots, and dark mode might be appropriate for them. --- docs/extra/darkimages.js | 24 ++++++++++++ docs/extra/darkmode.css | 6 +-- .../extra/{lightmode.js => darkmodetoggle.js} | 0 docs/extra/extra.css | 3 -- .../{invertlight.js => lightmodetoggle.js} | 6 ++- docs/extra/mkdocs.css | 1 + docs/extra/sitelink.js | 5 +++ docs/extra/sitelink.mkdocs2.js | 10 +++++ docs/extra/sitelink2.js | 5 +++ docs/extra/tablestripes.css | 1 + docs/index.md | 37 +++++++++++++++---- docs/topics/reading-and-writing-to-file.md | 2 +- mkdocs.material.yml | 1 + mkdocs.materialx.yml | 1 + mkdocs.mkdocs.yml | 6 ++- mkdocs.readthedocs.yml | 1 + mkdocs.yml | 3 +- properdocs.yml | 1 + 18 files changed, 95 insertions(+), 18 deletions(-) create mode 100644 docs/extra/darkimages.js rename docs/extra/{lightmode.js => darkmodetoggle.js} (100%) rename docs/extra/{invertlight.js => lightmodetoggle.js} (70%) create mode 100644 docs/extra/mkdocs.css create mode 100644 docs/extra/sitelink.js create mode 100644 docs/extra/sitelink.mkdocs2.js create mode 100644 docs/extra/sitelink2.js diff --git a/docs/extra/darkimages.js b/docs/extra/darkimages.js new file mode 100644 index 000000000..e46b1dcd9 --- /dev/null +++ b/docs/extra/darkimages.js @@ -0,0 +1,24 @@ +/* the following 2 attempts didn't always work +{ + const images = document.querySelectorAll('img'); + images.forEach(img => {img.style.filter = img.style.filter ? '' : 'invert(100%) hue-rotate(180deg)';}); +} + +{ + const images = document.querySelectorAll('img'); + images.forEach(img => {img.style.filter = img.style.filter ? '' : 'hue-rotate(180deg)';}); +} +*/ + +/* this appears to work all the time */ +{ + const images = document.querySelectorAll('img'); + images.forEach(img => { + const temp = img.style.filter; + if (temp == '' || temp == 'none') { + img.style.filter = 'invert(1) hue-rotate(180deg)'; + } else { + img.style.filter = 'none'; + } + }); +} diff --git a/docs/extra/darkmode.css b/docs/extra/darkmode.css index 4b809888c..c21b76169 100644 --- a/docs/extra/darkmode.css +++ b/docs/extra/darkmode.css @@ -6,12 +6,12 @@ Retrieved 2026-08-24, License - CC BY-SA 4.0 @media (prefers-color-scheme: dark) { html { - filter: invert(100%); + filter: invert(100%) hue-rotate(180deg); } /* double apply invert filter to cancel out effect on images */ - img:not([alt="Logo"]) { - filter: invert(100%); + img:not([alt^="Logo"]) { + filter: invert(100%) hue-rotate(180deg); } /* Dark mode (slate scheme) alternating rows */ diff --git a/docs/extra/lightmode.js b/docs/extra/darkmodetoggle.js similarity index 100% rename from docs/extra/lightmode.js rename to docs/extra/darkmodetoggle.js diff --git a/docs/extra/extra.css b/docs/extra/extra.css index e5374fc7e..6ab8bb566 100644 --- a/docs/extra/extra.css +++ b/docs/extra/extra.css @@ -22,6 +22,3 @@ table.features-cross-reference { .wehavedarktoggle {display: block;} .wedonthavedarktoggle {display: none;} - -[data-bs-theme="dark"] img[alt="Logo"] {filter: invert(100%)} -[data-md-color-scheme="slate"] img[alt="Logo"] {filter: invert(100%)} diff --git a/docs/extra/invertlight.js b/docs/extra/lightmodetoggle.js similarity index 70% rename from docs/extra/invertlight.js rename to docs/extra/lightmodetoggle.js index 18339b051..f9c4a0ca6 100644 --- a/docs/extra/invertlight.js +++ b/docs/extra/lightmodetoggle.js @@ -1,7 +1,11 @@ (function(){ document.documentElement.style.filter = document.documentElement.style.filter ? '' : 'invert(100%) hue-rotate(180deg)'; const images = document.querySelectorAll('img'); - images.forEach(img => { if (img.alt != 'Logo') img.style.filter = 'invert(100%) hue-rotate(180deg)';}); + images.forEach(img => { + if (!img.alt.startsWith('Logo')) { + img.style.filter = img.style.filter ? '' : 'invert(100%) hue-rotate(180deg)'; + } + }); if (document.body.getAttribute('data-md-color-scheme') == 'slate') { document.body.setAttribute('data-md-color-scheme', 'default'); } else { diff --git a/docs/extra/mkdocs.css b/docs/extra/mkdocs.css new file mode 100644 index 000000000..d4124e9ff --- /dev/null +++ b/docs/extra/mkdocs.css @@ -0,0 +1 @@ +[data-bs-theme="dark"] [alt^="Logo"] {filter: invert(100%) hue-rotate(180deg);} \ No newline at end of file diff --git a/docs/extra/sitelink.js b/docs/extra/sitelink.js new file mode 100644 index 000000000..59f0cabac --- /dev/null +++ b/docs/extra/sitelink.js @@ -0,0 +1,5 @@ +document.addEventListener("DOMContentLoaded", function() { + document.querySelectorAll("li.wy-breadcrumbs-aside").forEach(function(obj) { + obj.innerHTML = "Visit PhpSpreadsheet" + obj.innerHTML; + }); +}); diff --git a/docs/extra/sitelink.mkdocs2.js b/docs/extra/sitelink.mkdocs2.js new file mode 100644 index 000000000..24712becf --- /dev/null +++ b/docs/extra/sitelink.mkdocs2.js @@ -0,0 +1,10 @@ +document.addEventListener("DOMContentLoaded", function() { + var done = false; + document.querySelectorAll("#toc-collapse ul").forEach(function(obj) { + const x = obj.innerHTML; + if (!done) { + obj.innerHTML = "
  • Visit PhpSpreadsheet
    • " + x; + done = true; + } + }); +}); diff --git a/docs/extra/sitelink2.js b/docs/extra/sitelink2.js new file mode 100644 index 000000000..9063329cf --- /dev/null +++ b/docs/extra/sitelink2.js @@ -0,0 +1,5 @@ +document.addEventListener("DOMContentLoaded", function() { + document.querySelectorAll("footer").forEach(function(obj) { + obj.innerHTML = obj.innerHTML.replace("uilt with", "uilt for PhpSpreadsheet with"); + }); +}); diff --git a/docs/extra/tablestripes.css b/docs/extra/tablestripes.css index e4eba453a..620c010b0 100644 --- a/docs/extra/tablestripes.css +++ b/docs/extra/tablestripes.css @@ -6,3 +6,4 @@ [data-md-color-scheme="slate"] table tbody tr:nth-child(2n) { background-color: #404040; } +[data-md-color-scheme="slate"] [alt^="Logo"] {filter: invert(100%) hue-rotate(180deg);} diff --git a/docs/index.md b/docs/index.md index 293dae588..893c84749 100644 --- a/docs/index.md +++ b/docs/index.md @@ -168,8 +168,10 @@ may defer to your system's settings. This particular theme does not come with a toggle to switch back and forth. If you want to switch and it is inconvenient for you to change the browser setting:

    +

    Toggles If Your Browser Setting Is Dark Mode

    + If your setting is dark mode, and your browser supports ES11, this -Dark/Light Toggle +DarkModeToggle can be used as a bookmarklet. It executes: ```javascript @@ -180,28 +182,49 @@ Array.from(document.styleSheets).forEach((sheet) => { }); ``` +

    Toggles If Your Browser Setting Is Light Mode

    + If your setting is light mode, and your browser supports ES6, this -Emulate Dark Mode -bookmarklet can be used to emulate dark mode, but just reload the page to restore light mode: +LightModeToggle +bookmarklet (changed 2026-09-18) can be used to toggle dark/light mode (or just reload the page to restore light mode): ```javascript (function(){ document.documentElement.style.filter = document.documentElement.style.filter ? '' : 'invert(100%) hue-rotate(180deg)'; const images = document.querySelectorAll('img'); images.forEach(img => { - if (img.alt != 'Logo') { + if (!img.alt.startsWith('Logo')) { img.style.filter = img.style.filter ? '' : 'invert(100%) hue-rotate(180deg)'; - } - }); + } + }); if (document.body.getAttribute('data-md-color-scheme') == 'slate') { document.body.setAttribute('data-md-color-scheme', 'default'); } else { document.body.setAttribute('data-md-color-scheme', 'slate'); } })(); - ``` +
    +

    Displaying Images in Dark Mode

    +Images are not normally adjusted for Dark/Light mode. +If you also want images to display in dark mode, try DarkImages3 as a bookmarklet. (You may have to execute it twice the first time on a page.) It executes: + +```javascript +{ + const images = document.querySelectorAll('img'); + images.forEach(img => { + const temp = img.style.filter; + if (temp == '' || temp == 'none') { + img.style.filter = 'invert(1) hue-rotate(180deg)'; + } else { + img.style.filter = 'none'; + } + }); +} +``` +
    + ## Credits diff --git a/docs/topics/reading-and-writing-to-file.md b/docs/topics/reading-and-writing-to-file.md index 604d8cc78..6e00b2cd7 100644 --- a/docs/topics/reading-and-writing-to-file.md +++ b/docs/topics/reading-and-writing-to-file.md @@ -832,7 +832,7 @@ images root. For example, instead of: You might want to see: ```html - + ``` You can use the following code to achieve this result: diff --git a/mkdocs.material.yml b/mkdocs.material.yml index 67682e18c..47da34bde 100644 --- a/mkdocs.material.yml +++ b/mkdocs.material.yml @@ -35,6 +35,7 @@ extra_css: # - extra/pygments.emacs.css - extra/pygments.default.light.css - extra/pygments.lightbulb.dark.css + - extra/zensical.topbar.css extra_javascript: - extra/extrajs.js markdown_extensions: diff --git a/mkdocs.materialx.yml b/mkdocs.materialx.yml index f5d3fc85d..429fbf31b 100644 --- a/mkdocs.materialx.yml +++ b/mkdocs.materialx.yml @@ -36,6 +36,7 @@ extra_css: # - extra/pygments.emacs.css - extra/pygments.default.light.css - extra/pygments.lightbulb.dark.css + - extra/zensical.topbar.css extra_javascript: - extra/extrajs.js markdown_extensions: diff --git a/mkdocs.mkdocs.yml b/mkdocs.mkdocs.yml index 683a5c54f..cc4d997a2 100644 --- a/mkdocs.mkdocs.yml +++ b/mkdocs.mkdocs.yml @@ -1,6 +1,6 @@ site_name: PhpSpreadsheet Documentation -#site_url: https://github.com/PHPOffice/phpspreadsheet -repo_url: https://github.com/PHPOffice/phpspreadsheet +site_url: https://github.com/PHPOffice/PhpSpreadsheet +repo_url: https://github.com/PHPOffice/PhpSpreadsheet #repo_name: PhpSpreadsheet #edit_uri: edit/master/docs/ @@ -11,9 +11,11 @@ theme: extra_css: - extra/extra.css - extra/copyclipboard.css + - extra/mkdocs.css extra_javascript: - extra/extrajs.js - extra/copyclipboard.js + - extra/sitelink2.js # Mkdocs theme does not honor green and red color for ✔ and ✖. # I am at a loss to explain why, or even how; no other theme has this problem. # These are used on features-cross-reference page. diff --git a/mkdocs.readthedocs.yml b/mkdocs.readthedocs.yml index eed518641..1bf5bb6de 100644 --- a/mkdocs.readthedocs.yml +++ b/mkdocs.readthedocs.yml @@ -14,5 +14,6 @@ extra_css: extra_javascript: - extra/extrajs.js - extra/copyclipboard.js + - extra/sitelink2.js markdown_extensions: - md_in_html diff --git a/mkdocs.yml b/mkdocs.yml index eed518641..a3eb512f6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ site_name: PhpSpreadsheet Documentation -#site_url: https://github.com/PHPOffice/phpspreadsheet +site_url: https://github.com/PHPOffice/PhpSpreadsheet/ repo_url: https://github.com/PHPOffice/phpspreadsheet #repo_name: PhpSpreadsheet #edit_uri: edit/master/docs/ @@ -14,5 +14,6 @@ extra_css: extra_javascript: - extra/extrajs.js - extra/copyclipboard.js + - extra/sitelink2.js markdown_extensions: - md_in_html diff --git a/properdocs.yml b/properdocs.yml index b2b5059fc..63187be9c 100644 --- a/properdocs.yml +++ b/properdocs.yml @@ -14,5 +14,6 @@ extra_css: extra_javascript: - extra/extrajs.js - extra/copyclipboard.js + - extra/sitelink2.js markdown_extensions: - md_in_html