chore: remove hash symbol from internal links

INSTUI-4750

Author: ToMESSKa

packages/__docs__/src/App/index.tsx

@@ -185,7 +185,7 @@ class App extends Component<AppProps, AppState> {
     this._defaultDocumentTitle = document.title
     this.updateKey()
 
-    window.addEventListener('hashchange', this.updateKey, false)
+    window.addEventListener('popstate', this.updateKey, false)
 
     // TODO: Replace with the Responsive component later
     // Using this method directly for now instead to avoid a call to findDOMNode
@@ -225,6 +225,13 @@ class App extends Component<AppProps, AppState> {
         })
       })
       .catch(errorHandler)
+
+    const [page] = this.getPathInfo()
+    const isHomepage = page === 'index' || typeof page === 'undefined'
+    if (isHomepage) {
+      this.setState({ showMenu: false })
+    }
+
     document.addEventListener('focusin', this.handleFocusChange)
   }
 
@@ -242,7 +249,7 @@ class App extends Component<AppProps, AppState> {
   componentWillUnmount() {
     //cancel ongoing requests
     this._controller?.abort()
-    window.removeEventListener('hashchange', this.updateKey, false)
+    window.removeEventListener('popstate', this.updateKey, false)
 
     if (this._mediaQueryListener) {
       this._mediaQueryListener.remove()
@@ -261,13 +268,51 @@ class App extends Component<AppProps, AppState> {
   }
 
   getPathInfo = () => {
-    const { hash } = window.location
+    const { hash, pathname } = window.location
+
+    // Case 1: Old hash-based routing (hash contains the main content)
+    const cleanPath = pathname.replace(/^\/+|\/+$/g, '')
+    const pathSegments = cleanPath.split('/')
 
-    const path = hash && hash.split('/')
+    // Check if the pathname is just a base path (ends with slash or has no meaningful final segment)
+    const hasSubstantialPathname =
+      pathSegments.length > 0 &&
+      pathSegments[pathSegments.length - 1] !== '' &&
+      !pathSegments.every((seg) => seg === '')
+
+    // If it's just a base path with no hash, treat as homepage
+    if ((!hasSubstantialPathname || pathname.endsWith('/')) && !hash) {
+      return ['index'] // homepage
+    }
 
-    if (path) {
-      const [page, id] = path.map((entry) => decodeURI(entry.replace('#', '')))
-      return [page, id]
+    if (
+      hash &&
+      (!hasSubstantialPathname || pathname.endsWith('/')) &&
+      hash.startsWith('#') &&
+      !hash.startsWith('##')
+    ) {
+      const path = hash.split('/')
+      if (path) {
+        const [page, id] = path.map((entry) =>
+          decodeURI(entry.replace('#', ''))
+        )
+        return [page, id]
+      }
+    }
+    // Case 2: New clean URL routing (pathname contains the main content)
+    else {
+      if (pathSegments.length > 0 && pathSegments[0] !== '') {
+        // Get the page from the last segment of the path
+        const page = pathSegments[pathSegments.length - 1]
+        // If there's a hash that's not at the beginning (like #Guidelines), use it as ID
+        let id = undefined
+        if (hash && hash.startsWith('##')) {
+          id = decodeURI(hash.replace('##', ''))
+        } else if (hash && !hash.startsWith('#/')) {
+          id = decodeURI(hash.replace('#', ''))
+        }
+        return [page, id]
+      }
     }
     return []
   }
@@ -289,7 +334,6 @@ class App extends Component<AppProps, AppState> {
 
   updateKey = () => {
     const [page, _id] = this.getPathInfo()
-
     if (page) {
       this.setState(
         ({ key, showMenu }) => ({

packages/__docs__/src/Header/index.tsx

@@ -135,7 +135,16 @@ class Header extends Component<HeaderProps> {
     const { versionsData } = this.props
     return (
       <View as="div" margin="none none medium" padding="none medium">
-        <Link href="#index" isWithinText={false} display="block">
+        <Link
+          href="index"
+          isWithinText={false}
+          display="block"
+          onClick={(e) => {
+            e.preventDefault()
+            window.history.pushState({}, '', '/')
+            window.dispatchEvent(new PopStateEvent('popstate'))
+          }}
+        >
           <View display="block" textAlign="center">
             <InlineSVG src={logo} height="6rem" fontSize="12rem" />
             <ScreenReaderContent>Instructure logo</ScreenReaderContent>

packages/__docs__/src/Nav/index.tsx

@@ -141,6 +141,17 @@ class Nav extends Component<NavProps, NavState> {
     })
   }
 
+  getEffectiveBasePath = () => {
+    const pathname = window.location.pathname
+    // Check if we're in a PR preview (path contains /pr-preview/)
+    const prPreviewMatch = pathname.match(/^(\/pr-preview\/pr-\d+)/)
+    if (prPreviewMatch) {
+      return prPreviewMatch[1]
+    }
+    // Live version - no base path
+    return ''
+  }
+
   matchQuery(str: string): boolean {
     const { query } = this.state
     return query && typeof query.test === 'function' ? query.test(str) : true
@@ -257,6 +268,15 @@ class Nav extends Component<NavProps, NavState> {
     }
   }
 
+  handleInternalNavigation = (targetPath: string, e: React.MouseEvent) => {
+    e.preventDefault()
+    this.removeFocus(e as React.MouseEvent<ViewOwnProps>)
+    const basePath = this.getEffectiveBasePath()
+    const newUrl = basePath ? `${basePath}/${targetPath}` : `/${targetPath}`
+    window.history.pushState({}, '', newUrl)
+    window.dispatchEvent(new PopStateEvent('popstate'))
+  }
+
   renderDocLink(docId: string) {
     const { docs, selected } = this.props
     const docSelected = docId === selected
@@ -283,9 +303,9 @@ class Nav extends Component<NavProps, NavState> {
           />
         )}
         <Link
-          onClick={this.removeFocus}
+          onClick={(e: any) => this.handleInternalNavigation(docId, e)}
           display="block"
-          href={`#${docId}`}
+          href={`/${docId}`} // Keep href simple
           isWithinText={false}
         >
           {docs[docId].title}
@@ -451,9 +471,9 @@ class Nav extends Component<NavProps, NavState> {
           >
             <Link
               display="block"
-              onClick={this.removeFocus}
+              onClick={(e: any) => this.handleInternalNavigation(themeKey, e)}
               isWithinText={false}
-              href={`#${themeKey}`}
+              href={`/${themeKey}`}
             >
               {themeKey}
             </Link>
@@ -479,9 +499,9 @@ class Nav extends Component<NavProps, NavState> {
     const themes = this.renderThemes()
     const icons = (
       <NavToggle
-        key={'icons'}
-        summary={'Icons'}
-        href="#icons"
+        summary="Icons"
+        onToggle={(e: any) => this.handleInternalNavigation('icons', e)}
+        href="icons"
         shouldBlur={true}
       />
     )

packages/__docs__/src/compileMarkdown.tsx

@@ -272,7 +272,19 @@ const renderer = (title: string) => ({
   heading: (text: string, level: number) =>
     headingVariants[`h${level}`]?.(uuid(), text),
   link: (href: string, text: string) => (
-    <Link key={uuid()} href={href}>
+    <Link
+      key={uuid()}
+      href={href}
+      onClick={(e: any) => {
+        e.preventDefault()
+        const basePath =
+          window.location.pathname.match(/^(\/pr-preview\/pr-\d+)/)?.[1] || ''
+        const newUrl = basePath ? `${basePath}/${href}` : `/${href}`
+        window.history.pushState({}, '', newUrl)
+        window.dispatchEvent(new PopStateEvent('popstate'))
+      }}
+      isWithinText={false}
+    >
       {text}
     </Link>
   )

packages/__docs__/webpack.config.mjs

@@ -59,6 +59,7 @@ const config = merge(baseConfig, {
       directory: outputPath,
     },
     host: '0.0.0.0',
+    historyApiFallback: true,
     onListening: function () {
       // devServer is watching source files by default and hot reloading the docs page if they are changed
       // however markdown files (i.e. README.md) need to be recompiled hence the need for chokidar