Custom CSS and JavaScript Loading

MichaelRFox commented 1 month ago

Currently, clean-jsdoc-theme loads custom CSS and JavaScript files near the beginning of the <head> section of index.js. Since custom CSS files are loaded before clean-jsdoc-theme.min.css, conflicting styles in clean-jsdoc-theme.min.css override those in a custom CSS file.

In my use case I have loaded an octocat svg file to customize my menu link to my GitHub page. In my custom CSS file I use the svg as a mask-image with a background-color of currentColor to accommodate theme toggling, However, the .nav-bar-item:hover background style from clean-jsdoc-theme.min.css overrides my custom hover style. I managed a work around my using !important, but this is admittedly clumsy.

Here is a portion of my jsdocConfig.json:

"template": "node_modules/clean-jsdoc-theme",
"theme_opts": {
    "default_theme": "dark",
    "static_dir": ["./static"],
    "favicon": "./static/favicon.ico",
    "homepageTitle": "Home",
    "title": "fxTooltip",
    "includeFilesListInHomepage": true,
    "include_css": ["./static/docs.css"],
    "include_js": ["./static/docs.js"],
    "displayModuleHeader": true,
    "sort": false,
    "search": true,
    "menu": [
        {
            "title": "<span class = 'hiddenText'>Gihub</span>",
            "link": "https://github.com/MichaelRFox/fxToolTip.js/",
            "target": "_blank",
            "class": "github linkItems",
            "id": "repository"                
        },
        {
            "title": "<span class = 'hiddenText'>NPM</span>",
            "link": "https://www.npmjs.com/package/fx.tooltip.js/",
            "target": "_blank",
            "class": "npm linkItems",
            "id": "npm"
        }
    ]
}

And here is my custom CSS:

.linkItems { 
    mask-size: contain;
    webkit-mask-size: contain;
    mask-repeat: no-repeat;
    webkit-mask-repeat: no-repeat;
    mask-position: center;
    webkit-mask-position: center;
    margin: 0 0.5em 0 0.5em;
    background-color: currentColor;
}

.linkItems a:active {
    background-color: currentColor im !important;    
}

.linkItems:hover {
    color: currentColor;
    background-color: #ababab !important;
    cursor: pointer;
}

.github {
    width: 2em;
    mask-image: url(static/github-mark.svg);
    webkit-mask-image: url(static/github-mark.svg);
}

.npm {
    width: 3em;
    mask-image: url(static/Npm-logo.svg);
    webkit-mask-image: url(static/Npm-logo.svg);
}

.hiddenText {
    visibility: hidden;
}

In my second use case I would like to add a tooltip to my menu items to mirror the right-menu-items by including the following Javascript:

tippy('.github', {
    content: 'Github repo',
    delay: 500
})

tippy('.npm', {
    content: 'NPM repo',
    delay: 500
})

However, since my custom JavaScript is loaded before tippy.js it can't access it. I haven't yet figured out a workaround for this yet.

I think that loading custom CSS and JavaScript files at the end of the <head> section would be an easy solution. Anyone competent enough to create custom CSS and JavaScript for their docs should be able to prevent the unintended consequences of reusing variables, functions, and selectors from the index.html file, etc. (perhaps a disclaimer in your documentation).

github-actions[bot] commented 1 month ago

Wonderful, you have created your first issue for clean-jsdoc-theme. Someone will talk to you soon!

MichaelRFox commented 1 month ago

So I figured out a workaround for the JavaScript issue (rather embarrassed about this). It was simply to enclose the code in a window.onload event. Still seems a bit kludgy, but seems to work.

window.onload = function (event) {
    tippy('.github', {
        content: 'Github repo',
        placement: 'top',
        delay: 500
    })

    tippy('.npm', {
        content: 'NPM repo',
        placement: 'top',
        delay: 500
    })    
}

ankitskvmdam commented 1 month ago

Hi @MichaelRFox! I am glad that you figured out a workaround for this.

To fix the css I would recommend you to increase the specificity. So to updated the hover colour of navbar item you could do something as follows:


.navbar-container .navbar-item:hover {
 /* My custom css. */
}

Alternatively, feel free to suggest some ideas.

ankitskvmdam / clean-jsdoc-theme

Custom CSS and JavaScript Loading #299