Exclude cross links from pagelinks.

Author: koculu

frontend/purestack.studio/components/_nav.json

@@ -1,3 +1,15 @@
 {
-  "pageLinks": true
+  "pageLinks": true,
+  "sequence": [
+    "index.mdx",
+    "guides"
+  ],
+  "items": [
+    {
+      "id": "guides",
+      "title": "Guides",
+      "url": "/guides/",
+      "icon": "tabler:book-2"
+    }
+  ]
 }

frontend/purestack.studio/guides/_nav.json

@@ -2,6 +2,7 @@
   "pageLinks": true,
   "sequence": [
     "index.mdx",
+    "components",
     "purestack-cli.mdx",
     "site-config.mdx",
     "vscode-extension.mdx",
@@ -11,5 +12,13 @@
     "semantic-tones.mdx",
     "icons.mdx",
     "themes.mdx"
+  ],
+  "items": [
+    {
+      "id": "components",
+      "title": "Components",
+      "url": "/components/",
+      "icon": "tabler:components"
+    }
   ]
 }

frontend/purestack.studio/guides/site-config.mdx

@@ -172,7 +172,7 @@ In `hybrid` mode, a folder's `_nav.json` can order discovered pages, add custom
 }
 ```
 
-Place this in `content/guides/_nav.json`. A nav file can also use `"mode": "override"` to replace that folder's discovered items, or `"root"` to select another built navigation root. The default nav filename is `_nav.json`.
+Place this in `content/guides/_nav.json`. A custom item's `url` is relative to the nav file's folder, unless it starts with `/`, which makes it site-absolute: `/components/` links to another section. Give an item an `id` to place it with `sequence`. Previous and next links stay within the current navigation root, so a link to another section appears in the menu but is skipped by previous and next. A nav file can also use `"mode": "override"` to replace that folder's discovered items, or `"root"` to select another built navigation root. The default nav filename is `_nav.json`.
 
 `pageToc.enabled` sets the default for a page's table of contents; individual pages can override it with frontmatter `layout.showToc`. `docLayout.sidebarTop` and `sidebarTopMobile` are CSS lengths measured from the viewport top. Adjust them when your header height changes so the sidebars and mobile drawers start below it.
 

packages/ts-ssg/src/navigation/nav-file.ts

@@ -129,7 +129,10 @@ function resolveUrl(raw: Record<string, unknown>, folder: string) {
 
 function resolveInternalUrl(folder: string, url: string) {
   const { base, suffix } = urlNormalizer.splitSuffix(url)
-  const joined = path.posix.join('/', folder, base)
+  // A leading slash is site-absolute, so it must not be nested in the folder.
+  const joined = base.startsWith('/')
+    ? path.posix.normalize(base)
+    : path.posix.join('/', folder, base)
   const hasExt = path.posix.extname(joined).length > 0
   const normalized = hasExt || joined.endsWith('/') ? joined : `${joined}/`
   return `${normalized}${suffix}`

packages/ts-ssg/src/navigation/navigation.test.ts

@@ -567,6 +567,38 @@ describe('navigation', () => {
     })
   })
 
+  it('keeps site-absolute custom item urls outside the nav file folder', async () => {
+    await withTempDir(async (base) => {
+      const contentDir = path.join(base, 'content')
+      await fs.mkdir(path.join(contentDir, 'guides'), { recursive: true })
+      await fs.writeFile(
+        path.join(contentDir, 'guides', 'index.mdx'),
+        `---\ntitle: Guides\n---\n# Guides\n`,
+        'utf8',
+      )
+      await fs.writeFile(
+        path.join(contentDir, 'guides', '_nav.json'),
+        JSON.stringify({
+          items: [
+            { title: 'Components', url: '/components/' },
+            { title: 'Themes', url: 'themes' },
+          ],
+        }),
+        'utf8',
+      )
+
+      const files = await discoverContent(contentDir)
+      const nav = await buildNavigation(contentDir, files, {
+        mode: 'hybrid',
+        maxDepth: 20,
+      })
+      const urls = (nav?.byFolder.guides ?? []).map((item) => item.url)
+
+      expect(urls).toContain('/components/')
+      expect(urls).toContain('/guides/themes/')
+    })
+  })
+
   it('applies nav file icons to mixed auto and custom items', async () => {
     await withTempDir(async (base) => {
       const contentDir = path.join(base, 'content')
@@ -741,6 +773,67 @@ describe('navigation', () => {
     })
   })
 
+  it('keeps page links inside the current navigation root', async () => {
+    await withTempDir(async (base) => {
+      const contentDir = path.join(base, 'content')
+      await fs.mkdir(path.join(contentDir, 'guides'), { recursive: true })
+      await fs.mkdir(path.join(contentDir, 'components'), { recursive: true })
+      await fs.writeFile(
+        path.join(contentDir, 'guides', 'index.mdx'),
+        `---\ntitle: Guides\n---\n# Guides\n`,
+        'utf8',
+      )
+      await fs.writeFile(
+        path.join(contentDir, 'guides', 'setup.mdx'),
+        `---\ntitle: Setup\n---\n# Setup\n`,
+        'utf8',
+      )
+      await fs.writeFile(
+        path.join(contentDir, 'components', 'index.mdx'),
+        `---\ntitle: Components\n---\n# Components\n`,
+        'utf8',
+      )
+      await fs.writeFile(
+        path.join(contentDir, 'guides', '_nav.json'),
+        JSON.stringify({
+          pageLinks: true,
+          sequence: ['index.mdx', 'components', 'setup.mdx'],
+          items: [
+            { id: 'components', title: 'Components', url: '/components/' },
+          ],
+        }),
+        'utf8',
+      )
+
+      const files = await discoverContent(contentDir)
+      const nav = await buildNavigation(contentDir, files, {
+        mode: 'hybrid',
+        maxDepth: 20,
+        roots: ['guides', 'components'],
+      })
+      const guides = resolvePageNavigation(
+        nav,
+        findContentFile(files, 'guides/index.mdx'),
+      )
+      const setup = resolvePageNavigation(
+        nav,
+        findContentFile(files, 'guides/setup.mdx'),
+      )
+
+      expect(guides?.items.map((item) => item.title)).toEqual([
+        'Guides',
+        'Components',
+        'Setup',
+      ])
+      expect(guides?.pageLinks).toEqual({
+        next: { title: 'Setup', url: '/guides/setup/' },
+      })
+      expect(setup?.pageLinks).toEqual({
+        previous: { title: 'Guides', url: '/guides/' },
+      })
+    })
+  })
+
   it('falls back to the locale root for localized pages outside configured navigation roots', async () => {
     await withTempDir(async (base) => {
       const contentDir = path.join(base, 'content')

packages/ts-ssg/src/navigation/navigation.ts

@@ -87,7 +87,7 @@ export function resolvePageNavigation(
     ? (tree.rootByFolder[folder] ?? configuredRoot)
     : configuredRoot
   const items = tree.byFolder[root] ?? tree.byFolder[folder] ?? []
-  const pageLinks = resolvePageLinks(tree, folder, items, file)
+  const pageLinks = resolvePageLinks(tree, folder, root, items, file)
   return {
     mode: tree.mode,
     folder,

packages/ts-ssg/src/navigation/page-links.ts

@@ -20,14 +20,19 @@ export function buildPageLinksByFolder(
 export function resolvePageLinks(
   tree: NavigationTree,
   folder: string,
+  root: string,
   items: NavItem[],
   file: NavigationContentFile,
 ): PageNavigationLinks | undefined {
   if (!isPageLinksEnabled(tree, folder)) return undefined
   const currentUrl = normalizePageLinkUrl(resolveRouteInfo(file).urlPath)
   if (!currentUrl) return undefined
 
-  const links = flattenPageLinks(items)
+  // Previous and next walk one section. Items that link to another section,
+  // such as a cross-link from the guides to the components, are skipped.
+  const links = flattenPageLinks(items).filter((link) =>
+    isInsideRoot(link.url, root),
+  )
   const index = links.findIndex((link) => link.url === currentUrl)
   if (index < 0) return undefined
 
@@ -40,6 +45,12 @@ export function resolvePageLinks(
   }
 }
 
+function isInsideRoot(url: string, root: string) {
+  if (!root) return true
+  const rootUrl = `/${root}/`
+  return url === rootUrl || url.startsWith(rootUrl)
+}
+
 function isPageLinksEnabled(tree: NavigationTree, folder: string) {
   let current = folder
   while (true) {