feat: split out docs/react routes from shared MdxRoute file

- Create DocsReactRoute.res/.resi for /docs/react/* pages, following the
  same pattern as MdxRoute with React-specific sidebar categories
  (Overview, Main Concepts, Hooks & State Management, Guides) and
  breadcrumbs (Docs > rescript-react)
- Register docsReactRoutes in app/routes.res via MdxFile.scanPaths and
  filter docs/react paths out of the legacy mdxRoutes
- Fix inconsistent comparator in Mdx.sortSection: items with an order
  field now always sort before items without one, and items without order
  preserve their relative position

Author: jderochervlk

app/routes.res

@@ -33,10 +33,20 @@ let blogArticleRoutes =
     route(path, "./routes/BlogArticleRoute.jsx", ~options={id: path})
   )
 
+let docsReactRoutes =
+  MdxFile.scanPaths(~dir="markdown-pages/docs/react", ~alias="docs/react")->Array.map(path =>
+    route(path, "./routes/DocsReactRoute.jsx", ~options={id: path})
+  )
+
 let mdxRoutes = mdxRoutes("./routes/MdxRoute.jsx")->Array.filter(r =>
   !(
     r.path
-    ->Option.map(path => path === "blog" || String.startsWith(path, "blog/"))
+    ->Option.map(path =>
+      path === "blog" ||
+      String.startsWith(path, "blog/") ||
+      path === "docs/react" ||
+      String.startsWith(path, "docs/react/")
+    )
     ->Option.getOr(false)
   )
 )
@@ -56,6 +66,7 @@ let default = [
   ...stdlibRoutes,
   ...beltRoutes,
   ...blogArticleRoutes,
+  ...docsReactRoutes,
   ...mdxRoutes,
   route("*", "./routes/NotFoundRoute.jsx"),
 ]

app/routes/DocsReactRoute.res

@@ -0,0 +1,171 @@
+type loaderData = {
+  compiledMdx: CompiledMdx.t,
+  categories: array<SidebarLayout.Sidebar.Category.t>,
+  entries: array<TableOfContents.entry>,
+  title: string,
+  description: string,
+  filePath: string,
+}
+
+let convertToNavItems = (items, rootPath) =>
+  Array.map(items, (item): SidebarLayout.Sidebar.NavItem.t => {
+    let href = switch item.Mdx.slug {
+    | Some(slug) => `${rootPath}/${slug}`
+    | None => rootPath
+    }
+    {
+      name: item.title,
+      href,
+    }
+  })
+
+let getGroup = (groups, groupName): SidebarLayout.Sidebar.Category.t => {
+  {
+    name: groupName,
+    items: groups
+    ->Dict.get(groupName)
+    ->Option.getOr([]),
+  }
+}
+
+let getAllGroups = (groups, groupNames): array<SidebarLayout.Sidebar.Category.t> =>
+  groupNames->Array.map(item => getGroup(groups, item))
+
+// Build sidebar categories from all React docs, sorted by their "order" field in frontmatter
+let reactTableOfContents = async () => {
+  let groups =
+    (await Mdx.allMdx(~filterByPaths=["markdown-pages/docs"]))
+    ->Mdx.filterMdxPages("docs/react")
+    ->Mdx.groupBySection
+    ->Dict.mapValues(values => values->Mdx.sortSection->convertToNavItems("/docs/react"))
+
+  getAllGroups(groups, ["Overview", "Main Concepts", "Hooks & State Management", "Guides"])
+}
+
+let loader: ReactRouter.Loader.t<loaderData> = async ({request}) => {
+  let {pathname} = WebAPI.URL.make(~url=request.url)
+  let filePath = MdxFile.resolveFilePath(
+    (pathname :> string),
+    ~dir="markdown-pages/docs/react",
+    ~alias="docs/react",
+  )
+
+  let raw = await Node.Fs.readFile(filePath, "utf-8")
+  let {frontmatter}: MarkdownParser.result = MarkdownParser.parseSync(raw)
+
+  let description = switch frontmatter {
+  | Object(dict) =>
+    switch dict->Dict.get("description") {
+    | Some(String(s)) => s
+    | _ => ""
+    }
+  | _ => ""
+  }
+
+  let title = switch frontmatter {
+  | Object(dict) =>
+    switch dict->Dict.get("title") {
+    | Some(String(s)) => s
+    | _ => ""
+    }
+  | _ => ""
+  }
+
+  let categories = await reactTableOfContents()
+
+  let compiledMdx = await MdxFile.compileMdx(raw, ~filePath, ~remarkPlugins=Mdx.plugins)
+
+  // Build table of contents entries from markdown headings
+  let markdownTree = Mdast.fromMarkdown(raw)
+  let tocResult = Mdast.toc(markdownTree, {maxDepth: 2})
+
+  let headers = Dict.make()
+  Mdast.reduceHeaders(tocResult.map, headers)
+
+  let entries =
+    headers
+    ->Dict.toArray
+    ->Array.map(((header, url)): TableOfContents.entry => {
+      header,
+      href: (url :> string),
+    })
+    ->Array.slice(~start=2) // skip document entry and H1 title, keep h2 sections
+
+  {
+    compiledMdx,
+    categories,
+    entries,
+    title: `${title} | ReScript React`,
+    description,
+    filePath,
+  }
+}
+
+let default = () => {
+  let {pathname} = ReactRouter.useLocation()
+  let {compiledMdx, categories, entries, title, description, filePath} = ReactRouter.useLoaderData()
+
+  let breadcrumbs = list{
+    {Url.name: "Docs", href: "/docs/react/introduction"},
+    {
+      Url.name: "rescript-react",
+      href: "/docs/react/introduction",
+    },
+  }
+
+  let editHref = `https://github.com/rescript-lang/rescript-lang.org/blob/master/${filePath}`
+
+  let sidebarContent =
+    <aside className="px-4 w-full block">
+      <div className="flex justify-between items-baseline">
+        <div className="flex flex-col text-fire font-medium">
+          <VersionSelect />
+        </div>
+        <button
+          className="flex items-center" onClick={_ => NavbarUtils.closeMobileTertiaryDrawer()}
+        >
+          <Icon.Close />
+        </button>
+      </div>
+      <div className="mb-56">
+        {categories
+        ->Array.map(category => {
+          let isItemActive = (navItem: SidebarLayout.Sidebar.NavItem.t) =>
+            navItem.href === (pathname :> string)
+          let getActiveToc = (navItem: SidebarLayout.Sidebar.NavItem.t) =>
+            if navItem.href === (pathname :> string) {
+              Some({TableOfContents.title, entries})
+            } else {
+              None
+            }
+          <div key=category.name>
+            <SidebarLayout.Sidebar.Category
+              isItemActive
+              getActiveToc
+              category
+              onClick={_ => NavbarUtils.closeMobileTertiaryDrawer()}
+            />
+          </div>
+        })
+        ->React.array}
+      </div>
+    </aside>
+
+  <>
+    <Meta title description />
+    <NavbarSecondary />
+    <NavbarTertiary sidebar=sidebarContent>
+      <SidebarLayout.BreadCrumbs crumbs=breadcrumbs />
+      <a
+        href=editHref className="inline text-14 hover:underline text-fire" rel="noopener noreferrer"
+      >
+        {React.string("Edit")}
+      </a>
+    </NavbarTertiary>
+    <DocsLayout categories activeToc={title, entries}>
+      <div className="markdown-body">
+        <MdxContent compiledMdx />
+      </div>
+    </DocsLayout>
+  </>
+}

app/routes/DocsReactRoute.resi

@@ -0,0 +1,12 @@
+type loaderData = {
+  compiledMdx: CompiledMdx.t,
+  categories: array<SidebarLayout.Sidebar.Category.t>,
+  entries: array<TableOfContents.entry>,
+  title: string,
+  description: string,
+  filePath: string,
+}
+
+let loader: ReactRouter.Loader.t<loaderData>
+
+let default: unit => React.element

app/routes/MdxRoute.res

@@ -99,22 +99,6 @@ let manualTableOfContents = async () => {
   categories
 }
 
-let reactTableOfContents = async () => {
-  let groups =
-    (await allMdx(~filterByPaths=["markdown-pages/docs"]))
-    ->filterMdxPages("docs/react")
-    ->groupBySection
-    ->Dict.mapValues(values => values->sortSection->convertToNavItems("/docs/react"))
-
-  // these are the categories that appear in the sidebar
-  let categories: array<SidebarLayout.Sidebar.Category.t> = getAllGroups(
-    groups,
-    ["Overview", "Main Concepts", "Hooks & State Management", "Guides"],
-  )
-
-  categories
-}
-
 let communityTableOfContents = async () => {
   let groups =
     (await allMdx(~filterByPaths=["markdown-pages/community"]))
@@ -163,8 +147,6 @@ let loader: ReactRouter.Loader.t<loaderData> = async ({request}) => {
         []
       } else if pathname->String.includes("docs/manual") {
         await manualTableOfContents()
-      } else if pathname->String.includes("docs/react") {
-        await reactTableOfContents()
       } else if pathname->String.includes("community") {
         await communityTableOfContents()
       } else {
@@ -222,21 +204,11 @@ let loader: ReactRouter.Loader.t<loaderData> = async ({request}) => {
               href: "/docs/manual/" ++ "introduction",
             },
           })
-        : pathname->String.includes("docs/react")
-        ? Some(list{
-          {Url.name: "Docs", href: "/docs/"},
-          {
-            Url.name: "rescript-react",
-            href: "/docs/react/" ++ "introduction",
-          },
-        })
         : None
 
     let metaTitleCategory = {
       let path = (pathname :> string)
-      let title = if path->String.includes("docs/react") {
-        "ReScript React"
-      } else if path->String.includes("docs/manual/api") {
+      let title = if path->String.includes("docs/manual/api") {
         "ReScript API"
       } else if path->String.includes("docs/manual") {
         "ReScript Language Manual"
@@ -322,8 +294,7 @@ let default = () => {
       </>
     } else if (
       (pathname :> string)->String.includes("docs/manual") ||
-      (pathname :> string)->String.includes("docs/react") ||
-      (pathname :> string)->String.includes("docs/guidelines")
+        (pathname :> string)->String.includes("docs/guidelines")
     ) {
       <>
         <Meta title=title description={attributes.description->Nullable.getOr("")} />
@@ -334,8 +305,6 @@ let default = () => {
               if index === 0 {
                 if (pathname :> string)->String.includes("docs/manual") {
                   {...item, href: "/docs/manual/introduction"}
-                } else if (pathname :> string)->String.includes("docs/react") {
-                  {...item, href: "/docs/react/introduction"}
                 } else {
                   item
                 }

src/Mdx.res

@@ -82,7 +82,9 @@ let sortSection = mdxPages =>
   Array.toSorted(mdxPages, (a: attributes, b: attributes) =>
     switch (a.order, b.order) {
     | (Some(a), Some(b)) => a > b ? 1.0 : -1.0
-    | _ => -1.0
+    | (Some(_), None) => -1.0
+    | (None, Some(_)) => 1.0
+    | (None, None) => 0.0
     }
   )