hdoc-tools 0.19.7 → 0.20.0

package/ui/js/doc.hornbill.js

@@ -1,659 +1,708 @@
-//-- DOM/URL EVENTS
-//-- THIS CONTROLS NAVIGATION
-//-- loaded in index.html
-
-var jqContentContainer = null;
-var jqDocumentHeader = null;
-var jqLeftNav = null;
-var global = { stateParams: {}, lastLayoutClass: "" };
-
-var docAppMethods = {
-    setSessionInfo: function (info) {
-        let self = this;
-        self.docApp.userSession = info;
-    },
-
-    showInlineDocumentList:function(ev)
-    {
-        if(ev)
-        {
-            ev.stopImmediatePropagation();
-            ev.preventDefault();
-        }
-
-        let self = this;
-        self.docApp.showInlineDocumentsMarkup = true;
-        self.$forceUpdate();
-    },
-    popupInlineDocument:function(ev,navSectionItem)
-    {
-        if(ev)
-        {
-            ev.stopImmediatePropagation();
-            ev.preventDefault();
-        }
-
-        $('#inlineModal').modal("show");
-        let self = this;
-        self.docApp.inlinePopupDocumentHref = navSectionItem.link;
-    },
-    switchViewTheme: function () {
-        if (ThemePreference) document.documentElement.classList.remove(ThemePreference);
-
-        if (ThemePreference === 'dark') {
-            ThemePreference = 'light';
-        }
-        else {
-            ThemePreference = 'dark';
-        }
-
-        localStorage.setItem('hdocbook-theme-appearance', ThemePreference);
-        document.documentElement.classList.add(ThemePreference);
-    },
-    renderNavigation: function () {
-        let self = this;
-        self.docApp.navSections = self.docApp.book.navigation.items; //-- show be an array of nav groups
-
-    },
-    toggleMobileMenu: function () {
-        let isOpen = $(".mobile-menu-btn").data("isopen");
-        if (isOpen) {
-            $(".DocSidebar").removeClass("open");
-        }
-        else {
-            $(".DocSidebar").addClass("open");
-        }
-        //-- store new mode
-        $(".mobile-menu-btn").data("isopen", !isOpen);
-    },
-    resetMobileMenu: function (ev) {
-        if (ev && ($(ev.srcElement).hasClass("mobile-menu-btn")[0] || $(ev.srcElement).closest(".mobile-menu-btn")[0])) {
-            //-- skp as have clikc no menu btn
-        }
-        else {
-            $(".mobile-menu-btn").data("isopen", false);
-            $(".DocSidebar").removeClass("open");
-        }
-    }
-
-};
-
-
-//--
-//-- user clicked back or forwards
-window.addEventListener('popstate', function (event) {
-    const loadUrl = new URL(event.target.location.href);
-    loadContentUrl(loadUrl.pathname + loadUrl.hash, {}, false, true);
-});
-
-
-//--- GLOBAL FUNCTIONS
-function removeTrailingSlash(str) {
-    return str.endsWith('/') ? str.slice(0, -1) : str;
-}
-function removeStartingSlash(str) {
-    return str.startsWith('/') ? str.slice(1, str.length) : str;
-
-    //if(linkRef.indexOf("/")===0)linkRef = linkRef.replace("/","");
-}
-
-function toSeoUrl(url) {
-    return url.toString()               // Convert to string
-        .normalize('NFD')               // Change diacritics
-        .replace(/[\u0300-\u036f]/g, '') // Remove illegal characters
-        .replace(/\s+/g, '-')            // Change whitespace to dashes
-        .toLowerCase()                  // Change to lowercase
-        .replace(/&/g, '-and-')          // Replace ampersand
-        .replace(/[^a-z0-9\-]/g, '')     // Remove anything that is not a letter, number or dash
-        .replace(/-+/g, '-')             // Remove duplicate dashes
-        .replace(/^-*/, '')              // Remove starting dashes
-        .replace(/-*$/, '');             // Remove trailing dashes
-}
-
-function listenForHrefClicks() {
-    //-- trap all link click events - we want to handle links so can cancel and load content ourselves
-    $("A").off("click").on("click", function (ev) {
-        let ele = this;
-        if (ele.href) {
-            const checkUrl = new URL(ele.href);
-
-            view.resetMobileMenu();
-
-            //-- clicking on a hash tag header link element - so jsut scroll to element
-            if (checkUrl.origin + "/" === siteBaseLocation) {
-                //-- if a url that is part of this doc site then handle loading content inline else let link do whatever (i.e. its an external link)                
-                ev.stopImmediatePropagation();
-                ev.preventDefault();
-
-                //-- do we need to scroll into view element on this page
-                if (checkUrl.hash && getAnchorFromHash(checkUrl.hash, "faq-toc-item")) {
-                    let eleAnc = getAnchorFromHash(checkUrl.hash, "faq-toc-item");
-                    if (eleAnc[0] && eleAnc[0].scrollIntoView) scrollIntoView[0].scrollIntoView();
-
-                    if (ele.href !== document.location.href) window.history.pushState(null, null, ele.href); //-- user has clicked a link so we want to add state to history so we can click back                
-                }
-                else {
-                    loadContentUrl(ele.getAttribute("href"), false, false);
-                }
-                return false;
-            }
-            else {
-                //-- if not part of this website then always open in new tab as considered an external site
-                ele.setAttribute("target", "_blank");
-            }
-        }
-    });
-
-}
-
-//-- based on content url highlight match navigation menu item
-//-- based on content url highlight match navigation menu item
-function highlightNavigationLinkFromUrl(matchLinkHref) {
-
-    matchLinkHref = removeStartingSlash(matchLinkHref).split("#")[0]; //-- remvoe # link
-    $('a.DocLink').removeClass("active");
-
-    let arrItems = document.querySelectorAll('a.DocLink');
-
-    for (let x = 0; x < arrItems.length; x++) {
-        let checkUrl = null;
-        try {
-            checkUrl = new URL(el.href);
-        }
-        catch (e) {
-            //hslDocLog.log("BAD navigation menu item found",el);
-        }
-
-        if (checkUrl) {
-            //hslDocLog.log(checkUrl.pathname,matchLinkHref)
-            let testCurrPath = removeStartingSlash(checkUrl.pathname);
-            if (testCurrPath === matchLinkHref) {
-                //-- exact match
-                $(el).addClass("active")
-                el.scrollIntoView();
-                return false;//break out
-            }
-            else if (testCurrPath.indexOf(matchLinkHref) === 0) {
-                //-- 
-                $(el).addClass("active")
-                el.scrollIntoView();
-                return false;//break out
-            }
-            else if (matchLinkHref.indexOf(removeStartingSlash(checkUrl.pathname) + "/") === 0) {
-                $(el).addClass("active");
-                el.scrollIntoView();
-                return false;//break out
-            }
-        }
-    }
-}
-
-function getAnchorFromHash(strHash, strHasClass) {
-    try {
-        let strSelector = toSeoUrl(strHash.replace("#", ""));
-        if (strHasClass) strSelector += "." + strHasClass;
-
-        let jqEle = $("#" + strSelector);
-        if (jqEle[0]) {
-            return jqEle;
-        }
-        else {
-            return null;
-        }
-    }
-    catch (e) {
-        hslDocLog.log("Get document anchor element by hash failed [" + strHash + "]", e);
-        return null;
-    }
-
-}
-
-
-//-- create items to stick in toc from current loaded content
-//-- searches for H2,H3
-function generateTableOfContentsFromDoc() {
-    let container = jqContentContainer[0];
-    if (container) {
-        const currUrl = new URL(document.location.href);
-        view.docApp.tableOfContents = [];
-        for (let i = 2; i <= 3; i++) {
-            let headers = container.getElementsByTagName("h" + i);
-            for (let j = 0; j < headers.length; j++) {
-                let jqCurrHeader = $(headers[j]);
-                //-- only process headers that do not have this class
-                if (!jqCurrHeader.hasClass("no-auto-anchor")) jqCurrHeader.addClass("faq-toc-item");
-            }
-        }
-
-        var headersTocItem = container.getElementsByClassName("faq-toc-item");
-        for (let k = 0; k < headersTocItem.length; k++) {
-            let item = headersTocItem[k];
-            let strLabel = $.trim(item.innerText);
-            if (strLabel) {
-                let seoSafeId = toSeoUrl(strLabel); //-- will use SEO to set in url so can scroll to element from url
-                let linkUrl = currUrl.pathname + "#" + seoSafeId;
-                item.id = seoSafeId;
-
-                view.docApp.tableOfContents.push({ ele: item, eleText: strLabel, tagName: item.tagName, href: linkUrl });
-
-                //-- add link icon to header (using seo id)
-                $(item).append("<a class='header-anchor'><i class='bi bi-link'></i></a>");
-                $(item).find("a").attr("href", linkUrl);
-
-            }
-        }
-    }
-}
-
-
-function loadContentUrl(linkRef, fromPageRefresh, fromPopState, fromBook = true) {
-    //-- clear table of contents
-    view.docApp.tableOfContents = [];
-    if (linkRef.indexOf(window.location.origin + "/") === 0) {
-        linkRef = linkRef.replace(window.location.origin + "/", "");
-    }
-
-    //-- remove trailing / if has one
-    linkRef = removeTrailingSlash(linkRef);
-    //-- remove starting / if link starts with it
-    linkRef = removeStartingSlash(linkRef);
-
-    //-- update url in browser
-    if (fromBook) setBrowserViewUrl(linkRef, {}, fromPageRefresh, fromPopState);
-    //-- destroy any existing content children and events properly
-    jqContentContainer.empty();
-    jqDocumentHeader.find(".document-title").empty();
-    
-    //-- for now just load whatever the href prop is (we can add actions to perform specific processing and then load content based on element atts etc)
-    let frontmatterData = {};
-    let booksLinkRef = linkRef;
-    if (fromBook) {
-        booksLinkRef = linkRef.includes('_books/') ? linkRef : "_books/" + linkRef;
-    }
-    fetch(booksLinkRef).then(response => {
-        if (response.headers.has("X-frontmatter")) {
-            frontmatterData = response.headers.get("X-frontmatter");
-            frontmatterData = JSON.parse(atob(frontmatterData));
-        }
-        return response.text();
-    }).then(html => {
-        jqContentContainer.html(html);
-
-        //-- remove previous layoutclass if have one
-        if (global.lastLayoutClass) {
-            $("#DocContent").removeClass(global.lastLayoutClass);
-            global.lastLayoutClass = "";
-        }
-
-        //-- if have layoutclass add it to content container - this is so we can specify table list view sizes etc
-        if (frontmatterData.layout) {
-            $("#DocContent").addClass(frontmatterData.layout);
-            global.lastLayoutClass = frontmatterData.layout;
-        }
-
-        //--generate toc for all layouts that have h2/h3 
-        view.docApp.keepTocLayout = (frontmatterData.layout == "article-no-toc");
-        if (!frontmatterData.layout || frontmatterData.layout === "article" || frontmatterData.layout === "article-toc") {
-            view.docApp.keepTocLayout = true;
-            generateTableOfContentsFromDoc();
-        }
-
-        //-- find any <tabs> and andd a bootstrap tab item strip
-        $("#DocContent").find('tabs').each((idx, el) => {
-            let tabClass = el.getAttribute("tabstyle");
-            let tabMarkup = "<ul class='nav nav-tabs'>";
-            //-- for each tab we need to create a tab link
-            $(el).find("tab").each((idx, aTab) => {
-
-                let activeClass = (idx === 0) ? " active" : "";
-                tabMarkup += `<li class='nav-item c-pointer' contentidx='${idx}'><span class='nav-link${activeClass}'>${aTab.getAttribute("name")}</span></li>`;
-
-                //-- hide the tab element if it is not the active one (first)
-                if (idx > 0) $(aTab).addClass("d-none");
-
-            });
-
-            tabMarkup += "</ul>";
-            //-- inject markup
-            $(el).prepend(tabMarkup).find(".nav.nav-tabs").addClass(tabClass);
-
-            //-- add event handler for switching tab items
-            $(el).find("li").off("click").on("click", function () {
-                let contentIdx = this.getAttribute('contentidx');
-                let tabsContainer = $(this).closest("tabs").eq(0);
-                let tabs = tabsContainer.find("tab");
-
-                //-- hide other tab content and show this tabs content
-                tabs.addClass("d-none");
-                tabs.eq(contentIdx - 0).removeClass("d-none");
-
-                //-- set clicked tab item to active
-                tabsContainer.find(".nav-link").removeClass("active");
-                $(this).find(".nav-link").addClass("active");
-
-            });
-        });
-
-        //-- do any code highlighting
-        if (hljs) {
-            document.querySelectorAll('pre code').forEach((el) => {
-                hljs.highlightBlock(el);
-            });
-        }
-        else {
-            hslDocLog.log("code highlighting js could not be loaded. code block highlighting will not be enabled");
-        }
-
-        //-- show copy button by any code blocks
-        var options = {
-            contentSelector: ".injected-document-content",
-            // Delay in ms used for `setTimeout` before badging is applied
-            // Use if you need to time highlighting and badge application
-            // since the badges need to be applied afterwards.
-            // 0 - direct execution (ie. you handle timing
-            loadDelay: 0,
-
-            // CSS class(es) used to render the copy icon.
-            copyIconClass: "bi bi-clipboard",
-            // CSS class(es) used to render the done icon.
-            checkIconClass: "bi bi-clipboard-check --htl-c-brand",
-
-            // intercept text copying - passed in text return text out
-            onBeforeCodeCopied: function (text) {
-                return text;
-            }
-        };
-
-        highlightJsBadge(options);
-
-        //-- get first H1 and put it into our header section header
-        let docHeader = jqContentContainer.find("H1").eq(0)
-        jqDocumentHeader.find(".document-title").append(docHeader);
-
-
-        setGitHubBookUrl(linkRef);
-        
-        //-- make sure selected link parents are set to .expand=true
-        if (expandNavParentSectionBySelectedLinkHref(linkRef)) {
-            view.updateCounter++;
-            view.$nextTick(function () {
-                //-- find any navigation links that match url and highlight
-                //                listenForHrefClicks();
-                highlightNavigationLinkFromUrl(linkRef);
-                
-                //-- scroll to element that match hash (if have one)
-                if (document.location.hash) {
-                    let gotoEle = getAnchorFromHash(document.location.hash);
-                    if (gotoEle) gotoEle[0].scrollIntoView();
-                }
-            });
-            view.$forceUpdate();
-        }
-        
-        listenForHrefClicks();
-    });
-}
-
-function setGitHubBookUrl(linkRef) {
-    let bookRef = linkRef.split(siteBaseLocation);
-    bookRef = (bookRef[1]) ? bookRef[1] : bookRef[0];
-    let bookId = bookRef.split("/")[0];
-    view.docApp.documentGithubUrl = "https://github.com/Hornbill-Docs/" + bookId + "/blob/main/" + bookRef + ".md";
-    //--https://github.com/Hornbill-Docs/hdoc-guide/blob/main/hdoc-guide/overview.md
-}
-
-function loadBookDefaultLink() {
-    $(".DocLink.link").first().click();
-}
-
-function findFirstClickableBookLink(findByLinkRef, currentNavSection) {
-    if (currentNavSection === undefined)
-        currentNavSection = view.docApp.navSections;
-
-
-    for (let x = 0; x < currentNavSection.length; x++) {
-        if (currentNavSection[x].items) {
-            let clickableItem = findFirstClickableBookLink(findByLinkRef, currentNavSection[x].items);
-            if (clickableItem) {
-                return clickableItem;
-            }
-        }
-        else if (currentNavSection[x].link) {
-            if (findByLinkRef) {
-                if (removeStartingSlash(removeTrailingSlash(currentNavSection[x].link)) == findByLinkRef) return currentNavSection[x].link;
-            }
-            else {
-                return currentNavSection[x].link;
-            }
-        }
-    }
-}
-
-function expandNavParentSectionBySelectedLinkHref(findByLinkRef, currentNavSection) {
-    findByLinkRef = findByLinkRef.split("#")[0];
-    if (currentNavSection === undefined) {
-        view.docApp.bookBreadCrumb = [];        //-- reset bread crumb
-        currentNavSection = view.docApp.navSections;
-    }
-
-    for (let x = 0; x < currentNavSection.length; x++) {
-        if (currentNavSection[x].items) {
-            let res = expandNavParentSectionBySelectedLinkHref(findByLinkRef, currentNavSection[x].items);
-            if (res) {
-                currentNavSection[x].expand = true;
-                view.docApp.bookBreadCrumb.unshift({ title: currentNavSection[x].text, link: currentNavSection[x].items[0].link });
-                return res;
-            }
-        }
-        else {
-            //-- check item to see if it matches url
-            if (removeStartingSlash(removeTrailingSlash(currentNavSection[x].link)) == findByLinkRef) {
-                return true;
-            }
-        }
-    }
-
-}
-
-
-function old_expandNavParentSectionBySelectedLinkHref(findByLinkRef, currentNavSection) {
-    findByLinkRef = findByLinkRef.split("#")[0];
-    if (currentNavSection === undefined)
-        currentNavSection = view.docApp.navSections;
-
-
-    for (let x = 0; x < currentNavSection.length; x++) {
-        if (currentNavSection[x].items) {
-            let res = expandNavParentSectionBySelectedLinkHref(findByLinkRef, currentNavSection[x].items);
-            if (res) {
-                currentNavSection[x].expand = true;
-                return res;
-            }
-        }
-        else {
-            //-- check item to see if it matches url
-            if (removeStartingSlash(removeTrailingSlash(currentNavSection[x].link)) == findByLinkRef) {
-                return true;
-            }
-        }
-    }
-
-}
-
-var lastUrlDynamicallySet = "";
-function setBrowserViewUrl(strHrefToLoad,viewData,fromPageRefresh,fromPopState)
-{
-   
-   let urlToSet = window.location.origin + "/" + strHrefToLoad;
-   const url = new URL(urlToSet);
-   
-   //-- remove any old params
-   for(let strKey in global.stateParams)
-   {
-       url.searchParams.delete(strKey);
-   }
-
-   //-- now set new data params in url
-   for(let strKey in viewData)
-   {
-       url.searchParams.set(strKey,viewData[strKey]);
-   }    
-
-   //-- store global params
-   global.stateParams = viewData;
-
-   if(!fromPageRefresh)
-   {
-    if(fromPopState)
-    {
-            //-- so user has clicked on a link - always add entry
-            window.history.pushState(null, null, url); //-- add entry
-    }
-    else
-    {
-            if(lastUrlDynamicallySet)
-            {
-                if(lastUrlDynamicallySet!==strHrefToLoad)
-                {
-                    window.history.pushState(null, null, url); //-- add entry
-                }
-                else
-                {
-                    window.history.replaceState(null, null, url); //-- user has refreshed page or jsut visited page
-                    
-                }
-            }
-            else
-            {
-                window.history.replaceState(null, null, url); //-- user has clicked a link so we want to add state to history so we can click back
-            }
-        }
-    }
-    lastUrlDynamicallySet=strHrefToLoad;
-}
-
-async function fetchContentFile(strFilePath) {
-    return await fetch(strFilePath).then(response => response.text()).then(fileContent => {
-        return fileContent;
-    });
-}
-
-async function fetchJsonFile(strFilePath) {
-    return await fetch(strFilePath).then(response => response.json()).then(jsonObject => {
-        return jsonObject;
-    });
-}
-
-
-//-- THE INIT APP CALLED FROM index.html
-//$(".document-body").attr("v-pre", "");
-
-var view = new Vue({
-    el: '#vDocDevApp',
-    data: { userSession: {}, updateCounter: 0, bookId: "", docApp: {error: "", inlinePopupDocumentHref:"",showInlineDocumentsMarkup:false, keepTocLayout: false, book: {}, navSections: [], inlineDocumentItems:[], tableOfContents: [], bookBreadCrumb: [] } },
-    methods: docAppMethods,
-    directives: {
-        somedirectivename: {
-            bind(el, binding, vnode) {
-                //-- do something when created on element
-            }
-        }
-    },
-    mounted: function () {
-
-    }
-});
-
-//-- repeatable conmponent for nav sections
-Vue.component('nav-section-component', {
-    props: ['asection'],
-    template: '#nav-section-template',
-    methods: {
-        toggleNavCollapse: function (navSection) {
-            navSection.expand = !navSection.expand;
-            this.$forceUpdate();
-        }
-    }
-});
-
-
-var hslDocLog = {
-    _entry: [],
-    log: function (strMessage, varData) {
-        if (varData !== undefined) console.log(strMessage, varData)
-        else console.log(strMessage);
-
-        this._entry.push({ msg: strMessage, data: varData })
-    },
-    dump: function () {
-        for (let x = 0; x < this._entry.length; x++) {
-            console.log(this._entry[x].msg, this._entry[x].data || null);
-        }
-    }
-}
-
-async function intialiseApp() {
-
-    // set theme switch
-    $(".theme-switch-checkbox").prop('checked', (ThemePreference === 'dark'));
-
-    jqDocumentHeader = $(".injected-document-content .document-header");
-    jqContentContainer = $(".injected-document-content .document-body");
-    //jqContentContainer = $(".injected-document-content");
-    jqLeftNav = $("#DocSidebarNav");
-
-    await fetchJsonFile("_books/library.json").then(function (data) {
-
-        // Get docbook library list
-        view.docApp.library = data;
-        view.docId = view.docApp.library.books[0].docId;
-
-    }).then(function () {
-        // Get hdocbook.json
-        fetchJsonFile("_books/" + view.docId + "/hdocbook.json").then(function (data) {
-            view.docApp.book = data;
-            view.bookId = data.docId;
-            view.docApp.title = data.title || "";
-            view.docApp.description = data.description || "";
-
-
-            view.docApp.inlineDocumentItems = [];
-            view.docApp.inlinePopupDocumentHref = "";
-            view.docApp.showInlineDocumentsMarkup = false;
-            view.docApp.hasInlinePopupDocuments =  (view.docApp.library.books[0].nav_inline && view.docApp.library.books[0].nav_inline.items && view.docApp.library.books[0].nav_inline.items.length)?true:false
-            if(view.docApp.hasInlinePopupDocuments)
-            {
-                view.docApp.inlineDocumentItems = view.docApp.library.books[0].nav_inline.items;
-                view.docApp.book.navigation.items.push(view.docApp.library.books[0].nav_inline);
-            }
-
-            //-- now render out the nav menu
-            view.renderNavigation();
-
-
-            setTimeout(function () {
-                listenForHrefClicks();
-
-                //-- check if url is not root - in which case we need to load content for url
-                var initialLoadContentHref = window.location.href.replace(window.location.origin + "/", "");
-                initialLoadContentHref = findFirstClickableBookLink(initialLoadContentHref);
-
-                if (initialLoadContentHref) {
-                    //-- find the link we are going to show and make sure parent/s are set to .expand=true
-                    loadContentUrl(initialLoadContentHref, true, false);
-
-
-                }
-                else {
-                    hslDocLog.log("initial first view link to load is not present");
-                }
-
-                $(".hb-hidden").removeClass("hb-hidden");
-
-            }, 200);
-        }).catch(function (data) {
-            view.docApp.error = data;
-            $(".hb-hidden").removeClass("hb-hidden");
-        });
-    });
-}
+//-- DOM/URL EVENTS
+//-- THIS CONTROLS NAVIGATION
+//-- loaded in index.html
+
+let jqContentContainer = null;
+let jqDocumentHeader = null;
+let jqLeftNav = null;
+const global = { stateParams: {}, lastLayoutClass: "" };
+
+const docAppMethods = {
+	setSessionInfo: function (info) {
+		this.docApp.userSession = info;
+	},
+
+	showInlineDocumentList: function (ev) {
+		if (ev) {
+			ev.stopImmediatePropagation();
+			ev.preventDefault();
+		}
+		this.docApp.showInlineDocumentsMarkup = true;
+		this.$forceUpdate();
+	},
+	popupInlineDocument: function (ev, navSectionItem) {
+		if (ev) {
+			ev.stopImmediatePropagation();
+			ev.preventDefault();
+		}
+
+		$("#inlineModal").modal("show");
+		this.docApp.inlinePopupDocumentHref = navSectionItem.link;
+	},
+	switchViewTheme: () => {
+		if (ThemePreference)
+			document.documentElement.classList.remove(ThemePreference);
+
+		if (ThemePreference === "dark") {
+			ThemePreference = "light";
+		} else {
+			ThemePreference = "dark";
+		}
+
+		localStorage.setItem("hdocbook-theme-appearance", ThemePreference);
+		document.documentElement.classList.add(ThemePreference);
+	},
+	renderNavigation: function () {
+		this.docApp.navSections = this.docApp.book.navigation.items; //-- show be an array of nav groups
+	},
+	toggleMobileMenu: () => {
+		const isOpen = $(".mobile-menu-btn").data("isopen");
+		if (isOpen) {
+			$(".DocSidebar").removeClass("open");
+		} else {
+			$(".DocSidebar").addClass("open");
+		}
+		//-- store new mode
+		$(".mobile-menu-btn").data("isopen", !isOpen);
+	},
+	resetMobileMenu: (ev) => {
+		if (
+			ev &&
+			($(ev.srcElement).hasClass("mobile-menu-btn")[0] ||
+				$(ev.srcElement).closest(".mobile-menu-btn")[0])
+		) {
+			//-- skp as have clikc no menu btn
+		} else {
+			$(".mobile-menu-btn").data("isopen", false);
+			$(".DocSidebar").removeClass("open");
+		}
+	},
+};
+
+//--
+//-- user clicked back or forwards
+window.addEventListener("popstate", (event) => {
+	const loadUrl = new URL(event.target.location.href);
+	loadContentUrl(loadUrl.pathname + loadUrl.hash, {}, false, true);
+});
+
+//--- GLOBAL FUNCTIONS
+function removeTrailingSlash(str) {
+	return str.endsWith("/") ? str.slice(0, -1) : str;
+}
+function removeStartingSlash(str) {
+	return str.startsWith("/") ? str.slice(1, str.length) : str;
+
+	//if(linkRef.indexOf("/")===0)linkRef = linkRef.replace("/","");
+}
+
+function toSeoUrl(url) {
+	return (
+		url
+			.toString() // Convert to string
+			.normalize("NFD") // Change diacritics
+			// biome-ignore lint/suspicious/noMisleadingCharacterClass: Ignoring this as it's required
+			.replace(/[\u0300-\u036f]/g, "") // Remove illegal characters
+			.replace(/\s+/g, "-") // Change whitespace to dashes
+			.toLowerCase() // Change to lowercase
+			.replace(/&/g, "-and-") // Replace ampersand
+			.replace(/[^a-z0-9\-]/g, "") // Remove anything that is not a letter, number or dash
+			.replace(/-+/g, "-") // Remove duplicate dashes
+			.replace(/^-*/, "") // Remove starting dashes
+			.replace(/-*$/, "")
+	); // Remove trailing dashes
+}
+
+function listenForHrefClicks() {
+	//-- trap all link click events - we want to handle links so can cancel and load content ourselves
+	$("A")
+		.off("click")
+		.on("click", function (ev) {
+			if (this.href) {
+				const checkUrl = new URL(this.href);
+
+				view.resetMobileMenu();
+
+				//-- clicking on a hash tag header link element - so jsut scroll to element
+				if (`${checkUrl.origin}/` === siteBaseLocation) {
+					//-- if a url that is part of this doc site then handle loading content inline else let link do whatever (i.e. its an external link)
+					ev.stopImmediatePropagation();
+					ev.preventDefault();
+
+					//-- do we need to scroll into view element on this page
+					if (
+						checkUrl.hash &&
+						getAnchorFromHash(checkUrl.hash, "faq-toc-item")
+					) {
+						const eleAnc = getAnchorFromHash(checkUrl.hash, "faq-toc-item");
+						if (eleAnc[0]?.scrollIntoView) eleAnc[0].scrollIntoView();
+
+						if (checkUrl.pathname === "/") {
+							//-- going to element on current page so just update current browser url with new #
+							const currUrl = new URL(document.location.href);
+							currUrl.hash = checkUrl.hash;
+							if (currUrl.href !== document.location.href)
+								window.history.pushState(null, null, currUrl); //-- user has clicked a link so we want to add state to history so we can click back
+						} else if (ele.href !== document.location.href) {
+							window.history.pushState(null, null, this.href); //-- user has clicked a link so we want to add state to history so we can click back
+						}
+					} else {
+						loadContentUrl(this.getAttribute("href"), false, false);
+					}
+					return false;
+				}
+				//-- if not part of this website then always open in new tab as considered an external site
+				this.setAttribute("target", "_blank");
+			}
+		});
+}
+
+//-- return t/f is the element is actually visible on the screen
+function elementIsOnVisibleScreen(oEle) {
+	const item = oEle.getBoundingClientRect();
+	return (
+		item.top >= 0 &&
+		item.left >= 0 &&
+		item.bottom <=
+			(window.innerHeight || document.documentElement.clientHeight) &&
+		item.right <= (window.innerWidth || document.documentElement.clientWidth)
+	);
+}
+
+//-- based on content url highlight match navigation menu item
+function highlightNavigationLinkFromUrl(matchLinkHref) {
+	const clean_matchLinkHref = removeStartingSlash(matchLinkHref).split("#")[0]; //-- remvoe # link
+	$("a.DocLink").removeClass("active");
+
+	const arrItems = document.querySelectorAll("a.DocLink");
+
+	for (let x = 0; x < arrItems.length; x++) {
+		const el = arrItems[x];
+		let checkUrl = null;
+		try {
+			checkUrl = new URL(el.href);
+		} catch (e) {
+			//hslDocLog.log("BAD navigation menu item found",el);
+		}
+
+		if (checkUrl) {
+			const testCurrPath = removeStartingSlash(checkUrl.pathname);
+			if (
+				testCurrPath === clean_matchLinkHref ||
+				testCurrPath.indexOf(clean_matchLinkHref) === 0 ||
+				clean_matchLinkHref.indexOf(
+					`${removeStartingSlash(checkUrl.pathname)}/`,
+				) === 0
+			) {
+				//-- exact match
+				$(el).addClass("active");
+				if (!elementIsOnVisibleScreen(el)) el.scrollIntoView();
+				return false; //break out
+			}
+		}
+	}
+}
+
+function getAnchorFromHash(strHash, strHasClass) {
+	try {
+		let strSelector = toSeoUrl(strHash.replace("#", ""));
+		if (strHasClass) strSelector += `.${strHasClass}`;
+
+		const jqEle = $(`#${strSelector}`);
+		if (jqEle[0]) {
+			return jqEle;
+		}
+		return null;
+	} catch (e) {
+		hslDocLog.log(`Get document anchor element by hash failed [${strHash}]`, e);
+		return null;
+	}
+}
+
+//-- create items to stick in toc from current loaded content
+//-- searches for H2,H3
+function generateTableOfContentsFromDoc() {
+	const container = jqContentContainer[0];
+	if (container) {
+		const currUrl = new URL(document.location.href);
+		view.docApp.tableOfContents = [];
+		for (let i = 2; i <= 3; i++) {
+			const headers = container.getElementsByTagName(`h${i}`);
+			for (let j = 0; j < headers.length; j++) {
+				const jqCurrHeader = $(headers[j]);
+				//-- only process headers that do not have this class
+				if (!jqCurrHeader.hasClass("no-auto-anchor"))
+					jqCurrHeader.addClass("faq-toc-item");
+			}
+		}
+
+		const headersTocItem = container.getElementsByClassName("faq-toc-item");
+		for (let k = 0; k < headersTocItem.length; k++) {
+			const item = headersTocItem[k];
+			const strLabel = $.trim(item.innerText);
+			if (strLabel) {
+				const seoSafeId = toSeoUrl(strLabel); //-- will use SEO to set in url so can scroll to element from url
+				const linkUrl = `${currUrl.pathname}#${seoSafeId}`;
+				item.id = seoSafeId;
+
+				view.docApp.tableOfContents.push({
+					ele: item,
+					eleText: strLabel,
+					tagName: item.tagName,
+					href: linkUrl,
+				});
+
+				//-- add link icon to header (using seo id)
+				$(item).append(
+					"<a class='header-anchor'><i class='bi bi-link'></i></a>",
+				);
+				$(item).find("a").attr("href", linkUrl);
+			}
+		}
+	}
+}
+
+function loadContentUrl(
+	linkRef,
+	fromPageRefresh,
+	fromPopState,
+	fromBook = true,
+) {
+	//-- clear table of contents
+	view.docApp.tableOfContents = [];
+	let clean_linkRef = linkRef;
+	if (clean_linkRef.indexOf(`${window.location.origin}/`) === 0) {
+		clean_linkRef = clean_linkRef.replace(`${window.location.origin}/`, "");
+	}
+
+	//-- remove trailing / if has one
+	clean_linkRef = removeTrailingSlash(clean_linkRef);
+	//-- remove starting / if link starts with it
+	clean_linkRef = removeStartingSlash(clean_linkRef);
+
+	//-- update url in browser
+	if (fromBook)
+		setBrowserViewUrl(clean_linkRef, {}, fromPageRefresh, fromPopState);
+	//-- destroy any existing content children and events properly
+	jqContentContainer.empty();
+	jqDocumentHeader.find(".document-title").empty();
+
+	//-- for now just load whatever the href prop is (we can add actions to perform specific processing and then load content based on element atts etc)
+	let frontmatterData = {};
+	let booksLinkRef = clean_linkRef;
+	if (fromBook) {
+		booksLinkRef = clean_linkRef.includes("_books/")
+			? clean_linkRef
+			: `_books/${clean_linkRef}`;
+	}
+	fetch(booksLinkRef)
+		.then((response) => {
+			if (response.headers.has("X-frontmatter")) {
+				frontmatterData = response.headers.get("X-frontmatter");
+				frontmatterData = JSON.parse(atob(frontmatterData));
+			}
+			return response.text();
+		})
+		.then((html) => {
+			jqContentContainer.html(html);
+
+			//-- remove previous layoutclass if have one
+			if (global.lastLayoutClass) {
+				$("#DocContent").removeClass(global.lastLayoutClass);
+				global.lastLayoutClass = "";
+			}
+
+			//-- if have layoutclass add it to content container - this is so we can specify table list view sizes etc
+			if (frontmatterData.layout) {
+				$("#DocContent").addClass(frontmatterData.layout);
+				global.lastLayoutClass = frontmatterData.layout;
+			}
+
+			//--generate toc for all layouts that have h2/h3
+			view.docApp.keepTocLayout = frontmatterData.layout === "article-no-toc";
+			if (
+				!frontmatterData.layout ||
+				frontmatterData.layout === "article" ||
+				frontmatterData.layout === "article-toc"
+			) {
+				view.docApp.keepTocLayout = true;
+				generateTableOfContentsFromDoc();
+			}
+
+			//-- find any <tabs> and andd a bootstrap tab item strip
+			$("#DocContent")
+				.find("tabs")
+				.each((idx, el) => {
+					const tabClass = el.getAttribute("tabstyle");
+					let tabMarkup = "<ul class='nav nav-tabs'>";
+					//-- for each tab we need to create a tab link
+					$(el)
+						.find("tab")
+						.each((idx, aTab) => {
+							const activeClass = idx === 0 ? " active" : "";
+							tabMarkup += `<li class='nav-item c-pointer' contentidx='${idx}'><span class='nav-link${activeClass}'>${aTab.getAttribute("name")}</span></li>`;
+
+							//-- hide the tab element if it is not the active one (first)
+							if (idx > 0) $(aTab).addClass("d-none");
+						});
+
+					tabMarkup += "</ul>";
+					//-- inject markup
+					$(el).prepend(tabMarkup).find(".nav.nav-tabs").addClass(tabClass);
+
+					//-- add event handler for switching tab items
+					$(el)
+						.find("li")
+						.off("click")
+						.on("click", function () {
+							const contentIdx = this.getAttribute("contentidx");
+							const tabsContainer = $(this).closest("tabs").eq(0);
+							const tabs = tabsContainer.find("tab");
+
+							//-- hide other tab content and show this tabs content
+							tabs.addClass("d-none");
+							tabs.eq(contentIdx - 0).removeClass("d-none");
+
+							//-- set clicked tab item to active
+							tabsContainer.find(".nav-link").removeClass("active");
+							$(this).find(".nav-link").addClass("active");
+						});
+				});
+
+			//-- do any code highlighting
+			if (hljs) {
+				for (const el of document.querySelectorAll("pre code")) {
+					hljs.highlightBlock(el);
+				}
+			} else {
+				hslDocLog.log(
+					"code highlighting js could not be loaded. code block highlighting will not be enabled",
+				);
+			}
+
+			//-- show copy button by any code blocks
+			const options = {
+				contentSelector: ".injected-document-content",
+				// Delay in ms used for `setTimeout` before badging is applied
+				// Use if you need to time highlighting and badge application
+				// since the badges need to be applied afterwards.
+				// 0 - direct execution (ie. you handle timing
+				loadDelay: 0,
+
+				// CSS class(es) used to render the copy icon.
+				copyIconClass: "bi bi-clipboard",
+				// CSS class(es) used to render the done icon.
+				checkIconClass: "bi bi-clipboard-check --htl-c-brand",
+
+				// intercept text copying - passed in text return text out
+				onBeforeCodeCopied: (text) => text,
+			};
+
+			highlightJsBadge(options);
+
+			//-- get first H1 and put it into our header section header
+			const docHeader = jqContentContainer.find("H1").eq(0);
+			jqDocumentHeader.find(".document-title").append(docHeader);
+
+			setGitHubBookUrl(clean_linkRef);
+
+			//-- make sure selected link parents are set to .expand=true
+			if (expandNavParentSectionBySelectedLinkHref(clean_linkRef)) {
+				view.updateCounter++;
+				view.$nextTick(() => {
+					//-- find any navigation links that match url and highlight
+					//                listenForHrefClicks();
+					highlightNavigationLinkFromUrl(clean_linkRef);
+
+					//-- scroll to element that match hash (if have one)
+					if (document.location.hash) {
+						const gotoEle = getAnchorFromHash(document.location.hash);
+						if (gotoEle) gotoEle[0].scrollIntoView();
+					}
+				});
+				view.$forceUpdate();
+			}
+
+			listenForHrefClicks();
+		});
+}
+
+function setGitHubBookUrl(linkRef) {
+	let bookRef = linkRef.split(siteBaseLocation);
+	bookRef = bookRef[1] ? bookRef[1] : bookRef[0];
+	const bookId = bookRef.split("/")[0];
+	view.docApp.documentGithubUrl = `https://github.com/Hornbill-Docs/${bookId}/blob/main/${bookRef}.md`;
+	//--https://github.com/Hornbill-Docs/hdoc-guide/blob/main/hdoc-guide/overview.md
+}
+
+function loadBookDefaultLink() {
+	$(".DocLink.link").first().click();
+}
+
+function findFirstClickableBookLink(findByLinkRef, currentNavSection) {
+	let currNav = currentNavSection;
+	if (currNav === undefined) currNav = view.docApp.navSections;
+
+	for (let x = 0; x < currNav.length; x++) {
+		if (currNav[x].items) {
+			const clickableItem = findFirstClickableBookLink(
+				findByLinkRef,
+				currNav[x].items,
+			);
+			if (clickableItem) {
+				return clickableItem;
+			}
+		} else if (currNav[x].link) {
+			if (findByLinkRef) {
+				if (
+					removeStartingSlash(removeTrailingSlash(currNav[x].link)) ===
+					findByLinkRef
+				)
+					return currNav[x].link;
+			} else {
+				return currNav[x].link;
+			}
+		}
+	}
+}
+
+function expandNavParentSectionBySelectedLinkHref(
+	findByLinkRef,
+	currentNavSection,
+) {
+	let currNav = currentNavSection;
+	if (currNav === undefined) {
+		view.docApp.bookBreadCrumb = []; //-- reset bread crumb
+		currNav = view.docApp.navSections;
+	}
+
+	for (let x = 0; x < currNav.length; x++) {
+		if (currNav[x].items) {
+			const res = expandNavParentSectionBySelectedLinkHref(
+				findByLinkRef.split("#")[0],
+				currNav[x].items,
+			);
+			if (res) {
+				currNav[x].expand = true;
+				view.docApp.bookBreadCrumb.unshift({
+					title: currNav[x].text,
+					link: currNav[x].items[0].link,
+				});
+				return res;
+			}
+		} else {
+			//-- check item to see if it matches url
+			if (
+				removeStartingSlash(removeTrailingSlash(currNav[x].link)) ===
+				findByLinkRef.split("#")[0]
+			) {
+				return true;
+			}
+		}
+	}
+}
+
+function old_expandNavParentSectionBySelectedLinkHref(
+	findByLinkRef,
+	currentNavSection,
+) {
+	let currNav = currentNavSection;
+	if (currNav === undefined) currNav = view.docApp.navSections;
+
+	for (let x = 0; x < currNav.length; x++) {
+		if (currNav[x].items) {
+			const res = expandNavParentSectionBySelectedLinkHref(
+				findByLinkRef.split("#")[0],
+				currNav[x].items,
+			);
+			if (res) {
+				currNav[x].expand = true;
+				return res;
+			}
+		} else {
+			//-- check item to see if it matches url
+			if (
+				removeStartingSlash(removeTrailingSlash(currNav[x].link)) ===
+				findByLinkRef.split("#")[0]
+			) {
+				return true;
+			}
+		}
+	}
+}
+
+let lastUrlDynamicallySet = "";
+function setBrowserViewUrl(
+	strHrefToLoad,
+	viewData,
+	fromPageRefresh,
+	fromPopState,
+) {
+	const urlToSet = `${window.location.origin}/${strHrefToLoad}`;
+	const url = new URL(urlToSet);
+
+	//-- remove any old params
+	for (const strKey in global.stateParams) {
+		url.searchParams.delete(strKey);
+	}
+
+	//-- now set new data params in url
+	for (const strKey in viewData) {
+		url.searchParams.set(strKey, viewData[strKey]);
+	}
+
+	//-- store global params
+	global.stateParams = viewData;
+
+	if (!fromPageRefresh) {
+		if (fromPopState) {
+			//-- so user has clicked on a link - always add entry
+			window.history.pushState(null, null, url); //-- add entry
+		} else {
+			if (lastUrlDynamicallySet) {
+				if (lastUrlDynamicallySet !== strHrefToLoad) {
+					window.history.pushState(null, null, url); //-- add entry
+				} else {
+					window.history.replaceState(null, null, url); //-- user has refreshed page or jsut visited page
+				}
+			} else {
+				window.history.replaceState(null, null, url); //-- user has clicked a link so we want to add state to history so we can click back
+			}
+		}
+	}
+	lastUrlDynamicallySet = strHrefToLoad;
+}
+
+async function fetchContentFile(strFilePath) {
+	return await fetch(strFilePath)
+		.then((response) => response.text())
+		.then((fileContent) => {
+			return fileContent;
+		});
+}
+
+async function fetchJsonFile(strFilePath) {
+	return await fetch(strFilePath)
+		.then((response) => response.json())
+		.then((jsonObject) => {
+			return jsonObject;
+		});
+}
+
+//-- THE INIT APP CALLED FROM index.html
+//$(".document-body").attr("v-pre", "");
+
+const view = new Vue({
+	el: "#vDocDevApp",
+	data: {
+		userSession: {},
+		updateCounter: 0,
+		bookId: "",
+		docApp: {
+			error: "",
+			inlinePopupDocumentHref: "",
+			showInlineDocumentsMarkup: false,
+			keepTocLayout: false,
+			book: {},
+			navSections: [],
+			inlineDocumentItems: [],
+			tableOfContents: [],
+			bookBreadCrumb: [],
+		},
+	},
+	methods: docAppMethods,
+	directives: {
+		somedirectivename: {
+			bind(el, binding, vnode) {
+				//-- do something when created on element
+			},
+		},
+	},
+	mounted: () => {},
+});
+
+//-- repeatable conmponent for nav sections
+Vue.component("nav-section-component", {
+	props: ["asection"],
+	template: "#nav-section-template",
+	methods: {
+		toggleNavCollapse: function (navSection) {
+			navSection.expand = !navSection.expand;
+			this.$forceUpdate();
+		},
+	},
+});
+
+const hslDocLog = {
+	_entry: [],
+	log: function (strMessage, varData) {
+		if (varData !== undefined) console.log(strMessage, varData);
+		else console.log(strMessage);
+
+		this._entry.push({ msg: strMessage, data: varData });
+	},
+	dump: function () {
+		for (let x = 0; x < this._entry.length; x++) {
+			console.log(this._entry[x].msg, this._entry[x].data || null);
+		}
+	},
+};
+
+async function intialiseApp() {
+	// set theme switch
+	$(".theme-switch-checkbox").prop("checked", ThemePreference === "dark");
+
+	jqDocumentHeader = $(".injected-document-content .document-header");
+	jqContentContainer = $(".injected-document-content .document-body");
+	//jqContentContainer = $(".injected-document-content");
+	jqLeftNav = $("#DocSidebarNav");
+
+	await fetchJsonFile("_books/library.json")
+		.then((data) => {
+			// Get docbook library list
+			view.docApp.library = data;
+			view.docId = view.docApp.library.books[0].docId;
+		})
+		.then(() => {
+			// Get hdocbook.json
+			fetchJsonFile(`_books/${view.docId}/hdocbook.json`)
+				.then((data) => {
+					view.docApp.book = data;
+					view.bookId = data.docId;
+					view.docApp.title = data.title || "";
+					view.docApp.description = data.description || "";
+
+					view.docApp.inlineDocumentItems = [];
+					view.docApp.inlinePopupDocumentHref = "";
+					view.docApp.showInlineDocumentsMarkup = false;
+					view.docApp.hasInlinePopupDocuments =
+						!!view.docApp.library.books[0].nav_inline?.items?.length;
+					if (view.docApp.hasInlinePopupDocuments) {
+						view.docApp.inlineDocumentItems =
+							view.docApp.library.books[0].nav_inline.items;
+						view.docApp.book.navigation.items.push(
+							view.docApp.library.books[0].nav_inline,
+						);
+					}
+
+					//-- now render out the nav menu
+					view.renderNavigation();
+
+					setTimeout(() => {
+						listenForHrefClicks();
+
+						//-- check if url is not root - in which case we need to load content for url
+						let initialLoadContentHref = window.location.href.replace(
+							`${window.location.origin}/`,
+							"",
+						);
+						initialLoadContentHref = findFirstClickableBookLink(
+							initialLoadContentHref,
+						);
+
+						if (initialLoadContentHref) {
+							//-- find the link we are going to show and make sure parent/s are set to .expand=true
+							loadContentUrl(initialLoadContentHref, true, false);
+						} else {
+							hslDocLog.log("initial first view link to load is not present");
+						}
+
+						$(".hb-hidden").removeClass("hb-hidden");
+					}, 200);
+				})
+				.catch((data) => {
+					view.docApp.error = data;
+					$(".hb-hidden").removeClass("hb-hidden");
+				});
+		});
+}