Skip to content

fix: resolve multiple UI and configuration issues #280

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pekkah merged 2 commits into from
Aug 17, 2025
Merged

fix: resolve multiple UI and configuration issues #280

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7b3f5db
fix: resolve multiple UI and configuration issues
pekkah Aug 17, 2025
0c8ffd1
fix: address FOUC issue in theme handling
pekkah Aug 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 18 additions & 22 deletions src/DocsTool/Resources/default-tanka-docs-wip.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,11 @@
# Generated by: tanka-docs init
# This configuration uses HEAD (current working directory state) for faster development iteration

name: "{{PROJECT_NAME}} (WIP)"
description: "Development version of {{PROJECT_NAME}} documentation"

# Content sources - Use working directory for WIP builds
sources:
- source: git-branch
branch: HEAD # Uses current working directory state
path: docs/

# Output configuration
output_path: _build-wip/
build_path: _site-wip/

# UI configuration
ui_bundle: ui-bundle/

# Processing options
extensions:
- include
- xref
base_path: "/"
title: "{{PROJECT_NAME}} (WIP)"
index_page: xref://root@HEAD:index.md
output_path: "_build-wip"
build_path: "_site-wip"

# Homepage link configuration (optional)
homepage:
Expand All @@ -30,5 +15,16 @@ homepage:
target: "_blank"
enabled: false

# Development settings
base_path: ""
# Content sources - Use current working directory (HEAD) for WIP builds
branches:
HEAD:
input_path:
- docs
- ui-bundle

# Development typically doesn't need tags, but you can add them if needed:
#tags:
# v1.*:
# input_path:
# - docs
# - ui-bundle
47 changes: 24 additions & 23 deletions src/DocsTool/Resources/default-tanka-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,34 @@
# Tanka Docs Configuration (Production)
# Generated by: tanka-docs init

name: "{{PROJECT_NAME}}"
description: "Documentation for {{PROJECT_NAME}}"

# Content sources - Git branches/tags for stable builds
sources:
- source: git-branch
branch: "{{DEFAULT_BRANCH}}"
path: docs/

# Output configuration
output_path: _build/
build_path: _site/

# UI configuration
ui_bundle: ui-bundle/

# Processing options
extensions:
- include
- xref
base_path: "/"
title: "{{PROJECT_NAME}}"
index_page: xref://root@{{DEFAULT_BRANCH}}:index.md
output_path: "gh-pages"
build_path: "_build"

# Homepage link configuration (optional)
homepage:
url: ""
text: "Home"
target: "_blank"
enabled: false

# Development settings (override in tanka-docs-wip.yml for WIP builds)
base_path: ""

# Content sources - Git branches/tags for stable builds
branches:
{{DEFAULT_BRANCH}}:
input_path:
- docs
- ui-bundle

# Add tags configuration for versioned documentation
# Uncomment and customize as needed:
#tags:
# v1.*:
# input_path:
# - docs
# - ui-bundle
# v2.*:
# input_path:
# - docs
# - ui-bundle
30 changes: 2 additions & 28 deletions ui-bundle/article.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,34 +10,7 @@
<!-- Bootstrap 5 -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">

<!-- Color mode toggler -->
<script>
(() => {
'use strict'

const getStoredTheme = () => localStorage.getItem('theme')
const setStoredTheme = theme => localStorage.setItem('theme', theme)

const getPreferredTheme = () => {
const storedTheme = getStoredTheme()
if (storedTheme) {
return storedTheme
}

return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
}

const setTheme = theme => {
if (theme === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches) {
document.documentElement.setAttribute('data-bs-theme', 'dark')
} else {
document.documentElement.setAttribute('data-bs-theme', theme)
}
}

setTheme(getPreferredTheme())
})()
</script>
<!-- Color mode toggler - theme initialization moved to body script for better organization -->
Copy link

@gemini-code-assist gemini-code-assist bot Aug 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

While removing the duplicated theme-handling script from the <head> cleans up the code, it introduces a potential user experience issue: a "flash of unstyled content" (FOUC). The theme is now applied only after the DOM is fully loaded, which can cause a brief flash of the default theme before it switches to the user's preferred theme.

To prevent this, it's best practice to run a minimal, blocking script in the <head> to set the theme attribute on the <html> element as early as possible. Some duplication with the main script in the body is an acceptable trade-off for a better user experience.

I suggest re-introducing a small script here. This version is slightly more minimal than the original, as it omits the unused setStoredTheme function.

    <!-- Color mode toggler -->
    <script>
        // This minimal script runs early to prevent a "flash of unstyled content" (FOUC) by setting the theme before the page renders.
        (() => {
            'use strict';
            const getStoredTheme = () => localStorage.getItem('theme');
            const getPreferredTheme = () => {
                const storedTheme = getStoredTheme();
                if (storedTheme) {
                    return storedTheme;
                }
                return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
            };
            const setTheme = theme => {
                if (theme === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches) {
                    document.documentElement.setAttribute('data-bs-theme', 'dark');
                } else {
                    document.documentElement.setAttribute('data-bs-theme', theme);
                }
            };
            setTheme(getPreferredTheme());
        })()
    </script>


<!-- Noto Color Emoji font for cross-platform emoji support -->
<link href="https://fonts.googleapis.com/css2?family=Noto+Color+Emoji&display=swap" rel="stylesheet">
Expand Down Expand Up @@ -766,6 +739,7 @@
})

window.addEventListener('DOMContentLoaded', () => {
setTheme(getPreferredTheme())
showActiveTheme(getPreferredTheme())

document.querySelectorAll('[data-bs-theme-value]')
Expand Down
2 changes: 1 addition & 1 deletion ui-bundle/partials/NavigationItem.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
{{#if Children}}
<div class="d-flex justify-content-between align-items-center">
{{#link_to DisplayLink}}<a class="nav-link" href={{url}}>{{title}}</a>{{/link_to}}
<button class="btn btn-sm btn-link p-0" data-bs-toggle="collapse" data-bs-target="#nav-{{DisplayLink.Link.Xref.Path}}" aria-expanded="false" aria-controls="nav-{{DisplayLink.Link.Xref.Path}}" aria-label="Toggle submenu">
<button type="button" class="btn btn-sm btn-link p-0" data-bs-toggle="collapse" data-bs-target="#nav-{{DisplayLink.Link.Xref.Path}}" aria-expanded="false" aria-controls="nav-{{DisplayLink.Link.Xref.Path}}" aria-label="Toggle submenu">
<svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" fill="currentColor" class="bi bi-chevron-down" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/></svg>
</button>
</div>
Expand Down
Loading