Add a Zen-mode reading feature

[v20100v]

First, I wanted to thank you for your work in Blowfish. Thx!!!

Zen-mode = occupy full width available in browser

The idea is to enhance the reading experience in Blowfish theme, by optimizing the article text to occupy the full width available in the browser. Users have the option to activate this feature at their convenience through a straightforward button located in the article header.

To enable or disable Zen mode, image an implementation of a straightforward button. This button will be easily accessible in the header of the article, providing users with a seamless way to toggle this immersive reading experience on or off. Crucially, the implementation will ensure that user preferences persist as they navigate through different pages. This means if a user activates Zen mode on one page, it remains active when moving to another, creating a consistent and personalized reading experience.

So what do we want to do :

• Add a new toggle button in the header of the article, allowing users to activate or deactivate Zen mode with a simple click.
• Adjust the available width dynamically, ensuring the text takes up as much space as possible when Zen mode is activated.
• And keep user configuration.

A picture more than words

before-after-zen-mode.mp4

Implementation proposal

I did not create a fork to offer you this functionality... waiting for your opinion. But I have already coded it for my use (by override) which I share with you below.

Create a zen-mode button (partial layout)

Begin by establishing a dedicated space for the zen-mode button. In the ./layouts/partials/meta/ local folder, create a new file named zen-mode.html. This file will serve as the container for the zen-mode button’s layout and functionality.
Inside this newly created file, we define the structure of the button, and we load appropriate javascript with this instruction {{ $jsCode := resources.Get "js/zen-mode.js" }}. Notes that we added data-attributes (data-title-i18n-disable and data-title-i18n-enable) to store the button titles, depending on its state (activated or deactivated), in order to benefit of multi-languages support.

<!-- ./layouts/partials/meta/zen-mode.html` -->

{{ $jsCode := resources.Get "js/zen-mode.js" }}

<span class="mb-[2px]">
  <span id="zen-mode-button"
        class="text-lg hover:text-primary-500"
        title="{{ i18n "article.zen_mode_title.enable" }}"
        data-title-i18n-disable="{{ i18n "article.zen_mode_title.enable" }}"
        data-title-i18n-enable="{{ i18n "article.zen_mode_title.disable" }}">
    <span class="inline-block align-text-bottom">{{ partial "icon.html" "expand" }}</span>
  </span>
</span>

Put this zen-mode button into the article layout

This button will be placed at the head of each article, providing users with an easily accessible control for toggling Zen mode. To do it, we override the partials layout used for article in the Blowfish theme. Specifically, we override the file article-meta/basic.html, by creating the new file ./layouts/partials/article-meta/basic.html.

<!-- ./layouts/partials/article-meta/basic.html -->

(...)

{{ if and (eq $scope "single") (.Params.showEdit | default (.Site.Params.article.showEdit | default false)) }}
    {{ $meta.Add "partials" (slice (partial "meta/edit.html" .)) }}
{{ end }}

{{ if and (eq $scope "single") (.Params.showZenMode | default (.Site.Params.article.showZenMode | default false)) }}
    {{ $meta.Add "partials" (slice (partial "meta/zen-mode.html" .)) }}
{{ end }}

<div class="flex flex-row flex-wrap items-center">
(...)
</div>

This button is added only if the showZenMode option is activated in the Hugo configuration, specifically within the configuration file located at ./config/_default/params.toml. The conditional check ensures that the Zen-mode button template is included only when the showZenMode option is set to true in the Hugo configuration. Don’t forget to activate it.

## /config/_default/params.toml ##

[article]
  showZenMode = true
  # (...)

Update "single" layout

Add a new div with .zen-mode class into this layout.

<!-- ./layouts/_default/single.html -->

{{ define "main" }}
{{ .Scratch.Set "scope" "single" }}

<article>
    {{ if .Params.showHero | default (.Site.Params.article.showHero | default false) }}
        {{ $heroStyle := .Params.heroStyle }}
        {{ if not $heroStyle }}{{ $heroStyle = .Site.Params.article.heroStyle }}{{ end }}
        {{ $heroStyle := print "partials/hero/" $heroStyle ".html" }}
        {{ if templates.Exists $heroStyle }}
            {{ partial $heroStyle . }}
        {{ else }}
            {{ partial "partials/hero/basic.html" . }}
        {{ end }}
    {{ end }}

    <div class="zen-mode">

        <header id="single_header" class="mt-5 max-w-prose">
        {{ if .Params.showBreadcrumbs | default (.Site.Params.article.showBreadcrumbs | default false) }}
        {{ partial "breadcrumbs.html" . }}
        {{ end }}
        <h1 class="mt-0 text-4xl font-extrabold text-neutral-900 dark:text-neutral">
            {{ .Title | emojify }}
        </h1>
        <div class="mt-1 mb-6 text-base text-neutral-500 dark:text-neutral-400 print:hidden">
            {{ partial "article-meta/basic.html" (dict "context" . "scope" "single") }}
        </div>

        {{ $authorsData := .Site.Data.authors }}
        {{ $taxonomies := .Site.Taxonomies.authors }}
        {{ $baseURL := .Site.BaseURL }}
        {{ $taxonomyLink := 0 }}
        {{ $showAuthor := 0 }}

        {{ if .Params.showAuthor | default (.Site.Params.article.showAuthor | default true) }}
        {{ $showAuthor = 1 }}
        {{ partial "author.html" . }}
        {{ end }}

        {{ if not (strings.HasSuffix $baseURL "/") }}
        {{ $baseURL = delimit (slice $baseURL "/") "" }}
        {{ end }}

        {{ range $author := .Page.Params.authors }}
        {{ $authorData := index $authorsData $author }}
        {{- if $authorData -}}

        {{ range $taxonomyname, $taxonomy := $taxonomies }}
        {{ if (eq $taxonomyname $author) }}
        {{ $taxonomyLink = delimit (slice $baseURL "/authors/" $author) "" }}
        {{ end }}
        {{ end }}

        {{ partial "author-extra.html" (dict "context" . "data" $authorData "link" $taxonomyLink) }}
        {{- end -}}
        {{ end }}

        {{ if or $taxonomyLink $showAuthor }}
        <div class="mb-5"></div>
        {{ end }}

    </header>

        <section class="flex flex-col max-w-full mt-0 prose dark:prose-invert lg:flex-row">

            {{ if or (and (.Params.showTableOfContents | default (.Site.Params.article.showTableOfContents | default false)) (in
            .TableOfContents "<ul")) (.Site.Params.article.showRelatedPosts | default false) }} <div
                class="order-first sm:max-w-prose lg:ml-auto px-0 lg:order-last lg:max-w-xs ltr:lg:pl-8 rtl:lg:pr-8">
            <div class="toc ltr:pl-5 rtl:pr-5 print:hidden lg:sticky {{ if hasPrefix .Site.Params.header.layout "fixed" -}}
            lg:top-[140px]{{ else }}lg:top-10{{ end }}">

            {{ if and (.Params.showTableOfContents | default (.Site.Params.article.showTableOfContents | default false)) (in
            .TableOfContents "<ul") }} {{ partial "toc.html" . }} {{ end }} {{ if .Site.Params.article.showRelatedPosts |
            default false }} sd {{ end }} </div>
            </div>
            {{ end }}

            <div class="min-w-0 min-h-0 max-w-fit">

                {{ partial "series.html" . }}

                <div class="max-w-fit mb-20">
                    {{ .Content | emojify }}
                </div>

                {{ partial "series-closed.html" . }}
                {{ partial "sharing-links.html" . }}
                {{ partial "related.html" . }}
            </div>

            <script>
                var oid = "views_{{ .File.Path }}"
                var oid_likes = "likes_{{ .File.Path }}"
            </script>
            {{ $jsPage := resources.Get "js/page.js" }}
            {{ $jsPage = $jsPage | resources.Minify | resources.Fingerprint "sha512" }}
            <script type="text/javascript" src="{{ $jsPage.RelPermalink }}" integrity="{{ $jsPage.Data.Integrity }}"></script>
        </section>
    </div>

    <footer class="pt-8 max-w-prose print:hidden">

        {{ partial "article-pagination.html" . }}
        {{ if .Params.showComments | default (.Site.Params.article.showComments | default false) }}
        {{ if templates.Exists "partials/comments.html" }}
        <div class="pt-3">
            <hr class="border-dotted border-neutral-300 dark:border-neutral-600" />
            <div class="pt-3">
                {{ partial "comments.html" . }}
            </div>
        </div>
        {{ else }}
        {{ warnf "[BLOWFISH] Comments are enabled for %s but no comments partial exists." .File.Path }}
        {{ end }}
        {{ end }}
    </footer>
</article>
{{ end }}

Addding customs icons

Placing these below SVG icon, edit.svg and expand.svg, into the dedicated ./assets/icons folder.

• edit.svg : This edit icon bellow override the one used in the base theme.

  <svg xmlns="http://www.w3.org/2000/svg" height="1em" viewBox="0 0 512 512"><path fill="currentColor" d="M441 58.9L453.1 71c9.4 9.4 9.4 24.6 0 33.9L424 134.1 377.9 88 407 58.9c9.4-9.4 24.6-9.4 33.9 0zM209.8 256.2L344 121.9 390.1 168 255.8 302.2c-2.9 2.9-6.5 5-10.4 6.1l-58.5 16.7 16.7-58.5c1.1-3.9 3.2-7.5 6.1-10.4zM373.1 25L175.8 222.2c-8.7 8.7-15 19.4-18.3 31.1l-28.6 100c-2.4 8.4-.1 17.4 6.1 23.6s15.2 8.5 23.6 6.1l100-28.6c11.8-3.4 22.5-9.7 31.1-18.3L487 138.9c28.1-28.1 28.1-73.7 0-101.8L474.9 25C446.8-3.1 401.2-3.1 373.1 25zM88 64C39.4 64 0 103.4 0 152V424c0 48.6 39.4 88 88 88H360c48.6 0 88-39.4 88-88V312c0-13.3-10.7-24-24-24s-24 10.7-24 24V424c0 22.1-17.9 40-40 40H88c-22.1 0-40-17.9-40-40V152c0-22.1 17.9-40 40-40H200c13.3 0 24-10.7 24-24s-10.7-24-24-24H88z"/></svg>
  

• expand.svg : A new addition

  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 50" width="50px" height="50px"><path fill="currentColor" d="M 12.980469 4 C 9.1204688 4 5.9804688 7.14 5.9804688 11 L 6 26 L 9.9804688 26 L 9.9804688 11 C 9.9804688 9.35 11.320469 8 12.980469 8 L 40.019531 8 C 41.679531 8 43.019531 9.35 43.019531 11 L 43.019531 39 C 43.019531 40.65 41.679531 42 40.019531 42 L 29 42 C 29 43.54 28.420938 44.94 27.460938 46 L 40.019531 46 C 43.879531 46 47.019531 42.86 47.019531 39 L 47.019531 11 C 47.019531 7.14 43.879531 4 40.019531 4 L 12.980469 4 z M 7 28 C 4.794 28 3 29.794 3 32 L 3 42 C 3 44.206 4.794 46 7 46 L 23 46 C 25.206 46 27 44.206 27 42 L 27 32 C 27 29.794 25.206 28 23 28 L 7 28 z M 7 32 L 23 32 L 23.001953 42 L 7 42 L 7 32 z"/></svg>
  

Adding CSS styles

Put this CSS style into the folder ./assets/css/custom.css.

The CSS class .zen-mode-enable ensures article occupy the full viewport width, have a maximum width of 1600px, and include padding for readability.

/** ./assets/css/custom.css **/

.zen-mode {
    position: relative;
}

.zen-mode-enable {
    left: calc(max(-50vw, -800px) + 50%);
    width: 100vw;
    max-width: 1600px;
    padding-left: 30px;
    padding-right: 30px;
}

#zen-mode-button {
    cursor:pointer
}

Adding internationalization (i18n)

In the Blowfish theme, default translations can be overridden by creating a custom file in the ./i18n/ directory. So, to customize title attributes for the Zen-mode button, create a custom language definition file for each language you want to support.

Example languages definitions for zen-mode button

## ./i18n/en.yaml

global:
  language: "🇬🇧"

article:
  zen_mode_title:
    enable: "Enable zen mode"
    disable: "Disable zen mode"

By storing i18n texts in data attributes within the HTML, you ensure dynamic content updates based on the user’s language preference. JavaScript is utilized to fetch these i18n values dynamically, allowing for real-time updates to the Zen-mode button title attribute.

To handle i18n for the Zen-mode button title attribute, we store the texts in HTML data attributes within the partial layout.

data-title-i18n-disable="{{ i18n "article.zen_mode_title.disable" }}"
data-title-i18n-enable="{{ i18n "article.zen_mode_title.enable" }}"

Then these data attributes can be then fetched in JavaScript, like this.

let titleDisable = zendModeButton.getAttribute('data-title-i18n-disable');
let titleEnable = zendModeButton.getAttribute('data-title-i18n-enable');

Adding Javascript

Create the new JavaScript file zen-mode.js into ./assets/js/ folder. It will be responsible for managing the click event and defining the behavior of the Zen mode button.

/** ./assets/js/zen-mode.js **/

function _toogleZenMode(zendModeButton) {
    const divZenMode = document.querySelector('.zen-mode');
    if(divZenMode !== null && divZenMode !== undefined) {
        divZenMode.classList.toggle('zen-mode-enable');
    }

    // Read i18n title from data-attributes
    const titleI18nDisable = zendModeButton.getAttribute('data-title-i18n-disable');
    const titleI18nEnable = zendModeButton.getAttribute('data-title-i18n-enable');

    // Persist configuration
    if (divZenMode.classList.contains('zen-mode-enable')) {
        localStorage.setItem('blowfish-zen-mode-enabled', 'true');
        zendModeButton.setAttribute('title', titleI18nEnable);
        divZenMode.scrollIntoView();
    } else {
        localStorage.setItem('blowfish-zen-mode-enabled', 'false');
        zendModeButton.setAttribute('title', titleI18nDisable);
        document.querySelector('body').scrollIntoView();
    }
}

function _registerZendModeButtonClick(zendModeButton) {
    zendModeButton.addEventListener('click', function (event) {
        console.debug('[DEBUG] Click captured', event);
        event.preventDefault();

        // Toggle zen-mode
        _toogleZenMode(zendModeButton);
    });
}

(function init() {
    window.addEventListener("DOMContentLoaded", (event) => {
        console.debug('[DEBUG] Zen-mode feature enable');

        // Register click on 'zen-mode-button' node element
        const zendModeButton = document.getElementById('zen-mode-button');
        if(zendModeButton !== null && zendModeButton !== undefined) {
            _registerZendModeButtonClick(zendModeButton);
        }

        // Initialize localstorage option 'blowfish-zen-mode-enabled' to false, if it does not exist, otherwise enable it.
        if (localStorage.getItem('blowfish-zen-mode-enabled') === null) {
            localStorage.setItem('blowfish-zen-mode-enabled', 'false');
        } else if (localStorage.getItem('blowfish-zen-mode-enabled') === 'true') {
            _toogleZenMode(zendModeButton)
        }
    });
})();

Few remarks about its javascript :

• The click event on the Zen-mode button is registered using the addEventListener. It waits for the DOM to be completely loaded, by utilizing the DOMContentLoaded event.

• Local storage is employed to maintain user configuration across web navigation. The option blowfish-zen-mode-enabled is initially set to false, and it is updated each time the user clicks the button. Upon page load, the script checks if this option is set to true and, if so, calls the callback function _toogleZenMode to activate the Zen mode.

---

If you're interested, I can create a PR for this (less ugly than doing custom override)... if i found some time.

Cordialy,
2o1oo

[nunocoracao]

Hello @v20100v thanks for the suggestion and all the hard work.
I would like to first discuss what you are trying to achieve with the Zen-mode. I like the idea of a "zen-mode" but I think the focus shouldn't be on the width of the content - aka it's harder to read if your eyes need to move from one end to the other of the screen. Having said this I think there might be an opportunity to clean up the site when a user presses that button and focus only on the reading experience e.g. making the background single color, removing background images, hiding the TOC, etc. We could leverage some of the work here for that.

Let me know your thoughts and what you think about my comment on the width change specifically. I think there is something awesome here and I am happy to open a branch to collab with you on it.

p.s. sorry if the reply took some time have been busy

[v20100v]

Hello @nunocoracao

To continue the discussion.

I would like to first discuss what you are trying to achieve with the Zen-mode. I like the idea of a "zen-mode" but I think the focus shouldn't be on the width of the content - aka it's harder to read if your eyes need to move from one end to the other of the screen.

You are right about the use of width, the reading experience is not the most pleasant if the width of the screen is all used. I came to look for an improved reading experience, realizing that reading blocks of code requires constantly scrolling to the right to read the code. The default center column is too small. Hence the idea of this Zen-mode.

---

Having said this I think there might be an opportunity to clean up the site when a user presses that button and focus only on the reading experience e.g. making the background single color, removing background images, hiding the TOC, etc.

I really like your ideas for simplifying the display to concentrate on reading, in particular by hiding the table of contents. I think the line of thought should be as follows : Zen-mode is to simplify the user interface.

By hiding the TOC, reading is already much more pleasant =>

The Zen mode toggle button should always be visible on the screen, and thus prevent the user from having to constantly scroll down the page to find it, as was done for the top scroll button at the bottom of the page.

---

We could leverage some of the work here for that.

This is why I share this code ^^.

---

Let me know your thoughts and what you think about my comment on the width change specifically. I think there is something awesome here and I am happy to open a branch to collab with you on it.

Here we go !!!

---

p.s. sorry if the reply took some time have been busy

Don't worry, I imagine it's a complementary project to your professional activity. We all experience the same thing, frequently entering space-time gaps ^^.

[RenaudDenis]

It would actually be nice to be able to be able to specify the default value of the zen mode (enabled or disabled by default)