diff --git a/web/src/components/DocumentControlButtons.tsx b/web/src/components/DocumentControlButtons.tsx
index 8a808ff48..fc4ea54a5 100644
--- a/web/src/components/DocumentControlButtons.tsx
+++ b/web/src/components/DocumentControlButtons.tsx
@@ -31,7 +31,7 @@ export default function DocumentControlButtons (props: Props): JSX.Element {
         <Select
           className={styles['version-select']}
           onChange={(e) => { props.onVersionChange(e.target.value) }}
-          value={props.versions.length > 0 ? props.version : ''}
+          value={props.versions.find(v => v.name === props.version) !== undefined ? props.version : ''}
         >
           {props.versions
             .filter((v) => !v.hidden || v.name === props.version)
diff --git a/web/src/components/IFrame.tsx b/web/src/components/IFrame.tsx
new file mode 100644
index 000000000..349675c47
--- /dev/null
+++ b/web/src/components/IFrame.tsx
@@ -0,0 +1,95 @@
+import React, { useRef } from 'react'
+import { uniqueId } from 'lodash'
+
+import styles from '../style/components/IFrame.module.css'
+interface Props {
+  src: string
+  onPageChanged: (page: string, hash: string) => void
+  onHashChanged: (hash: string) => void
+}
+
+export default function IFrame(props: Props): JSX.Element {
+  const iFrameRef = useRef<HTMLIFrameElement>(null)
+
+  const onIframeLoad = (): void => {
+    if (iFrameRef.current == null) {
+      console.error('iFrameRef is null')
+      return
+    }
+
+    // remove the hashchange event listener to prevent memory leaks
+    iFrameRef.current.contentWindow?.removeEventListener('hashchange', hashChangeEventListener)
+
+    const url = iFrameRef.current?.contentDocument?.location.href
+    if (url == null) {
+      console.warn('IFrame onload event triggered, but url is null')
+      return
+    }
+
+    // make all external links in iframe open in new tab
+    // and make internal links replace the iframe url so that change
+    // doesn't show up in the page history (we'd need to click back twice)
+    iFrameRef.current.contentDocument
+      ?.querySelectorAll('a')
+      .forEach((a: HTMLAnchorElement) => {
+        if (!a.href.startsWith(window.location.origin)) {
+          a.setAttribute('target', '_blank')
+          return
+        }
+
+        if (a.href.trim() === '') {
+          // ignore empty links, may be handled with js internally,
+          // so we'll ignore it. Will inevitably cause the user to have to click back
+          // multiple times to get back to the previous page.
+          return
+        }
+
+        // From here: https://www.ozzu.com/questions/358584/how-do-you-ignore-iframes-javascript-history
+        a.onclick = () => {
+          iFrameRef.current?.contentWindow?.location.replace(a.href)
+          return false
+        }
+      })
+
+    // Add the event listener again
+    iFrameRef.current.contentWindow?.addEventListener('hashchange', hashChangeEventListener)
+
+    const parts = url.split('/doc/').slice(1).join('/doc/').split('/')
+    const urlPageAndHash = parts.slice(2).join('/')
+    const hashIndex = urlPageAndHash.includes('#') ? urlPageAndHash.indexOf('#') : urlPageAndHash.length
+    const urlPage = urlPageAndHash.slice(0, hashIndex)
+    const urlHash = urlPageAndHash.slice(hashIndex)
+
+    props.onPageChanged(urlPage, urlHash)
+  }
+
+  const hashChangeEventListener = (): void => {
+    if (iFrameRef.current == null) {
+      console.error('hashChangeEvent from iframe but iFrameRef is null')
+      return
+    }
+
+    const url = iFrameRef.current?.contentDocument?.location.href
+    if (url == null) {
+      return
+    }
+
+    let hash = url.split('#')[1]
+    if (hash !== null) {
+      hash = `#${hash}`
+    } else {
+      hash = ''
+    }
+
+    props.onHashChanged(hash)
+  }
+
+  return (<iframe
+    ref={iFrameRef}
+    key={uniqueId()}
+    className={styles['docs-iframe']}
+    src={props.src}
+    title="docs"
+    onLoad={onIframeLoad}
+  />)
+}
diff --git a/web/src/data-providers/MessageBannerProvider.tsx b/web/src/data-providers/MessageBannerProvider.tsx
index 80db2a880..940274c18 100644
--- a/web/src/data-providers/MessageBannerProvider.tsx
+++ b/web/src/data-providers/MessageBannerProvider.tsx
@@ -15,11 +15,15 @@ export interface Message {
 
 interface MessageBannerState {
   showMessage: (message: Message) => void
+  clearMessages: () => void
 }
 
 export const Context = React.createContext<MessageBannerState>({
   showMessage: (): void => {
     console.warn('MessageBannerProvider not initialized')
+  },
+  clearMessages: (): void => {
+    console.warn('MessageBannerProvider not initialized')
   }
 })
 
@@ -59,8 +63,20 @@ export function MessageBannerProvider ({ children }: any): JSX.Element {
     setLastTimeout(newTimeout)
   }, [])
 
+  const clearMessages = useCallback(() => {
+    if (lastTimeout !== undefined) {
+      clearTimeout(lastTimeout)
+    }
+
+    setMessage({
+      content: undefined,
+      type: 'success',
+      showMs: 6000
+    })
+  }, [])
+
   return (
-    <Context.Provider value={{ showMessage }}>
+    <Context.Provider value={{ showMessage, clearMessages }}>
       <Banner message={message} />
       {children}
     </Context.Provider>
diff --git a/web/src/pages/Docs.tsx b/web/src/pages/Docs.tsx
index c86a26b7d..3d56f9486 100644
--- a/web/src/pages/Docs.tsx
+++ b/web/src/pages/Docs.tsx
@@ -1,187 +1,74 @@
-/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call */
-/*
-  the iFrameRef is not really compatiple with ts,
-*/
-
-import React, { useEffect, useRef, useMemo, useState } from 'react'
-import { useLocation, useParams, useSearchParams, useNavigate } from 'react-router-dom'
-import DocumentControlButtons from '../components/DocumentControlButtons'
-import type ProjectDetails from '../models/ProjectDetails'
+import React, { useEffect, useMemo, useState, useRef } from 'react'
 import ProjectRepository from '../repositories/ProjectRepository'
-
+import type ProjectDetails from '../models/ProjectDetails'
 import LoadingPage from './LoadingPage'
 import NotFound from './NotFound'
-
-import styles from './../style/pages/Docs.module.css'
-import { uniqueId } from 'lodash'
+import DocumentControlButtons from '../components/DocumentControlButtons'
+import IFrame from '../components/IFrame'
+import { useLocation, useParams, useSearchParams } from 'react-router-dom'
 import { useMessageBanner } from '../data-providers/MessageBannerProvider'
 
 export default function Docs (): JSX.Element {
+  const params = useParams()
+  const searchParams = useSearchParams()[0]
   const location = useLocation()
-  const navigate = useNavigate()
-
-  const projectParam = useParams().project ?? ''
-  const versionParam = useParams().version ?? 'latest'
-  const pageParam = useParams().page ?? 'index.html'
-  const hashParam = useLocation().hash.split('?')[0] ?? ''
-  const hideUiParam = useSearchParams()[0].get('hide-ui') === 'true' || useLocation().hash.split('?')[1] === 'hide-ui=true'
-
-  const [project, setProject] = useState<string>('')
-  const [version, setVersion] = useState<string>('')
-  const [page, setPage] = useState<string>('')
-  const [hash, setHash] = useState<string>('')
-  const [hideUi, setHideUi] = useState<boolean>(false)
+  const { showMessage, clearMessages } = useMessageBanner()
 
   const [versions, setVersions] = useState<ProjectDetails[]>([])
   const [loadingFailed, setLoadingFailed] = useState<boolean>(false)
 
-  const { showMessage } = useMessageBanner()
-  const iFrameRef = useRef<HTMLIFrameElement>(null)
-
-  const iFrame = useMemo(() => {
-    return (<iframe
-      ref={iFrameRef}
-      key={uniqueId()}
-      src={ProjectRepository.getProjectDocsURL(project, version, page, hash)}
-      title="docs"
-      className={styles['docs-iframe']}
-      onLoad={() => {
-        if (iFrameRef.current == null) {
-          console.error('iFrameRef is null')
-          return
-        }
-
-        // @ts-expect-error ts can't find contentWindow
-        onIFrameLocationChanged(iFrameRef.current.contentWindow.location.href)
-      }}
-    />
-    )
-  }, [project, version])
-
-  document.title = `${project} | docat`
-
-  if (projectParam === '') {
-    setLoadingFailed(true)
-  }
-
-  const updateURL = (newProject: string, newVersion: string, newPage: string, newHash: string, newHideUi: boolean, historyMode: 'push' | 'replace' | 'skip'): void => {
-    const url = `/${newProject}/${newVersion}/${newPage}${newHash}${newHideUi ? '?hide-ui=true' : ''}`
-
-    if (project === newProject && version === newVersion && page === newPage && hash === newHash && hideUi === newHideUi) {
-      // no change
-      return
-    }
-
-    setProject(newProject)
-    setVersion(newVersion)
-    setPage(newPage)
-    setHash(newHash)
-    setHideUi(newHideUi)
-
-    if (historyMode === 'skip') {
-      return
-    }
-
-    if (historyMode === 'replace') {
-      navigate(url, { replace: true })
-      return
-    }
-
-    navigate(url)
-  }
-
-  /**
-   * Event listener for the hashchange event of the iframe
-   * updates the url of the page to match the iframe
-   */
-  const hashChangeEventListener = (): void => {
-    if (iFrameRef.current == null) {
-      console.error('hashChangeEvent from iframe but iFrameRef is null')
-      return
-    }
+  const project = useRef(params.project ?? '')
+  const page = useRef(params.page ?? 'index.html')
+  const hash = useRef(location.hash.split('?')[0] ?? '')
 
-    // @ts-expect-error - ts does not find the window on the iframe
-    iFrameRef.current.contentWindow.removeEventListener('hashchange', hashChangeEventListener)
+  const [version, setVersion] = useState<string>(params.version ?? 'latest')
+  const [hideUi, setHideUi] = useState<boolean>(searchParams.get('hide-ui') === 'true' || location.hash.split('?')[1] === 'hide-ui=true')
+  const [iframeUpdateTrigger, setIframeUpdateTrigger] = useState<number>(0)
 
-    const url = iFrameRef.current?.contentDocument?.location.href
-
-    onIFrameLocationChanged(url)
-  }
-
-  const onIFrameLocationChanged = (url?: string): void => {
-    if (url == null) {
-      return
-    }
-
-    url = url.split('/doc/')[1]
-    if (url == null) {
-      console.error('IFrame URL did not contain "/doc/"')
-      return
-    }
-
-    // make all external links in iframe open in new tab
-    // @ts-expect-error - ts does not find the document on the iframe
-    iFrameRef.current.contentDocument
-      .querySelectorAll('a')
-      .forEach((a: HTMLAnchorElement) => {
-        if (!a.href.startsWith(window.location.origin)) {
-          a.setAttribute('target', '_blank')
-        }
-      })
-
-    const parts = url.split('/')
-    const urlProject = parts[0]
-    const urlVersion = parts[1]
-    const urlPageAndHash = parts.slice(2).join('/')
-    const hashIndex = urlPageAndHash.includes('#') ? urlPageAndHash.indexOf('#') : urlPageAndHash.length
-    const urlPage = urlPageAndHash.slice(0, hashIndex)
-    const urlHash = urlPageAndHash.slice(hashIndex)
-
-    if (urlProject !== project || urlVersion !== version || urlPage !== page || urlHash !== hash) {
-      updateURL(urlProject, urlVersion, urlPage, urlHash, hideUi, 'push')
-    }
-
-    // add event listener for hashchange to iframe
-    // this is needed because the iframe doesn't trigger the hashchange event otherwise
-    // @ts-expect-error - ts does not find the window on the iframe
-    iFrameRef.current.contentWindow.addEventListener('hashchange', hashChangeEventListener)
-  }
+  // This provides the url for the iframe.
+  // It is always the same, except when the version changes,
+  // as this memo will trigger a re-render of the iframe, which
+  // is not needed when only the page or hash changes, because
+  // the iframe keeps track of that itself.
+  const iFrameSrc = useMemo(() => {
+    return ProjectRepository.getProjectDocsURL(project.current, version, page.current, hash.current)
+  }, [version, iframeUpdateTrigger])
 
   useEffect(() => {
-    if (project === '') {
+    if (project.current === '') {
       return
     }
 
     void (async (): Promise<void> => {
       try {
-        let allVersions = await ProjectRepository.getVersions(project)
-
+        let allVersions = await ProjectRepository.getVersions(project.current)
         if (allVersions.length === 0) {
           setLoadingFailed(true)
           return
         }
 
         allVersions = allVersions.sort((a, b) => ProjectRepository.compareVersions(a, b))
-        let versionToUse = ''
+        setVersions(allVersions)
 
+        const latestVersion = ProjectRepository.getLatestVersion(allVersions).name
         if (version === 'latest') {
-          versionToUse = ProjectRepository.getLatestVersion(allVersions).name
-        } else {
-          // custom version -> check if it exists
-          const versionsAndTags = allVersions.map((v) => [v.name, ...v.tags]).flat()
-          if (!versionsAndTags.includes(version)) {
-            // version does not exist -> fail
-            setLoadingFailed(true)
-            console.error("Version doesn't exist")
+          if (latestVersion === 'latest') {
             return
           }
+          setVersion(latestVersion)
+          return
+        }
 
-          versionToUse = version
+        // custom version -> check if it exists
+        // if it does. do nothing, as it should be set already
+        const versionsAndTags = allVersions.map((v) => [v.name, ...v.tags]).flat()
+        if (versionsAndTags.includes(version)) {
+          return
         }
 
-        updateURL(project, versionToUse, page, hash, hideUi, 'replace')
-        setVersions(allVersions)
-        setLoadingFailed(false)
+        // version does not exist -> fail
+        setLoadingFailed(true)
+        console.error(`Version '${version}' doesn't exist`)
       } catch (e) {
         console.error(e)
         setLoadingFailed(true)
@@ -189,10 +76,78 @@ export default function Docs (): JSX.Element {
     })()
   }, [project])
 
+  /** Encodes the url for the current page, and escapes the path part to avoid
+   * redirecting to escapeSlashForDocsPath.
+   * @example
+   * getUrl('project', 'version', 'path/to/page.html', '#hash', false) -> '#/project/version/path%2Fto%2Fpage.html#hash'
+   */
+  const getUrl = (project: string, version: string, page: string, hash: string, hideUi: boolean): string => {
+    return `#/${project}/${version}/${encodeURIComponent(page)}${hash}${hideUi ? '?hide-ui=true' : ''}`
+  }
+
+  const updateUrl = (newVersion: string, hideUi: boolean): void => {
+    const url = getUrl(project.current, newVersion, page.current, hash.current, hideUi)
+    window.history.pushState(null, '', url)
+  }
+
+  const iFramePageChanged = (urlPage: string, urlHash: string): void => {
+    if (urlPage === page.current) {
+      return
+    }
+    page.current = urlPage
+    hash.current = urlHash
+    updateUrl(version, hideUi)
+  }
+
+  const iFrameHashChanged = (newHash: string): void => {
+    if (newHash === hash.current) {
+      return
+    }
+    hash.current = newHash
+    updateUrl(version, hideUi)
+  }
+
+  const onVersionChanged = (newVersion: string): void => {
+    if (newVersion === version) {
+      return
+    }
+    setVersion(newVersion)
+    updateUrl(newVersion, hideUi)
+  }
+
+  const onHideUi = (): void => {
+    setHideUi(true)
+    updateUrl(version, true)
+  }
+
   useEffect(() => {
+    const urlProject = params.project ?? ''
+    const urlVersion = params.version ?? 'latest'
+    const urlPage = params.page ?? 'index.html'
+    const urlHash = location.hash.split('?')[0] ?? ''
+    const urlHideUi = searchParams.get('hide-ui') === 'true' || location.hash.split('?')[1] === 'hide-ui=true'
+
     // update the state to the url params on first loadon
-    if (projectParam !== project || versionParam !== version || pageParam !== page || hashParam !== hash || hideUiParam !== hideUi) {
-      updateURL(projectParam, versionParam, pageParam, hashParam, hideUiParam, 'replace')
+    if (urlProject !== project.current) {
+      setVersions([])
+      project.current = urlProject
+    }
+
+    if (urlVersion !== version) {
+      setVersion(urlVersion)
+    }
+
+    if (urlHideUi !== hideUi) {
+      setHideUi(urlHideUi)
+    }
+
+    if (urlPage !== page.current) {
+      page.current = urlPage
+      setIframeUpdateTrigger(v => v + 1)
+    }
+    if (urlHash !== hash.current) {
+      hash.current = urlHash
+      setIframeUpdateTrigger(v => v + 1)
     }
   }, [location])
 
@@ -205,6 +160,7 @@ export default function Docs (): JSX.Element {
 
     const latestVersion = ProjectRepository.getLatestVersion(versions).name
     if (version === latestVersion) {
+      clearMessages()
       return
     }
 
@@ -215,21 +171,7 @@ export default function Docs (): JSX.Element {
     })
   }, [version, versions])
 
-  useEffect(() => {
-    const popstateListener = (): void => {
-      // Somehow clicking back once isn't enough, so we do it twice automatically.
-      window.history.back()
-      updateURL(projectParam, versionParam, pageParam, hashParam, hideUiParam, 'skip')
-    }
-
-    window.addEventListener('popstate', popstateListener)
-
-    return (): void => {
-      window.removeEventListener('popstate', popstateListener)
-    }
-  }, [])
-
-  if (loadingFailed) {
+  if (loadingFailed || project.current === '') {
     return <NotFound />
   }
 
@@ -239,15 +181,18 @@ export default function Docs (): JSX.Element {
 
   return (
     <>
-      {iFrame}
+      <IFrame
+        src={iFrameSrc}
+        onPageChanged={iFramePageChanged}
+        onHashChanged={iFrameHashChanged}
+      />
       {!hideUi && (
         <DocumentControlButtons
           version={version}
           versions={versions}
-          onVersionChange={(v) => { updateURL(project, v, page, hash, hideUi, 'push') }}
-          onHideUi={() => { updateURL(project, version, page, hash, true, 'push') }}
-        />
-      )}
+          onVersionChange={onVersionChanged}
+          onHideUi={onHideUi}
+        />)}
     </>
   )
 }
diff --git a/web/src/pages/EscapeSlashForDocsPath.tsx b/web/src/pages/EscapeSlashForDocsPath.tsx
index a81642908..822192f43 100644
--- a/web/src/pages/EscapeSlashForDocsPath.tsx
+++ b/web/src/pages/EscapeSlashForDocsPath.tsx
@@ -5,9 +5,9 @@ import React from 'react'
 /**
  * This component is used to escape slashes in the path of the docs page.
  * It replaces all slashes with "%2F" and redirects to the new path.
- * @returns <Navigate to={newLocation} />
+ * @returns <Navigate to={newLocation} replace={true}/>
  */
 export default function EscapeSlashForDocsPath (): JSX.Element {
   const location = useLocation()
-  return <Navigate to={ProjectRepository.escapeSlashesInUrl(location.pathname, location.search, location.hash)}></Navigate>
+  return <Navigate to={ProjectRepository.escapeSlashesInUrl(location.pathname, location.search, location.hash)} replace={true}></Navigate>
 }
diff --git a/web/src/style/pages/Docs.module.css b/web/src/style/components/IFrame.module.css
similarity index 99%
rename from web/src/style/pages/Docs.module.css
rename to web/src/style/components/IFrame.module.css
index 80b013863..c3b3067f8 100644
--- a/web/src/style/pages/Docs.module.css
+++ b/web/src/style/components/IFrame.module.css
@@ -22,4 +22,4 @@ iframe {
   border: none;
   overflow-y: auto;
   overflow-x: hidden;
-}
\ No newline at end of file
+}