diff --git a/packages/nextra-theme/src/components/EditPageLink.tsx b/packages/nextra-theme/src/components/EditPageLink.tsx
index 5ae5180673d4..80cdcb347cf8 100644
--- a/packages/nextra-theme/src/components/EditPageLink.tsx
+++ b/packages/nextra-theme/src/components/EditPageLink.tsx
@@ -24,13 +24,15 @@ export const EditPageLink = ({ mobile = false, ...props }: EditPageLinkProps) =>
 
   // If the current page is in a language other than English, link to the English version, as translations are handled by Crowdin
   const { filePath } = useContext(NavContext)!
-  const pagePathSegments = filePath.split('/')
-  pagePathSegments[1] = ['en', '[locale]'].includes(pagePathSegments[1]) ? pagePathSegments[1] : 'en'
-  const pagePath = pagePathSegments.join('/')
-
+  const [, fileLocale, ...filePathSegments] = filePath.split('/')
+  const path = filePath.startsWith('https')
+    ? filePath
+    : `https://github.com/graphprotocol/docs/blob/main/website/pages/${
+        ['en', '[locale]'].includes(fileLocale) ? fileLocale : 'en'
+      }/${filePathSegments.join('/')}`
   return (
     <Link
-      href={`https://github.com/graphprotocol/docs/blob/main/website/${pagePath}`}
+      href={path}
       target="_blank"
       sx={{
         display: 'block',
diff --git a/packages/nextra-theme/src/index.tsx b/packages/nextra-theme/src/index.tsx
index df5e8c07b4d4..2fba425a46c6 100644
--- a/packages/nextra-theme/src/index.tsx
+++ b/packages/nextra-theme/src/index.tsx
@@ -60,7 +60,7 @@ const mdxStyles: ThemeUIStyleObject = {
 
 export { Heading, Image, Link, LinkInline, Paragraph }
 
-export default function NextraLayout({ children, pageOpts }: NextraThemeLayoutProps): ReactElement {
+export default function NextraLayout({ children, pageOpts, pageProps }: NextraThemeLayoutProps): ReactElement {
   const { frontMatter, filePath, pageMap, headings, title } = pageOpts
   const { locale, defaultLocale } = useI18n()
   const fsPath = useFSRoute()
@@ -138,7 +138,7 @@ export default function NextraLayout({ children, pageOpts }: NextraThemeLayoutPr
   }
 
   return (
-    <NavContext.Provider value={{ filePath, ...args }}>
+    <NavContext.Provider value={{ filePath: pageProps.remoteFilePath || filePath, ...args }}>
       <DocumentContext.Provider value={{ frontMatter, headings, markOutlineItem, highlightedOutlineItemId }}>
         <NextSeo {...seo} />
 
diff --git a/packages/nextra-theme/src/layout/MDXLayoutNav.tsx b/packages/nextra-theme/src/layout/MDXLayoutNav.tsx
index db3959f138d7..b7cdaa228c05 100644
--- a/packages/nextra-theme/src/layout/MDXLayoutNav.tsx
+++ b/packages/nextra-theme/src/layout/MDXLayoutNav.tsx
@@ -3,7 +3,7 @@ import { keyframes } from '@emotion/react'
 import * as Collapsible from '@radix-ui/react-collapsible'
 import { useRouter } from 'next/router'
 import { Item } from 'nextra/normalize-pages'
-import { PropsWithChildren, useContext, useEffect, useState } from 'react'
+import { Fragment, PropsWithChildren, useContext, useEffect, useState } from 'react'
 
 import { BorderRadius, buildTransition, Flex, Icon, NestedStrings, Spacing, Text, useI18n } from '@edgeandnode/gds'
 
@@ -186,7 +186,7 @@ export const MDXLayoutNav = ({ mobile = false }: { mobile?: boolean }) => {
             }
             if ('children' in pageItem && pageItem.children) {
               if (pageItem.type === 'children') {
-                return <>{pageItem.children.map(renderSidebar)}</>
+                return <Fragment key={pageItem.name}>{pageItem.children.map(renderSidebar)}</Fragment>
               }
 
               return (
diff --git a/website/pages/en/_meta.js b/website/pages/en/_meta.js
index 8e8fe06c974a..311cf5c174f0 100644
--- a/website/pages/en/_meta.js
+++ b/website/pages/en/_meta.js
@@ -31,7 +31,7 @@ export default {
     title: 'Substreams',
   },
   substreams: {
-    type: 'children'
+    type: 'children',
   },
   '###3': {
     type: 'heading',
diff --git a/website/pages/en/substreams/[[...slug]].mdx b/website/pages/en/substreams/[[...slug]].mdx
index 2bb2a23f6fac..017ff03f772c 100644
--- a/website/pages/en/substreams/[[...slug]].mdx
+++ b/website/pages/en/substreams/[[...slug]].mdx
@@ -18,24 +18,39 @@ export async function getStaticPaths() {
 export async function getStaticProps({ params: { slug = ['README'] } }) {
   const baseURL = 'https://raw.githubusercontent.com/streamingfast/substreams/develop/docs/'
   const paths = slug.join('/')
-  let response = await fetch(`${baseURL}${paths}.md`)
+  let fileURL = `${paths}.md`
+  let response = await fetch(baseURL + fileURL)
   if (response.status === 404 && paths !== 'README') {
-    response = await fetch(`${baseURL}${paths}/README.md`)
+    fileURL = `$${paths}/README.md`
+    response = await fetch(baseURL + fileURL)
   }
-  const data = await response.text()
+  const data = (await response.text())
+    // replace {% embed ... %} with <iframe />
+    .replaceAll(
+      /{%\s+embed\s+url="(.*?)"\s+%}/g,
+      (...m) =>
+        `<iframe src="${m[1].replace(
+          // we need enhance YouTube links, otherwise they will be not loaded in iframe
+          'youtube.com/watch?v=',
+          'youtube.com/embed/'
+        )}" style={{aspectRatio: 16/9, width: '100%'}}/>`
+    )
+    // remove gitbook {% ... %} elements
+    .replaceAll(/{%.*?%}/g, '')
+    // close img tags only if he doesn't point to .gitbook
+    .replaceAll(/<img(.*?)>/g, (...m) => (m[1].includes('src=".gitbook') ? '' : `<img${m[1]}/>`))
+    // fixes http://localhost:3000/en/substreams/reference-and-specs/authentication/
+    .replaceAll('<pre class="language-bash" data-overflow="wrap"><code class="lang-bash">', '```bash\n')
+    // fixes http://localhost:3000/en/substreams/developers-guide/modules/inputs/
+    .replaceAll('<pre class="language-yaml" data-title="manifest excerpt"><code class="lang-yaml">', '```yaml\n')
+    .replaceAll('</code></pre>', '```')
   const mdx = await buildDynamicMDX(data, {
     mdxOptions: {
-      format: 'md',
+      // change-log contains `{variable}` text that is thrown an error by MDX2 parser since he treat it as variable injection, to fix it we parse chang-log with the markdown parser
+      format: paths.endsWith('/change-log') ? 'md' : 'mdx',
       remarkPlugins: [
         () => (tree, _file, done) => {
-          const GITBOOK_CALLOUT_REGEX = /{%.*?%}/
-          visit(tree, 'paragraph', (node) => {
-            for (const child of node.children) {
-              if (child.value) {
-                child.value = child.value.replace(GITBOOK_CALLOUT_REGEX, '')
-              }
-            }
-          })
+          // enhance links
           visit(tree, 'link', (node) => {
             if (node.url.startsWith('./')) {
               node.url = node.url.slice(2)
@@ -59,6 +74,7 @@ export async function getStaticProps({ params: { slug = ['README'] } }) {
       ...mdx,
       __nextra_pageMap: await getPageMap('en'),
       hideLocaleSwitcher: true,
+      remoteFilePath: `https://github.com/streamingfast/substreams/tree/develop/docs/${fileURL}`,
     },
   }
 }