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 ad5bf479def6..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'
 
@@ -185,6 +185,10 @@ export const MDXLayoutNav = ({ mobile = false }: { mobile?: boolean }) => {
               return <NavTree.Heading key={pageItem.name}>{pageItem.title}</NavTree.Heading>
             }
             if ('children' in pageItem && pageItem.children) {
+              if (pageItem.type === 'children') {
+                return <Fragment key={pageItem.name}>{pageItem.children.map(renderSidebar)}</Fragment>
+              }
+
               return (
                 <NavTree.Group key={pageItem.name} active={activePage.route.startsWith(`${pageItem.route}/`)}>
                   <NavTree.Group.Heading
diff --git a/website/next.config.js b/website/next.config.js
index e4118b86c37d..0535581d2fb5 100644
--- a/website/next.config.js
+++ b/website/next.config.js
@@ -17,7 +17,7 @@ const withNextra = nextra({
   transform(result, { route }) {
     if (route && !result.includes('getStaticProps')) {
       const banner = `
-import { getPageMap } from '@/components/get-page-map'
+import { getPageMap } from '@/src/getPageMap'
 
 export const getStaticProps = async context => ({
   props: {
diff --git a/website/pages/[locale]/index.mdx b/website/pages/[locale]/index.mdx
index fdd24be5489c..f8ba0afa670c 100644
--- a/website/pages/[locale]/index.mdx
+++ b/website/pages/[locale]/index.mdx
@@ -7,8 +7,8 @@ import { buildDynamicMDX } from 'nextra/remote'
 import { RemoteContent } from 'nextra/data'
 import { supportedLocales, translations } from '@/i18n'
 
-import { Intro, NetworkRoles, Products, SupportedNetworks } from '@/components/IndexPage'
-import { getPageMap } from '@/components/get-page-map'
+import { Intro, NetworkRoles, Products, SupportedNetworks } from '@/src/IndexPage'
+import { getPageMap } from '@/src/getPageMap'
 
 export const getStaticPaths = () => {
   return {
diff --git a/website/pages/_app.mdx b/website/pages/_app.mdx
index 3db56988f1c4..587813d4c467 100644
--- a/website/pages/_app.mdx
+++ b/website/pages/_app.mdx
@@ -2,4 +2,4 @@
 
 {/* _app.mdx is used in nextra for better performance and smallest bundle size. */}
 
-export { default } from '../components/_app'
+export { default } from '../src/_app'
diff --git a/website/pages/ar/_meta.js b/website/pages/ar/_meta.js
index f2f3b56163a5..ac570f79abfc 100644
--- a/website/pages/ar/_meta.js
+++ b/website/pages/ar/_meta.js
@@ -1,5 +1,5 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
 }
diff --git a/website/pages/en/_meta.js b/website/pages/en/_meta.js
index 55979ff3c6f2..311cf5c174f0 100644
--- a/website/pages/en/_meta.js
+++ b/website/pages/en/_meta.js
@@ -27,11 +27,17 @@ export default {
     type: 'separator',
   },
   '###2': {
+    type: 'heading',
+    title: 'Substreams',
+  },
+  substreams: {
+    type: 'children',
+  },
+  '###3': {
     type: 'heading',
     title: 'Indexing',
   },
   'operating-graph-node': '',
-  substreams: 'Substreams',
   firehose: '',
   '---4': {
     type: 'separator',
diff --git a/website/pages/en/substreams/[[...slug]].mdx b/website/pages/en/substreams/[[...slug]].mdx
index b491d88dfbf4..820a3c9d4ebe 100644
--- a/website/pages/en/substreams/[[...slug]].mdx
+++ b/website/pages/en/substreams/[[...slug]].mdx
@@ -2,7 +2,7 @@ import { visit } from 'unist-util-visit'
 import { RemoteContent } from 'nextra/data'
 import { buildDynamicMDX } from 'nextra/remote'
 import { listFiles } from './_meta.js'
-import { getPageMap } from '@/components/get-page-map'
+import { getPageMap } from '@/src/getPageMap'
 
 export async function getStaticPaths() {
   const files = await listFiles()
@@ -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}`,
     },
   }
 }
diff --git a/website/pages/es/_meta.js b/website/pages/es/_meta.js
index 4d1ffaa73cc7..4bff8328bc48 100644
--- a/website/pages/es/_meta.js
+++ b/website/pages/es/_meta.js
@@ -1,7 +1,7 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
   network: 'The Graph Network',
   '###1': {
     type: 'heading',
@@ -13,7 +13,7 @@ export default {
   managing: 'Administrando',
   querying: 'Consultando',
   cookbook: 'Recetario',
-  '###2': {
+  '###3': {
     type: 'heading',
     title: 'Indexación',
   },
diff --git a/website/pages/fr/_meta.js b/website/pages/fr/_meta.js
index f2f3b56163a5..ac570f79abfc 100644
--- a/website/pages/fr/_meta.js
+++ b/website/pages/fr/_meta.js
@@ -1,5 +1,5 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
 }
diff --git a/website/pages/hi/_meta.js b/website/pages/hi/_meta.js
index f2f3b56163a5..ac570f79abfc 100644
--- a/website/pages/hi/_meta.js
+++ b/website/pages/hi/_meta.js
@@ -1,5 +1,5 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
 }
diff --git a/website/pages/ja/_meta.js b/website/pages/ja/_meta.js
index d200660b8ab7..8ed202627c8e 100644
--- a/website/pages/ja/_meta.js
+++ b/website/pages/ja/_meta.js
@@ -1,7 +1,7 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
   network: 'グラフネットワーク',
   '###1': {
     type: 'heading',
@@ -13,7 +13,7 @@ export default {
   managing: '管理します',
   querying: 'クエリ',
   cookbook: 'クックブック',
-  '###2': {
+  '###3': {
     type: 'heading',
     title: 'インデキシング',
   },
diff --git a/website/pages/ko/_meta.js b/website/pages/ko/_meta.js
index f2f3b56163a5..ac570f79abfc 100644
--- a/website/pages/ko/_meta.js
+++ b/website/pages/ko/_meta.js
@@ -1,5 +1,5 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
 }
diff --git a/website/pages/ru/_meta.js b/website/pages/ru/_meta.js
index 41202dcd5d1f..2aa3c4a9b466 100644
--- a/website/pages/ru/_meta.js
+++ b/website/pages/ru/_meta.js
@@ -1,6 +1,6 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
   tokenomics: 'Токеномика',
 }
diff --git a/website/pages/uk/_meta.js b/website/pages/uk/_meta.js
index eab65774a101..f8fa5568eed9 100644
--- a/website/pages/uk/_meta.js
+++ b/website/pages/uk/_meta.js
@@ -1,7 +1,7 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
   network: 'Graph мережа',
   '###1': {
     type: 'heading',
@@ -13,7 +13,7 @@ export default {
   managing: 'Управління',
   querying: 'Запити',
   cookbook: 'Книга поетапних порад',
-  '###2': {
+  '###3': {
     type: 'heading',
     title: 'Індексація',
   },
diff --git a/website/pages/ur/_meta.js b/website/pages/ur/_meta.js
index d16de5d4e4a1..a7a63bc2e186 100644
--- a/website/pages/ur/_meta.js
+++ b/website/pages/ur/_meta.js
@@ -1,7 +1,7 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
   network: 'گراف نیٹورک',
   '###1': {
     type: 'heading',
@@ -13,7 +13,7 @@ export default {
   managing: 'انتظام',
   querying: 'استفسار کرنا',
   cookbook: 'ہدایت نامہ',
-  '###2': {
+  '###3': {
     type: 'heading',
     title: 'انڈیکسنگ',
   },
diff --git a/website/pages/vi/_meta.js b/website/pages/vi/_meta.js
index f2f3b56163a5..ac570f79abfc 100644
--- a/website/pages/vi/_meta.js
+++ b/website/pages/vi/_meta.js
@@ -1,5 +1,5 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
 }
diff --git a/website/pages/zh/_meta.js b/website/pages/zh/_meta.js
index 5acc2860f872..5b591dbe36c3 100644
--- a/website/pages/zh/_meta.js
+++ b/website/pages/zh/_meta.js
@@ -1,7 +1,7 @@
 import meta from '../en/_meta.js'
 
 export default {
-  ...meta,
+  ...structuredClone(meta),
   network: 'Graph网络',
   '###1': {
     type: 'heading',
@@ -13,7 +13,7 @@ export default {
   managing: '管理',
   querying: '查询',
   cookbook: '导览',
-  '###2': {
+  '###3': {
     type: 'heading',
     title: '索引',
   },
diff --git a/website/components/IndexPage.tsx b/website/src/IndexPage.tsx
similarity index 100%
rename from website/components/IndexPage.tsx
rename to website/src/IndexPage.tsx
diff --git a/website/components/_app.tsx b/website/src/_app.tsx
similarity index 100%
rename from website/components/_app.tsx
rename to website/src/_app.tsx
diff --git a/website/components/get-page-map.ts b/website/src/getPageMap.ts
similarity index 100%
rename from website/components/get-page-map.ts
rename to website/src/getPageMap.ts