@salesforcedevs/docs-components 0.56.2 → 0.56.3-example

package/src/modules/doc/amfReference/amfReference.ts

@@ -2,8 +2,9 @@ import { LightningElement, api, track } from "lwc";
 import { noCase } from "no-case";
 import { sentenceCase } from "sentence-case";
 import qs from "query-string";
-import { AmfModelParser } from "./utils";
-import { RouteMeta } from "./route-meta";
+import { AmfModelParser } from "doc/amfModelParser";
+import { normalizeBoolean, toJson } from "dxUtils/normalizers";
+import type { OptionWithLink } from "typings/custom";
 import type {
     AmfConfig,
     AmfMetadataTopic,
@@ -14,94 +15,62 @@ import type {
     TopicModel,
     ReferenceVersion,
     ReferenceSetConfig,
-    AmfMetaTopicType
+    AmfMetaTopicType,
+    RouteMeta,
+    ParsedMarkdownTopic
 } from "./types";
 
-const NAVIGATION_ITEMS = [
-    {
-        label: "Summary",
-        name: "summary",
-        childrenPropertyName: undefined,
-        type: "summary"
-    },
-    {
-        label: "Endpoints",
-        name: "endpoints",
-        childrenPropertyName: "endpoints",
-        type: "endpoint"
-    },
-    {
-        label: "Documentation",
-        name: "documentation",
-        childrenPropertyName: "docs",
-        type: "documentation"
-    },
-    {
-        label: "Types",
-        name: "types",
-        childrenPropertyName: "types",
-        type: "type"
-    },
-    {
-        label: "Security",
-        name: "security",
-        childrenPropertyName: "security",
-        type: "security"
-    }
-];
-
-const URL_CONFIG = {
-    summary: {
-        urlIdentifer: "label"
-    },
-    endpoint: {
-        urlIdentifer: "path"
-    },
-    method: {
-        urlIdentifer: "label"
-    },
-    documentation: {
-        urlIdentifer: "label"
-    },
-    type: {
-        urlIdentifer: "label",
-        prefix: "type:"
-    },
-    security: {
-        urlIdentifer: "label",
-        prefix: "security:"
-    }
-};
-
-const urlHashToMetaRedirectMap = {
-    "commerce-api-assignments:Summary": "assignments:Summary",
-    "commerce-api-campaigns:Summary": "campaigns:Summary",
-    "commerce-api-catalogs:Summary": "catalogs:Summary",
-    "cdn-zones:Summary": "cdn-api-process-apis:Summary",
-    "inventory-impex:Summary": "impex:Summary",
-    "inventory-reservations:Summary": "inventory-reservation-service:Summary",
-    "shopper-login-and-api-access-service:Summary": "shopper-login:Summary",
-    "shopper-login-and-api-access-service-admin:Summary": "slas-admin:Summary",
-    "einstein-recommendations:Summary": "einstein-api-quick-start-guide:Summary"
+import {
+    NAVIGATION_ITEMS,
+    URL_CONFIG,
+    REFERENCE_TYPES,
+    oldReferenceIdNewReferenceIdMap
+} from "./constants";
+import { restoreScroll } from "dx/scrollManager";
+import { DocPhaseInfo } from "typings/custom";
+import { logCoveoPageView, oldVersionDocInfo } from "docUtils/utils";
+
+type NavigationItem = {
+    label: string;
+    name: string;
+    isExpanded: boolean;
+    children: ParsedMarkdownTopic[];
+    isChildrenLoading: boolean;
 };
 
 export default class AmfReference extends LightningElement {
-    @api breadcrumbs?: string = null;
-    @api sidebarHeader: string;
+    @api breadcrumbs: string | null = null;
+    @api sidebarHeader!: string;
     @api coveoOrganizationId!: string;
     @api coveoPublicAccessToken!: string;
-    @api coveoAdvancedQueryConfig!: string;
+    @api coveoAnalyticsToken!: string;
     @api coveoSearchHub!: string;
-    @api useOldSidebar?: boolean = false;
+    @api useOldSidebar: boolean = false;
+    @api tocTitle?: string;
+    @api tocOptions?: string;
+    @api languages!: OptionWithLink[];
+    @api language!: string;
+    @api hideFooter = false;
+    @track navigation = [] as NavigationItem[];
+    @track versions: Array<ReferenceVersion> = [];
+    @track showVersionBanner = false;
+    @track _coveoAdvancedQueryConfig!: { [key: string]: any };
 
     // Update this to update what component gets rendered in the content block
     @track
-    protected topicModel: TopicModel;
+    protected topicModel!: TopicModel;
 
     get isVersionEnabled(): boolean {
         return !!this._referenceSetConfig?.versions?.length;
     }
 
+    /**
+     * Gives if the currently selected reference is spec based or not
+     */
+    get showSpecBasedReference(): boolean {
+        return this.isSpecBasedReference(this._currentReferenceId);
+    }
+
     @api
     get referenceSetConfig(): ReferenceSetConfig {
         return this._referenceSetConfig;
@@ -122,27 +91,57 @@ export default class AmfReference extends LightningElement {
             this._referenceSetConfig = refConfig;
         } catch (e) {
             this._referenceSetConfig = {
-                refList: []
+                refList: [],
+                versions: []
             };
         }
 
+        this._amfConfigList = this._referenceSetConfig.refList || [];
+
+        this._amfConfigList.forEach((amfConfig) => {
+            this._amfConfigMap.set(amfConfig.id, amfConfig);
+        });
+
+        if (this._amfConfigList.length > 0) {
+            this._currentReferenceId =
+                this._referenceSetConfig.refId || this._amfConfigList[0].id;
+        }
+
         if (this.isVersionEnabled) {
             const selectedVersion = this.getSelectedVersion();
-            this.versionToRefMap = this._referenceSetConfig.versionToRefMap;
-            // if version is not available, then show empty - this will be the default behaviour
-            this._amfConfig = this.versionToRefMap[selectedVersion.id] || [];
-            this.versions = this._referenceSetConfig.versions;
+
+            /**
+             * If current selected is markdown based reference,
+             * We will assign versions once the selected item url is updated
+             */
+            if (this.isSpecBasedReference(this._currentReferenceId)) {
+                this.versions = this.getVersions();
+            }
             this.selectedVersion = selectedVersion;
+            if (this.isSpecBasedReference(this._currentReferenceId)) {
+                this.isVersionFetched = true;
+                if (this.oldVersionInfo) {
+                    this.showVersionBanner = true;
+                } else {
+                    this.latestVersion = true;
+                }
+            }
         } else {
-            this._amfConfig = this._referenceSetConfig.refList;
+            this.isVersionFetched = true;
         }
 
-        this.updateAmfConfigInView();
+        // This is to check if the url is hash based and redirect if needed
+        const redirectUrl = this.getHashBasedRedirectUrl();
+        if (redirectUrl) {
+            window.location.href = redirectUrl;
+        } else {
+            this.updateAmfConfigInView();
+        }
     }
 
     @api
-    get docPhaseInfo() {
-        return this.selectedReferenceDocPhase;
+    get docPhaseInfo(): string | null {
+        return this.selectedReferenceDocPhase || null;
     }
 
     set docPhaseInfo(value: string) {
@@ -152,53 +151,83 @@ export default class AmfReference extends LightningElement {
         }
     }
 
+    @api
+    get expandChildren() {
+        return this._expandChildren;
+    }
+
+    set expandChildren(value) {
+        this._expandChildren = normalizeBoolean(value);
+    }
+
+    /*
+     * The get coveoAdvancedQueryConfig() method returns this._coveoAdvancedQueryConfig,
+     * but before returning it, it checks if there are multiple versions (this.versions.length > 1)
+     * and if a version is selected (this.selectedVersion). If both conditions are met,
+     * it updates the version property of this._coveoAdvancedQueryConfig with the selected version.
+     */
+    @api
+    get coveoAdvancedQueryConfig(): { [key: string]: any } {
+        const coveoConfig = this._coveoAdvancedQueryConfig;
+        if (this.versions.length > 1 && this.selectedVersion) {
+            const currentGAVersionRef = this.versions[0];
+            if (this.selectedVersion.id !== currentGAVersionRef.id) {
+                // Currently Coveo only supports query without "v"
+                const version = this.selectedVersion.id.replace("v", "");
+                coveoConfig.version = version;
+                this._coveoAdvancedQueryConfig = coveoConfig;
+            }
+        }
+        return this._coveoAdvancedQueryConfig;
+    }
+
+    set coveoAdvancedQueryConfig(config) {
+        this._coveoAdvancedQueryConfig = toJson(config);
+    }
+
+    private get enableFooter(): boolean {
+        return !this.hideFooter;
+    }
+
     // model
-    protected _amfConfig: AmfConfig[] = [];
-    protected _referenceSetConfig: ReferenceSetConfig;
+    protected _amfConfigList: AmfConfig[] = [];
+    protected _amfConfigMap: Map<string, AmfConfig> = new Map();
+    protected _referenceSetConfig!: ReferenceSetConfig;
     protected _currentReferenceId = "";
 
+    protected parentReferenceUrls = [] as string[];
     protected amfMap: Record<string, AmfModelRecord> = {};
-    protected amfFetchPromiseMap = {};
+    protected amfFetchPromiseMap = {} as any;
     protected metadata: { [key: string]: AmfMetadataTopic } = {};
-    protected selectedTopic: AmfMetaTopicType = undefined;
-    protected navigation = [];
-    protected selectedSidebarValue = undefined;
-    protected versions: Array<ReferenceVersion> = [];
-    protected selectedVersion: ReferenceVersion = null;
+    protected selectedTopic?: AmfMetaTopicType = undefined;
+    protected selectedSidebarValue: string | undefined = undefined;
 
-    private hasRendered = false;
-    private navAmfOrder = [];
+    protected selectedVersion: ReferenceVersion | null = null;
 
-    private versionToRefMap: Map<string, Array<AmfConfig>>;
+    private hasRendered = false;
 
     private isParentLevelDocPhaseEnabled = false;
-    private selectedReferenceDocPhase?: string = null;
+    private selectedReferenceDocPhase?: string | null = null;
+    private _expandChildren?: boolean = false;
+    private isVersionFetched = false;
+    private latestVersion = false;
 
     /**
-     * Key for storing the currently selected reference meta query param. This will be used to save the
-     * previously selected reference meta and restoring it when changing between reference versions.
+     * Key for storing the currently selected reference url. This will be used to save the
+     * previously selected reference url and restoring it when changing between reference versions.
      */
-    private readonly docsReferenceMetaSessionKey: string = "docsReferenceMeta";
+    private readonly docsReferenceUrlSessionKey: string = "docsReferenceUrl";
 
     _boundOnApiNavigationChanged;
     _boundUpdateSelectedItemFromUrlQuery;
 
-    get amfConfigMapped(): AmfConfig[] {
-        return this._amfConfig.map((config) => {
-            return config.id in this.amfMap
-                ? Object.assign(config, this.amfMap[config.id])
-                : config;
-        });
-    }
-
     constructor() {
         super();
-        this._boundOnApiNavigationChanged = this.onApiNavigationChanged.bind(
-            this
-        );
-        this._boundUpdateSelectedItemFromUrlQuery = this.updateSelectedItemFromUrlQuery.bind(
-            this
-        );
+
+        this._boundOnApiNavigationChanged =
+            this.onApiNavigationChanged.bind(this);
+        this._boundUpdateSelectedItemFromUrlQuery =
+            this.updateSelectedItemFromUrlQuery.bind(this);
     }
 
     connectedCallback(): void {
@@ -226,7 +255,7 @@ export default class AmfReference extends LightningElement {
     renderedCallback(): void {
         if (!this.hasRendered) {
             this.hasRendered = true;
-            if (this._amfConfig && this._amfConfig.length) {
+            if (this._amfConfigList && this._amfConfigList.length) {
                 // If amfConfig has a value and length, it is assumed that fetch
                 // has already been called and promises stored.
                 this.updateView();
@@ -234,22 +263,136 @@ export default class AmfReference extends LightningElement {
         }
     }
 
+    /**
+     * Check if the URL hash to see whether this is one we want to redirect
+     * See GUS W-10718771 for references where we want hash-based redirects
+     * Return if we needs to redirect url to updated url
+     */
+    private getHashBasedRedirectUrl(): string | undefined {
+        const { hash } = window.location;
+        let hashBasedRedirectUrl = "";
+        if (hash) {
+            const strippedHash = hash.startsWith("#") ? hash.slice(1) : hash;
+            const strippedHashItems = strippedHash
+                ? strippedHash.split(":")
+                : [];
+            if (strippedHashItems.length) {
+                const referenceId = strippedHashItems[0];
+                const meta = strippedHashItems[1];
+                const encodedMeta = this.getUrlEncoded(meta);
+                const updatedReferenceId =
+                    oldReferenceIdNewReferenceIdMap[referenceId];
+                const newReferenceId = updatedReferenceId || referenceId;
+                const referenceItemConfig =
+                    this.getAmfConfigWithId(newReferenceId);
+                if (referenceItemConfig) {
+                    hashBasedRedirectUrl = `${referenceItemConfig.href}?meta=${encodedMeta}`;
+                }
+            }
+        }
+        return hashBasedRedirectUrl;
+    }
+
+    /**
+     * @param referenceId
+     * @returns AMFConfig with given reference Id
+     */
+    private getAmfConfigWithId(referenceId: string): AmfConfig | undefined {
+        return this._amfConfigMap.get(referenceId);
+    }
+
+    /**
+     * @param referenceId
+     * @returns if the reference is spec based one or not with given referenceId.
+     */
+    private isSpecBasedReference(referenceId: string): boolean {
+        const selectedReference = this.getAmfConfigWithId(referenceId);
+        return selectedReference
+            ? selectedReference.referenceType !== REFERENCE_TYPES.markdown
+            : false;
+    }
+
+    /*
+     * Refactor below method when sidebar allows sending extraData along with the name for each item.
+     * See if we can refactor the below method using regex.
+     */
+
+    /**
+     * @param url
+     * @returns reference Id from url path / selected sidebar item.
+     */
+    private getReferenceIdFromUrl(url: string): string {
+        let referenceId = "";
+        const urlItems = url.split("/references/");
+        if (urlItems.length > 1) {
+            const rightSidePart = urlItems[1];
+
+            //This covers urls like "/project-name/references/reference-id/..."
+            const slashSeparatorItems = rightSidePart.split("/");
+
+            //This covers urls like "/project-name/references/reference-id?meta=Summary"
+            const querySeparatorItems = slashSeparatorItems[0].split("?");
+
+            referenceId = querySeparatorItems[0];
+        }
+
+        return referenceId;
+    }
+
+    private get oldVersionInfo(): DocPhaseInfo | null {
+        let info = null;
+        if (this.versions.length > 1 && this.selectedVersion) {
+            const currentGAVersionRef = this.versions[0];
+            if (this.selectedVersion.id !== currentGAVersionRef.id) {
+                info = oldVersionDocInfo(currentGAVersionRef.link.href);
+            }
+        }
+        return info;
+    }
+
+    /**
+     * @returns versions to be shown in the dropdown
+     * For markdown based specs, Adds selected markdown topic url to same references
+     */
+    private getVersions(): Array<ReferenceVersion> {
+        const allVersions = this._referenceSetConfig.versions;
+        if (!this.isSpecBasedReference(this._currentReferenceId)) {
+            const currentRefMeta = this.getMarkdownReferenceMeta(
+                window.location.href
+            );
+            if (currentRefMeta) {
+                for (let i = 0; i < allVersions.length; i++) {
+                    const versionItem = allVersions[i];
+                    const referenceLink = versionItem.link.href;
+                    const referenceId =
+                        this.getReferenceIdFromUrl(referenceLink);
+                    if (this._currentReferenceId === referenceId) {
+                        // This is to navigate to respective topic in the changed version
+                        versionItem.link.href = `${referenceLink}/${currentRefMeta}`;
+                        allVersions[i] = versionItem;
+                    }
+                }
+            }
+        }
+        return allVersions;
+    }
+
     /**
      * Returns the selected version or the first available version.
      */
-    private getSelectedVersion(): ReferenceVersion {
+    private getSelectedVersion(): ReferenceVersion | null {
         const versions = this._referenceSetConfig?.versions || [];
         const selectedVersion = versions.find(
             (v: ReferenceVersion) => v.selected
         );
         // return a selected version if there is one, else return the first one.
-        return selectedVersion || (versions.length && versions[0]);
+        return selectedVersion || (versions.length && versions[0]) || null;
     }
 
     private updateAmfConfigInView(): void {
-        if (this._amfConfig && this._amfConfig.length) {
+        if (this._amfConfigList && this._amfConfigList.length) {
             // fetch AMF Json as soon as config is set
-            this.fetchAllAmf();
+            this.populateReferenceItems();
             // update() must be called after renderedCallback.
             if (this.hasRendered) {
                 this.updateView();
@@ -257,9 +400,11 @@ export default class AmfReference extends LightningElement {
         }
     }
 
-    private async fetchAmf(amfConfig): Promise<AmfModel | AmfModel[]> {
+    private async fetchAmf(
+        amfConfig: AmfConfig
+    ): Promise<AmfModel | AmfModel[]> {
         const { amf } = amfConfig;
-        const response = await fetch(amf, {
+        const response = await fetch(amf!, {
             headers: {
                 "Cache-Control": `max-age=86400`
             }
@@ -269,17 +414,95 @@ export default class AmfReference extends LightningElement {
     }
 
     /**
-     * Calls the fetch for each AMF in the config.
-     * Stores each fetch promise for handling after renderCallback.
+     * Returns whether current location is project root path like ../example-project/references
      */
-    private fetchAllAmf(): void {
-        for (const [i, amfConfig] of this._amfConfig.entries()) {
-            const p = this.fetchAmf(amfConfig).then((amfJson) => {
-                this.updateModel(amfConfig.id, amfJson);
-                this.assignNavigationItemsFromAmf(amfConfig.id, i);
-            });
-            this.amfFetchPromiseMap[amfConfig.id] = p;
+    private isProjectRootPath(): boolean {
+        return this.getReferenceIdFromUrl(window.location.href) === "";
+    }
+
+    /**
+     * Returns whether given url is parent reference path like ../example-project/references/reference-id
+     */
+    private isParentReferencePath(urlPath?: string | null): boolean {
+        if (!urlPath) {
+            return false;
         }
+        const parentReferenceIndex = this.parentReferenceUrls.findIndex(
+            (referenceUrl: string) => {
+                return urlPath.endsWith(referenceUrl);
+            }
+        );
+        return parentReferenceIndex !== -1;
+    }
+
+    /**
+     * Expands the children of Markdown-based References.
+     */
+    private expandChildrenForMarkdownReferences(
+        children: ParsedMarkdownTopic[]
+    ): void {
+        if (!children) {
+            return;
+        }
+        for (const childNode of children) {
+            childNode.isExpanded = true;
+            this.expandChildrenForMarkdownReferences(childNode.children);
+        }
+    }
+
+    /**
+     * Populates reference Items from amfConfigList and assigns it to navigation for sidebar
+     */
+    private populateReferenceItems(): void {
+        const navAmfOrder = [] as NavigationItem[];
+        for (const [index, amfConfig] of this._amfConfigList.entries()) {
+            let navItemChildren = [] as ParsedMarkdownTopic[];
+            let isChildrenLoading = false;
+            if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
+                if (amfConfig.isSelected) {
+                    const amfPromise = this.fetchAmf(amfConfig).then(
+                        (amfJson) => {
+                            this.updateModel(amfConfig.id, amfJson);
+                            this.assignNavigationItemsFromAmf(amfConfig, index);
+                        }
+                    );
+                    this.amfFetchPromiseMap[amfConfig.id] = amfPromise;
+                }
+                isChildrenLoading = true;
+            } else {
+                const isExpandChildrenEnabled = this.isExpandChildrenEnabled(
+                    amfConfig.id
+                );
+                // check whether we should expand all the child nodes, this is required for Coveo to crawl.
+                if (isExpandChildrenEnabled) {
+                    this.expandChildrenForMarkdownReferences(
+                        amfConfig.topic!.children
+                    );
+                }
+                navItemChildren = amfConfig.topic!.children;
+            }
+            // store nav items for each spec in order
+            navAmfOrder[index] = {
+                label: amfConfig.title,
+                name: amfConfig.href,
+                isExpanded:
+                    amfConfig.isSelected ||
+                    this.isExpandChildrenEnabled(amfConfig.id),
+                children: navItemChildren,
+                isChildrenLoading
+            };
+            this.parentReferenceUrls.push(amfConfig.href);
+        }
+        this.navigation = navAmfOrder;
+    }
+
+    /**
+     * Returns a boolean indicating whether the children should be expanded or not.
+     */
+    private isExpandChildrenEnabled(referenceId: string): boolean {
+        return (
+            !!this.expandChildren && this._currentReferenceId === referenceId
+        );
     }
 
     /**
@@ -311,7 +534,7 @@ export default class AmfReference extends LightningElement {
 
     /**
      * Transforms a list of model data for endpoints into corresponding
-     * navigation list items that is compatible with dx-sidebar.
+     * navigation list items that are compatible with dx-sidebar.
      * Compatible with transforming AMF data parsed from both RAML and OAS spec.
      * Transforms a flat list of endpoints into a nested list based on indentation level
      * for RAML spec.
@@ -319,29 +542,47 @@ export default class AmfReference extends LightningElement {
      * @returns {array<Object>} List of navigation items
      */
     private assignEndpointNavItems(
+        parentReferencePath: string,
         referenceId: string,
         items: ParsedTopicModel[]
     ): NavItem[] {
-        const methodList = [];
+        const methodList = [] as NavItem[];
 
         items.forEach((item) => {
             item.methods?.forEach((method) => {
-                const meta = this.addToMetadata(referenceId, "method", method);
+                const title =
+                    this.getTitleForLabel(method.label!) || method.method;
+                const meta = this.addToMetadata(
+                    parentReferencePath,
+                    referenceId,
+                    "method",
+                    method,
+                    title
+                );
                 methodList.push(
                     Object.assign(method, {
-                        name: this.getReferencePathWithMeta(meta),
-                        label:
-                            this.getTitleForLabel(method.label) || method.method
+                        name: this.getReferencePathWithMeta(
+                            parentReferencePath,
+                            meta
+                        ),
+                        label: title
                     })
                 );
             });
         });
-
         return methodList;
     }
 
-    private getReferencePathWithMeta(meta: string): string {
-        return meta ? `${window.location.pathname}?meta=${meta}` : "";
+    /**
+     * Gives URL path for reference items, Which can be used to push to the history
+     */
+    private getReferencePathWithMeta(
+        parentReferencePath: string,
+        meta: string
+    ): string {
+        // update the encoded url meta param
+        const encodedMeta = meta ? this.getUrlEncoded(meta) : "";
+        return encodedMeta ? `${parentReferencePath}?meta=${encodedMeta}` : "";
     }
 
     /**
@@ -351,12 +592,15 @@ export default class AmfReference extends LightningElement {
      * The 'endpoint' nav item may have nested children.
      */
     private assignNavigationItemsFromAmf(
-        referenceId: string,
+        amfConfig: AmfConfig,
         amfIdx: number
     ): void {
+        const referenceId = amfConfig.id;
+        const parentReferencePath = amfConfig.href;
         const model = this.amfMap[referenceId].parser.parsedModel;
 
-        const children = [];
+        const children: any[] = [];
+        const expandChildren = this.isExpandChildrenEnabled(referenceId);
 
         NAVIGATION_ITEMS.forEach(
             ({ label, name, childrenPropertyName, type }) => {
@@ -365,58 +609,67 @@ export default class AmfReference extends LightningElement {
                     case "summary": {
                         const summary = model[type];
                         const meta = this.addToMetadata(
+                            parentReferencePath,
                             referenceId,
                             type,
-                            summary
+                            summary,
+                            label
                         );
                         children.push({
                             label,
-                            name: this.getReferencePathWithMeta(meta)
+                            name: this.getReferencePathWithMeta(
+                                parentReferencePath,
+                                meta
+                            )
                         });
                         break;
                     }
                     case "endpoint":
                         if (
-                            model[childrenPropertyName] &&
-                            model[childrenPropertyName].length
+                            model[childrenPropertyName!] &&
+                            model[childrenPropertyName!].length
                         ) {
                             const amfTopicId = this.getFormattedIdentifier(
                                 referenceId,
                                 indexedName
                             );
                             const childTopics = this.assignEndpointNavItems(
+                                parentReferencePath,
                                 referenceId,
-                                model[childrenPropertyName]
+                                model[childrenPropertyName!]
                             );
                             children.push({
                                 label,
                                 name: this.getReferencePathWithMeta(
+                                    parentReferencePath,
                                     this.metadata[amfTopicId]?.meta
                                 ),
-                                isExpanded: false,
+                                isExpanded: expandChildren,
                                 children: childTopics
                             });
                         }
                         break;
                     case "security":
                     case "type":
-                        if (model[childrenPropertyName]?.length) {
+                        if (model[childrenPropertyName!]?.length) {
                             // Sorting the types alphabetically
-                            model[childrenPropertyName].sort((typeA, typeB) => {
-                                const typeALbl = typeA.label.toLowerCase();
-                                const typeBLbl = typeB.label.toLowerCase();
-                                return typeALbl < typeBLbl
-                                    ? -1
-                                    : typeALbl > typeBLbl
-                                    ? 1
-                                    : 0;
-                            });
+                            model[childrenPropertyName!].sort(
+                                (typeA: any, typeB: any) => {
+                                    const typeALbl = typeA.label.toLowerCase();
+                                    const typeBLbl = typeB.label.toLowerCase();
+                                    return typeALbl < typeBLbl
+                                        ? -1
+                                        : typeALbl > typeBLbl
+                                        ? 1
+                                        : 0;
+                                }
+                            );
                         }
                     // eslint-disable-next-line no-fallthrough
                     default:
                         if (
-                            model[childrenPropertyName] &&
-                            model[childrenPropertyName].length
+                            model[childrenPropertyName!] &&
+                            model[childrenPropertyName!].length
                         ) {
                             const amfTopicId = this.getFormattedIdentifier(
                                 referenceId,
@@ -425,19 +678,23 @@ export default class AmfReference extends LightningElement {
                             children.push({
                                 label,
                                 name: this.getReferencePathWithMeta(
+                                    parentReferencePath,
                                     this.metadata[amfTopicId]?.meta
                                 ),
-                                isExpanded: false,
-                                children: model[childrenPropertyName].map(
-                                    (topic) => {
+                                isExpanded: expandChildren,
+                                children: model[childrenPropertyName!].map(
+                                    (topic: any) => {
                                         const meta = this.addToMetadata(
+                                            parentReferencePath,
                                             referenceId,
                                             type,
-                                            topic
+                                            topic,
+                                            topic.label
                                         );
                                         return {
                                             label: topic.label,
                                             name: this.getReferencePathWithMeta(
+                                                parentReferencePath,
                                                 meta
                                             )
                                         };
@@ -449,47 +706,48 @@ export default class AmfReference extends LightningElement {
             }
         );
 
-        // store nav items for each spec in order
-        this.navAmfOrder[amfIdx] = {
-            label: model.title,
-            name: this.getReferencePathWithMeta(`${referenceId}-root`),
-            isExpanded: amfIdx === 0, // only expand the first spec
-            children
+        this.navigation[amfIdx] = {
+            ...this.navigation[amfIdx],
+            children,
+            isChildrenLoading: false
         };
-
-        // update navigation with each specs nav items as they become available
-        // navigation has to be an array because dx-sidebar expects an array.
-        const navigation = [];
-        for (const navAmf of this.navAmfOrder) {
-            if (navAmf) {
-                navigation.push(navAmf);
-            }
-        }
-        this.navigation = navigation;
+        this.navigation = [...this.navigation];
     }
 
     protected addToMetadata(
+        parentReferencePath: string,
         referenceId: string,
         type: string,
-        topic: { id: string; domId: string }
+        topic: { id: string; domId: string },
+        navTitle: string
     ): string {
-        const { urlIdentifer, prefix } = URL_CONFIG[type];
+        const config = URL_CONFIG[type as keyof typeof URL_CONFIG];
+        const urlIdentifer = config.urlIdentifer;
+        let prefix = null;
+        if ("prefix" in config) {
+            prefix = config.prefix;
+        }
 
         // encodeURI to avoid special characters in the URL meta.
         const identifier =
-            topic[urlIdentifer] && this.encodeIdentifier(topic[urlIdentifer]);
-        const meta = prefix
-            ? `${referenceId}:${prefix}${identifier}`
-            : `${referenceId}:${identifier}`;
-        this.metadata[meta] = {
-            meta: meta,
-            referenceId: referenceId,
-            amfId: topic.id,
-            elementId: topic.domId,
-            identifier,
-            type
-        };
-        return meta;
+            urlIdentifer in topic &&
+            this.encodeIdentifier(topic[urlIdentifer as keyof typeof topic]);
+        let meta;
+        // Assuming that there will be an identifier always
+        if (identifier) {
+            meta = prefix ? `${prefix}${identifier}` : `${identifier}`;
+            this.metadata[meta] = {
+                parentReferencePath,
+                meta,
+                referenceId,
+                amfId: topic.id,
+                elementId: topic.domId,
+                identifier,
+                type,
+                navTitle
+            };
+        }
+        return meta!;
     }
 
     /**
@@ -500,7 +758,7 @@ export default class AmfReference extends LightningElement {
             (metadata: AmfMetadataTopic) => {
                 return routeMeta.meta === metadata.meta;
             }
-        );
+        )!;
     }
 
     /**
@@ -514,7 +772,7 @@ export default class AmfReference extends LightningElement {
         return Object.values(this.metadata).find(
             (metadata: AmfMetadataTopic) =>
                 referenceId === metadata.referenceId && amfId === metadata.amfId
-        );
+        )!;
     }
 
     /**
@@ -529,7 +787,7 @@ export default class AmfReference extends LightningElement {
             (metadata: AmfMetadataTopic) =>
                 referenceId === metadata.referenceId &&
                 identifier === metadata.identifier
-        );
+        )!;
     }
 
     /**
@@ -543,58 +801,29 @@ export default class AmfReference extends LightningElement {
         return Object.values(this.metadata).find(
             (metadata: AmfMetadataTopic) =>
                 referenceId === metadata.referenceId && type === metadata.type
-        );
+        )!;
     }
 
     /**
-     * Parses url query params without decoding of params
+     * Parses URL query params without decoding of params
      */
-    private parseParams(path: string): qs.ParsedQuery<string> {
-        if (!path) {
+    private parseParams(params: string): qs.ParsedQuery<string> {
+        if (!params) {
             return {};
         }
-        return qs.parse(path, {
+        return qs.parse(params, {
             decode: false
         });
     }
 
-    /**
-     * Gets the portion from the URL query param 'meta'.
-     */
-    protected getCurrentRefMeta(
-        previousRefMetaInSession?: string
-    ): RouteMeta | null {
-        const path = window.location.search;
-        const urlParams = this.parseParams(path);
-        let meta = urlParams.meta as string;
-        let routeMeta = null;
-        if (previousRefMetaInSession) {
-            const refParts = previousRefMetaInSession.split(":");
-            const newRefId = refParts.length > 0 ? refParts[0] : null;
-            const [, type, topicId] = previousRefMetaInSession.split(":");
-            meta = newRefId ? [newRefId, type, topicId].join(":") : null;
-        } else if (!meta) {
-            // If no `meta` explicitly exists, check the URL hash to see whether this is one we
-            // want to redirect (see GUS W-10718771 for one reference where we want hash-based
-            // redirects)
-            const { hash } = window.location;
-            const strippedHash = hash.startsWith("#") ? hash.slice(1) : hash;
-            meta = urlHashToMetaRedirectMap[strippedHash];
-        }
-        if (meta) {
-            routeMeta = new RouteMeta(meta);
-        }
-        return routeMeta;
-    }
-
     /**
      * Normalizes topic identifier by replacing spaces with '+'
      * and running encodeURI() on it
-     * @param identifer raw identifer for a topic as parsed from the spec file
+     * @param identifier raw identifier for a topic as parsed from the spec file
      * @returns normalized and encoded identifier
      */
-    protected encodeIdentifier(identifer: string): string {
-        let result = identifer.trim();
+    protected encodeIdentifier(identifier: string): string {
+        let result = identifier.trim();
         result = result.replace(new RegExp(/\s+/, "g"), "+");
         return encodeURI(result);
     }
@@ -606,86 +835,137 @@ export default class AmfReference extends LightningElement {
         return `${referenceId}:${id}`;
     }
 
-    protected updateSelectedItemFromUrlQuery(): void {
-        const currentMeta: RouteMeta | null = this.getCurrentRefMeta();
-        const metadata = currentMeta && this.getMetadataByUrlQuery(currentMeta);
-        if (metadata) {
-            const {
-                referenceId,
-                amfId,
-                type,
-                elementId
-            }: AmfMetadataTopic = metadata;
-            this.loadContent(
-                referenceId,
-                amfId,
-                type,
-                elementId,
-                currentMeta.meta
-            );
-        }
-    }
-    protected onApiNavigationChanged(): void {
-        // The API Navigation event will always intend to navigate within the current reference
-        const metadata = this.metadata[
-            this.getReferencePathWithMeta(this.selectedTopic.meta)
-        ];
-        const {
-            referenceId,
-            amfId,
-            type,
-            elementId
-        }: AmfMetadataTopic = metadata;
-        this.loadContent(referenceId, amfId, type, elementId, metadata.meta);
-        this.updateUrlWithSelected();
-    }
-
-    protected updateUrlWithSelected(meta?: string): void {
+    protected updateUrlWithSelected(
+        parentReferencePath: string,
+        meta?: string
+    ): void {
         if (meta) {
+            // update the encoded url meta param
+            const encodedMeta = this.getUrlEncoded(meta);
+
             window.history.pushState(
                 {},
                 "",
-                `${window.location.pathname}?meta=${meta}`
+                `${parentReferencePath}?meta=${encodedMeta}`
             );
         }
     }
 
     /**
-     * Does a replace on the url meta, so it does not create a history entry.
+     * Does a replace on the URL meta, so it does not create a history entry.
      */
-    protected replaceUrlWithSelected(meta?: string): void {
+    protected replaceUrlWithSelected(
+        parentReferencePath: string,
+        meta?: string
+    ): void {
         if (meta) {
+            // update the encoded url meta param
+            const encodedMeta = this.getUrlEncoded(meta);
+
             window.history.replaceState(
-                {},
+                window.history.state,
                 "",
-                `${window.location.pathname}?meta=${meta}`
+                `${parentReferencePath}?meta=${encodedMeta}`
             );
         }
     }
 
+    /**
+     * This method gets called when the user navigates back and forth using browser arrows
+     * Updates content depending on the type of reference - spec based or markdown
+     */
+    protected updateSelectedItemFromUrlQuery(): void {
+        const specBasedReference = this.isSpecBasedReference(
+            this._currentReferenceId
+        );
+        if (specBasedReference) {
+            const currentMeta: RouteMeta | undefined =
+                this.getReferenceMetaInfo(window.location.href);
+            const metadata =
+                currentMeta && this.getMetadataByUrlQuery(currentMeta);
+            if (metadata) {
+                const {
+                    parentReferencePath,
+                    referenceId,
+                    amfId,
+                    type,
+                    elementId
+                }: AmfMetadataTopic = metadata;
+                this.loadSpecReferenceContent(
+                    parentReferencePath,
+                    referenceId,
+                    amfId,
+                    type,
+                    elementId,
+                    currentMeta.meta
+                );
+            }
+        } else {
+            this.loadMarkdownBasedReference();
+        }
+
+        restoreScroll(); // don't try this at home kids
+    }
+
+    /**
+     * The API Navigation event will always intend to navigate within the current reference
+     * @param event
+     */
+    protected onApiNavigationChanged(): void {
+        const specBasedReference = this.isSpecBasedReference(
+            this._currentReferenceId
+        );
+        if (specBasedReference) {
+            const { meta } = this.selectedTopic!;
+            const metadata = this.metadata[meta];
+            if (metadata) {
+                const {
+                    parentReferencePath,
+                    referenceId,
+                    amfId,
+                    type,
+                    elementId
+                }: AmfMetadataTopic = metadata;
+                this.loadSpecReferenceContent(
+                    parentReferencePath,
+                    referenceId,
+                    amfId,
+                    type,
+                    elementId,
+                    metadata.meta
+                );
+            }
+        } else {
+            this.loadMarkdownBasedReference();
+        }
+    }
+
     /**
      * Updates the currently selected amf and topic
      */
-    protected loadContent(
+    protected loadSpecReferenceContent(
+        parentReferencePath: string,
         referenceId: string,
         amfId: string,
         type: string,
-        elementId = "",
-        meta = ""
+        elementId: string,
+        meta: string
     ): void {
         this.selectedTopic = {
             referenceId,
+            parentReferencePath,
             amfId,
             elementId,
             type,
             meta
         };
-        this.selectedSidebarValue = this.getReferencePathWithMeta(meta);
+        this.selectedSidebarValue = this.getReferencePathWithMeta(
+            parentReferencePath,
+            meta
+        );
 
         this.handleSelectedItem();
 
-        // Ensures that the URL always has the meta, that way we don't get two history entries for summary
-        this.replaceUrlWithSelected(meta);
         this.updateDocPhase();
     }
 
@@ -696,10 +976,9 @@ export default class AmfReference extends LightningElement {
         /* If parent level doc phase is enabled, Individual reference level doc phase should not be considered */
 
         if (!this.isParentLevelDocPhaseEnabled) {
-            const referenceId = this.selectedTopic?.referenceId;
-            const selectedReference = this._amfConfig.find(
+            const selectedReference = this._amfConfigList.find(
                 (referenceItem: AmfConfig) => {
-                    return referenceItem.id === referenceId;
+                    return referenceItem.id === this._currentReferenceId;
                 }
             );
             if (selectedReference) {
@@ -711,103 +990,505 @@ export default class AmfReference extends LightningElement {
     }
 
     /**
-     * Updates the DOM on first load
+     * Returns the decoded meta query param from given Url as it is being used internally.
+     */
+    getMetaFromUrl(referenceUrl: string): string {
+        const indexOfQueryParam = referenceUrl.indexOf("?");
+        const urlPath = referenceUrl.substring(
+            indexOfQueryParam >= 0 ? indexOfQueryParam : referenceUrl.length
+        );
+        const meta = this.parseParams(urlPath).meta as string;
+        // Always get the meta query param encoded and decode it and store it for internal use
+        // This has 2 advantages,
+        // 1. Supports backward compatible meta query param, so there is no need for redirects.
+        // 2. Supports Prerender and Coveo for their crawling.
+        const encodedMeta = meta && this.getUrlEncoded(meta);
+        const decodedMeta = encodedMeta && decodeURIComponent(encodedMeta);
+        return decodedMeta || "";
+    }
+
+    /**
+     *
+     * @returns meta for given markdown based referenceUrl
+     * Consider last topic url in ../references/reference-name/example.html
+     */
+    getMarkdownReferenceMeta(referenceUrl: string): string {
+        let meta = "";
+        if (referenceUrl) {
+            const slashSeparatorItems = referenceUrl.split("/");
+            const lastItem =
+                slashSeparatorItems[slashSeparatorItems.length - 1];
+            if (lastItem.endsWith(".html")) {
+                meta = lastItem;
+            }
+        }
+        return meta;
+    }
+
+    /**
+     * Gets the encoded url.
+     * This method will return the encoded url for 2 cases,
+     * 1. If the url is encoded already
+     * 2. If the url is decoded
+     */
+    getUrlEncoded(url: string): string {
+        // if url matches, then return the encoded url.
+        if (decodeURIComponent(url) === url) {
+            return encodeURIComponent(url);
+        }
+        // return the encoded url.
+        return this.getUrlEncoded(decodeURIComponent(url));
+    }
+
+    /**
+     *
+     * @returns RouteMeta object for given referenceUrl
+     * referenceId - gets referenceId from url
+     * For spec based references gets meta parm from url and then topicId & type from meta
+     * For markdown based references gets topicId as last html path in the name, meta & type will be empty
+     */
+    getReferenceMetaInfo(referenceUrl: string | null): RouteMeta | undefined {
+        let metaReferenceInfo;
+        if (referenceUrl) {
+            const referenceId = this.getReferenceIdFromUrl(referenceUrl);
+            let meta = "";
+            let topicId = "";
+            let type = "";
+            if (this.isSpecBasedReference(referenceId)) {
+                meta = this.getMetaFromUrl(referenceUrl);
+                if (meta) {
+                    if (meta.includes(":")) {
+                        const metaInfo = meta.split(":");
+                        type = metaInfo[0];
+                        topicId = metaInfo[1] || type;
+                    } else {
+                        topicId = meta;
+                    }
+                }
+            } else {
+                topicId = this.getMarkdownReferenceMeta(referenceUrl);
+            }
+            metaReferenceInfo = {
+                referenceId,
+                meta,
+                topicId,
+                type
+            };
+        }
+        return metaReferenceInfo;
+    }
+
+    /**
+     * Finds and returns referenceUrl and topicTitle if given topic url matches
+     */
+    getReferenceDetailsInGivenTopics(
+        topics: ParsedMarkdownTopic[],
+        topicMeta: string
+    ): { referenceUrl: string; topicTitle: string } {
+        let referenceUrl = "";
+        let topicTitle = "";
+        for (let i = 0; i < topics.length; i++) {
+            const topic = topics[i];
+            const meta = this.getMarkdownReferenceMeta(topic.link!.href);
+            const childTopics = topic.children;
+            if (meta === topicMeta) {
+                referenceUrl = topic.link!.href;
+                topicTitle = topic.label;
+            } else if (childTopics && childTopics.length) {
+                const referenceDetails = this.getReferenceDetailsInGivenTopics(
+                    childTopics,
+                    topicMeta
+                );
+                referenceUrl = referenceDetails.referenceUrl;
+                topicTitle = referenceDetails.topicTitle;
+            }
+            if (referenceUrl && topicTitle) {
+                break;
+            }
+        }
+        return {
+            referenceUrl,
+            topicTitle
+        };
+    }
+
+    /**
+     * Gives referenceUrl and topicTitle for given markdown topic url
+     */
+    getRefDetailsForGivenTopicMeta(
+        referenceId: string,
+        topicMeta: string
+    ): { referenceUrl: string; topicTitle: string } | undefined {
+        const amfConfig = this.getAmfConfigWithId(referenceId);
+        let referenceDetails;
+        if (amfConfig) {
+            const topics = amfConfig.topic?.children || [];
+            referenceDetails = this.getReferenceDetailsInGivenTopics(
+                topics,
+                topicMeta
+            );
+        }
+        return referenceDetails;
+    }
+
+    /**
+     * Updates the DOM on the first load
      */
     updateView(): void {
+        const previousRefUrlInSession = window.sessionStorage.getItem(
+            this.docsReferenceUrlSessionKey
+        );
+        window.sessionStorage.removeItem(this.docsReferenceUrlSessionKey);
+        let previousRefInfo = this.getReferenceMetaInfo(
+            previousRefUrlInSession
+        );
+
+        // For spec based reference, We should consider urlData to show same topic when user reloads after navigating to specific topic
+        if (!previousRefInfo) {
+            const currentUrl = window.location.href;
+            const urlReferenceId = this.getReferenceIdFromUrl(currentUrl);
+            if (urlReferenceId && this.isSpecBasedReference(urlReferenceId)) {
+                if (
+                    !this.isProjectRootPath() &&
+                    !this.isParentReferencePath(currentUrl)
+                ) {
+                    previousRefInfo = this.getReferenceMetaInfo(currentUrl);
+                }
+            }
+        }
+
         let referenceId: string;
         let topicId = "";
-        const previousRefMetaInSession = window.sessionStorage.getItem(
-            this.docsReferenceMetaSessionKey
-        );
-        window.sessionStorage.removeItem(this.docsReferenceMetaSessionKey);
-        const currentMeta = this.getCurrentRefMeta(previousRefMetaInSession);
-        if (currentMeta) {
-            referenceId = currentMeta.referenceId;
-            topicId = currentMeta.topicId;
-            if (!this.amfFetchPromiseMap[referenceId]) {
-                // This could happen if they specify a bad query value.
-                // In this case, we'll do the logic below to use the default amf
-                referenceId = null;
+
+        if (
+            previousRefInfo &&
+            this._amfConfigMap.has(previousRefInfo.referenceId)
+        ) {
+            referenceId = previousRefInfo.referenceId;
+            topicId = previousRefInfo.topicId;
+        } else {
+            referenceId = this._currentReferenceId;
+        }
+
+        const specBasedReference = this.isSpecBasedReference(referenceId);
+        if (specBasedReference) {
+            // Wait till the AMF is loaded.
+            this.amfFetchPromiseMap[referenceId].then(() => {
+                let selectedItemMetaData = this.getMetadataByIdentifier(
+                    referenceId,
+                    topicId
+                );
+                if (!selectedItemMetaData) {
+                    // Doesn't exist, let's use the summary.
+                    selectedItemMetaData = this.getMetadataByType(
+                        referenceId,
+                        "summary"
+                    );
+                }
+
+                if (selectedItemMetaData) {
+                    this.loadSpecReferenceContent(
+                        selectedItemMetaData.parentReferencePath,
+                        selectedItemMetaData.referenceId,
+                        selectedItemMetaData.amfId,
+                        selectedItemMetaData.type,
+                        "",
+                        selectedItemMetaData.meta
+                    );
+
+                    this.updateUrlWithSelected(
+                        selectedItemMetaData.parentReferencePath,
+                        selectedItemMetaData.meta
+                    );
+                    this.updateTags(selectedItemMetaData.navTitle);
+                }
+            });
+        } else {
+            let invalidTopicReferenceUrl: string | null = "";
+            if (topicId) {
+                const referenceDetails = this.getRefDetailsForGivenTopicMeta(
+                    referenceId,
+                    topicId
+                );
+                const selectedItemUrl = referenceDetails?.referenceUrl;
+                if (!selectedItemUrl) {
+                    invalidTopicReferenceUrl = previousRefUrlInSession;
+                }
             }
+            this.loadMarkdownBasedReference(invalidTopicReferenceUrl);
+        }
+    }
+
+    /**
+     * Navigates to reference of the given URL
+     * @param url
+     */
+    private loadNewReferenceItem(url: string): void {
+        const referenceId = this.getReferenceIdFromUrl(url);
+        const referenceItem = this.getAmfConfigWithId(referenceId);
+        if (referenceItem) {
+            window.location.href = referenceItem.href;
         }
+    }
 
-        if (!referenceId) {
-            referenceId = this._amfConfig[0].id;
-            if (!this.amfFetchPromiseMap[referenceId]) {
-                // This should never happen.
-                referenceId = Object.keys(this.amfFetchPromiseMap)[0];
+    /**
+     * @param referenceUrl to which user wants to navigate
+     * Redirect to first sub item if it's root level item, otherwise content will be loaded
+     * Push the history as a first child item
+     * set selected sidebar value as a pathname
+     */
+
+    private loadMarkdownBasedReference(referenceUrl?: string | null): void {
+        // MILES TODO: figure out if we ever need to log a coveo page view in here
+        // this would be the case if at some point we 'load' a new 'markdown based reference'
+        // without actually triggering a page load
+        let referenceId = "";
+        const currentUrl = window.location.href;
+        if (this.isProjectRootPath()) {
+            /**
+             * CASE1: This case is to consider when the user navigates to references by clicking a project card
+             * Ex: /docs/example-project/references should navigate to the first topic in the first reference
+             */
+            referenceId = this._currentReferenceId;
+        } else if (this.isParentReferencePath(referenceUrl)) {
+            /**
+             * CASE2: This case is to navigate to respective reference when the user clicked on root item
+             * Ex: .../references/markdown-ref should navigate to first topic.
+             */
+            referenceId = this.getReferenceIdFromUrl(referenceUrl!);
+        } else if (this.isParentReferencePath(currentUrl)) {
+            /**
+             * CASE3: This case is to navigate to respective reference when the user entered url with reference id
+             * Ex: .../references/markdown-ref should navigate to first topic.
+             */
+            referenceId = this.getReferenceIdFromUrl(currentUrl);
+        } else if (referenceUrl) {
+            /**
+             * CASE4: This case is to navigate to first item when we don't have topic in the selected version
+             * Ex: .../references/markdown-ref/not-existed-topic-url should navigate to first topic.
+             */
+            const referenceMeta = this.getMarkdownReferenceMeta(referenceUrl);
+            const selectedItemRefId = this.getReferenceIdFromUrl(referenceUrl);
+            const referenceDetails = this.getRefDetailsForGivenTopicMeta(
+                selectedItemRefId,
+                referenceMeta
+            );
+            const selectedItemUrl = referenceDetails?.referenceUrl;
+            if (!selectedItemUrl) {
+                referenceId = this.getReferenceIdFromUrl(referenceUrl);
             }
         }
 
-        // Wait till the AMF is loaded.
-        this.amfFetchPromiseMap[referenceId].then(() => {
-            let topic = this.getMetadataByIdentifier(referenceId, topicId);
-            if (!topic) {
-                // Doesn't exist, let's use the summary.
-                topic = this.getMetadataByType(referenceId, "summary");
+        let isRedirecting = false;
+        if (referenceId) {
+            const amfConfig = this.getAmfConfigWithId(referenceId);
+            let redirectReferenceUrl = "";
+            if (amfConfig) {
+                const childrenItems = amfConfig.topic!.children;
+                if (childrenItems.length > 0) {
+                    redirectReferenceUrl = childrenItems[0].link!.href;
+                }
+            }
+            if (redirectReferenceUrl) {
+                if (this.isParentReferencePath(referenceUrl)) {
+                    // This is for CASE2 mentioned above, Where we need to navigate user to respective href
+                    isRedirecting = true;
+                    window.location.href = redirectReferenceUrl;
+                } else {
+                    // This is for CASE 1,3 and 4 mentioned above, Where we need to update the browser history
+                    window.history.replaceState(
+                        window.history.state,
+                        "",
+                        redirectReferenceUrl
+                    );
+                }
+            }
+        }
+        if (!isRedirecting) {
+            const currentReferenceUrl = window.location.href;
+            const referenceMeta =
+                this.getMarkdownReferenceMeta(currentReferenceUrl);
+            const selectedItemRefId =
+                this.getReferenceIdFromUrl(currentReferenceUrl);
+            const referenceDetails = this.getRefDetailsForGivenTopicMeta(
+                selectedItemRefId,
+                referenceMeta
+            );
+            if (referenceDetails) {
+                this.updateTags(referenceDetails.topicTitle);
             }
 
-            if (topic) {
-                this.loadContent(
-                    topic.referenceId,
-                    topic.amfId,
-                    topic.type,
-                    "",
-                    topic.meta
-                );
+            this.versions = this.getVersions();
+            if (this.oldVersionInfo) {
+                this.showVersionBanner = true;
+            } else {
+                this.latestVersion = true;
             }
-        });
+
+            this.isVersionFetched = true;
+            this.updateDocPhase();
+            this.selectedSidebarValue = window.location.pathname;
+        }
     }
 
     /**
-     * Currently, used to handle the version change and storing the current meta query param to the session storage.
+     * Currently, used to handle the version change and store the current reference Url.
      */
     handleVersionChange(): void {
-        const path = window.location.search;
-        const urlParams = this.parseParams(path);
-        const meta = urlParams.meta as string;
-        if (meta) {
-            window.sessionStorage.setItem(
-                this.docsReferenceMetaSessionKey,
-                meta
-            );
+        const currentUrl = window.location.href;
+        window.sessionStorage.setItem(
+            this.docsReferenceUrlSessionKey,
+            currentUrl
+        );
+    }
+
+    handleDismissVersionBanner() {
+        this.showVersionBanner = false;
+    }
+
+    private updateTags(navTitle = ""): void {
+        if (!navTitle) {
+            return;
+        }
+
+        // this is required to update the nav title meta tag.
+        // eslint-disable-next-line @lwc/lwc/no-document-query
+        const metaNavTitle = document.querySelector('meta[name="nav-title"]');
+        // eslint-disable-next-line @lwc/lwc/no-document-query
+        const titleTag = document.querySelector("title");
+        const TITLE_SEPARATOR = " | ";
+
+        if (metaNavTitle) {
+            metaNavTitle.setAttribute("content", navTitle);
+        }
+
+        /**
+         * Right now, the title tag only changes when you pick a Ref spec,
+         * not every time you choose a subsection of the Ref spec.
+         * This update aims to refresh the title tag with each selection.
+         * If a Ref spec is chosen, we add the value of the <selected topic> to the title.
+         * If a subsection is selected, we update the first part of the current
+         * title with the new <selected topic>.
+         * Example: Following is a sample project structure.
+         * - Project Name
+         *  - Ref Spec1
+         *      - Summary
+         *      - Endpoints
+         *          - E1
+         *          - E2
+         *  - Ref Spec2
+         *      - Summary
+         *      - Endpoints
+         *          - E1 (Selected)
+         *          - E2
+         * Previous Title: Ref Spec2 | Project Name | Salesforce Developer
+         * New Title: E1 | Ref Spec2 | Project Name | Salesforce Developer
+         *
+         */
+        if (titleTag) {
+            let titleTagValue = titleTag.textContent;
+            const titleTagSectionValues: string[] =
+                titleTagValue?.split(TITLE_SEPARATOR);
+            if (titleTagSectionValues) {
+                if (titleTagSectionValues.length <= 3) {
+                    titleTagValue = navTitle + TITLE_SEPARATOR + titleTagValue;
+                } else {
+                    titleTagSectionValues[0] = navTitle;
+                    titleTagValue = titleTagSectionValues.join(TITLE_SEPARATOR);
+                }
+            }
+            titleTag.textContent = titleTagValue;
         }
     }
 
     onNavSelect(event: CustomEvent): void {
         const name = event.detail.name;
-        const indexOfQueryParam = name.indexOf("?");
-        const urlPath = name.substring(
-            indexOfQueryParam >= 0 ? indexOfQueryParam : name.length
-        );
-        const metaVal = this.parseParams(urlPath).meta as string;
-        const currentSelectedMeta = this.selectedTopic.meta;
+        if (name) {
+            const urlReferenceId = this.getReferenceIdFromUrl(name);
+            const specBasedReference =
+                this.isSpecBasedReference(urlReferenceId);
+            if (specBasedReference) {
+                const metaVal = this.getMetaFromUrl(name);
+                const currentSelectedMeta = this.selectedTopic
+                    ? this.selectedTopic.meta
+                    : "";
+
+                if (metaVal && metaVal === currentSelectedMeta) {
+                    // selecting the same nav item, skip update
+                    return;
+                }
 
-        if (metaVal === currentSelectedMeta) {
-            // selecting the same nav item, skip update
-            return;
+                const metadata = this.metadata[metaVal];
+                if (metadata) {
+                    const {
+                        parentReferencePath,
+                        referenceId,
+                        amfId,
+                        type,
+                        elementId
+                    } = metadata;
+                    this.loadSpecReferenceContent(
+                        parentReferencePath,
+                        referenceId,
+                        amfId,
+                        type,
+                        elementId,
+                        metaVal
+                    );
+
+                    logCoveoPageView(
+                        this.coveoOrganizationId,
+                        this.coveoAnalyticsToken
+                    );
+                    this.updateUrlWithSelected(parentReferencePath, metaVal);
+                    this.updateTags(metadata.navTitle);
+                } else {
+                    if (this.isParentReferencePath(name)) {
+                        this.loadNewReferenceItem(name);
+                    }
+                }
+            } else {
+                this.loadMarkdownBasedReference(name);
+            }
         }
+    }
 
-        const metadata = this.metadata[metaVal];
-        if (metadata) {
-            const { referenceId, amfId, type, elementId } = metadata;
-            this.loadContent(referenceId, amfId, type, elementId, metaVal);
-            this.updateUrlWithSelected(metaVal);
+    onExpandCollapse(event: CustomEvent): void {
+        const { name, isSelectAction, isExpanded } = event.detail;
+        if (!isSelectAction && isExpanded) {
+            const referenceId = this.getReferenceIdFromUrl(name);
+            const currentUrl = window.location.href;
+            const currentReferenceId = this.getReferenceIdFromUrl(currentUrl);
+            //No need to do anything if user is expanding currently selected reference
+            if (referenceId !== currentReferenceId) {
+                const isSpecBasedReference =
+                    this.isSpecBasedReference(referenceId);
+                if (isSpecBasedReference) {
+                    // Perform functionality same as item selection
+                    this.onNavSelect(event);
+                }
+            }
         }
     }
 
     handleSelectedItem(): void {
         // update topic view
-        const { referenceId, amfId, type } = this.selectedTopic;
+        const { referenceId, amfId, type } = this.selectedTopic!;
+
+        // Adding stringify inside try/catch
+        let amfModelString = "";
+        try {
+            amfModelString = JSON.stringify(this.amfMap[referenceId].model);
+        } catch (error) {
+            console.error(`Error stringifying amf model: ${error}`);
+        }
 
         // This updates the component in the content section.
         this.topicModel = {
             type,
-            amf: this.amfMap[referenceId].model,
+            amf: amfModelString,
             parser: this.amfMap[referenceId].parser,
             id: amfId
         };
-
-        window.scrollTo({ top: 0, behavior: "smooth" });
     }
 }