Enhance MarkdownRenderer to support internal navigation; resolve document paths and update link handling

Author: yceruto

spa/src/components/docs/MarkdownRenderer.tsx

@@ -4,13 +4,46 @@ import remarkGfm from 'remark-gfm';
 import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { oneLight, oneDark } from 'react-syntax-highlighter/dist/esm/styles/prism';
 import { useTheme } from '../../hooks/useTheme';
+import { useNavigation } from '../../hooks/useNavigation';
+import { useDocs } from '../../hooks/useDocs';
 import { MermaidDiagram } from './MermaidDiagram';
 
 interface MarkdownRendererProps {
   content: string;
 }
 
+function resolveDocPath(currentDocPath: string, href: string): string {
+  const lastSlash = currentDocPath.lastIndexOf('/');
+  const currentDir = lastSlash >= 0 ? currentDocPath.substring(0, lastSlash) : '';
+  const baseParts = currentDir ? currentDir.split('/') : [];
+
+  for (const part of href.split('/')) {
+    if (part === '..') {
+      baseParts.pop();
+    } else if (part !== '.' && part !== '') {
+      baseParts.push(part);
+    }
+  }
+
+  return baseParts.join('/');
+}
+
+function collectAllPaths(items: import('../../types').DocsNavItem[]): Set<string> {
+  const paths = new Set<string>();
+  for (const item of items) {
+    if (item.path) paths.add(item.path);
+    if (item.items.length > 0) {
+      for (const p of collectAllPaths(item.items)) paths.add(p);
+    }
+  }
+  return paths;
+}
+
 export function MarkdownRenderer({ content }: MarkdownRendererProps) {
+  const { view, navigate } = useNavigation();
+  const { navigation } = useDocs();
+  const knownPaths = collectAllPaths(navigation);
+
   return (
     <div className="prose-doc max-w-4xl mt-10">
       <Markdown
@@ -48,11 +81,38 @@ export function MarkdownRenderer({ content }: MarkdownRendererProps) {
           li: ({ children }) => (
             <li className="leading-relaxed">{children}</li>
           ),
-          a: ({ href, children }) => (
-            <a href={href} className="text-primary-600 dark:text-primary-400 underline hover:text-primary-700 dark:hover:text-primary-300" target="_blank" rel="noopener noreferrer">
-              {children}
-            </a>
-          ),
+          a: ({ href, children }) => {
+            const linkClass = "text-primary-600 dark:text-primary-400 underline hover:text-primary-700 dark:hover:text-primary-300";
+
+            if (!href || /^(?:https?:|\/\/|mailto:|tel:)/.test(href)) {
+              return <a href={href} className={linkClass} target="_blank" rel="noopener noreferrer">{children}</a>;
+            }
+
+            if (href.startsWith('#')) {
+              return <a href={href} className={linkClass}>{children}</a>;
+            }
+
+            const [linkPath, anchor] = href.split('#');
+            const currentDocPath = view.type === 'doc' ? view.path : '';
+            const resolved = resolveDocPath(currentDocPath, linkPath!);
+
+            if (!knownPaths.has(resolved) && !/\.md$/.test(linkPath!)) {
+              return <a href={href} className={linkClass} target="_blank" rel="noopener noreferrer">{children}</a>;
+            }
+
+            return (
+              <a
+                href={href}
+                className={linkClass}
+                onClick={e => {
+                  e.preventDefault();
+                  navigate({ type: 'doc', path: resolved, anchor: anchor || undefined });
+                }}
+              >
+                {children}
+              </a>
+            );
+          },
           code: CodeBlock,
           pre: ({ children }) => <>{children}</>,
           blockquote: ({ children }) => (

templates/doc.html.php

@@ -4,7 +4,9 @@ Use the Club API to access contacts, conversations, group messages, and more and
 
 ## Getting started
 
-To get started, create a new application in your developer settings, then read about how to make requests for the resources you need to access using our HTTP APIs or dedicated client SDKs. When your integration is ready to go live, publish it to our integrations directory to reach the Club community.
+To get started, follow the [Quickstart guide](./quickstart.md) to create a new application in your developer settings, then read about how to make requests for the resources you need to access using our HTTP APIs or dedicated client SDKs. When your integration is ready to go live, publish it to our integrations directory to reach the Club community.
+
+For details on the domain model, see the [Property module](./specs/catalog/property/domain/models.md) and its [business rules](./specs/catalog/property/domain/business-rules.md).
 
 | Field1 | Field2 | Description |
 | --- | --- | --- |

tests/Functional/docs/introduction.md

@@ -5,6 +5,7 @@ This guide will get you all set up and ready to use the Club API. We'll cover ho
 ## What's next?
 Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the Protocol API:
 
-* Grab your API key from the Protocol dashboard
-* Check out the Conversations endpoint
-* Learn about the different error messages in Protocol
+* Read the [Introduction](./introduction.md) for an overview of the Club API
+* Explore the [Property module](./specs/catalog/property/README.md) to understand the catalog structure
+* Review the [API endpoints](./specs/catalog/property/presentation/api.md) and [webhook integration](./specs/catalog/property/presentation/webhook.md)
+* Check out the [SDK reference](./sdk/README.md) for client libraries

tests/Functional/docs/quickstart.md

@@ -1,3 +1,10 @@
 # Property Module
 
-A property is a key-value pair that describes an aspect of a catalog item. Properties can be used to provide additional information about an item, such as its color, size, or material. They can also be used to categorize items, such as by brand or type.
+A property is a key-value pair that describes an aspect of a catalog item. Properties can be used to provide additional information about an item, such as its color, size, or material. They can also be used to categorize items, such as by brand or type.
+
+## Layers
+
+* **Domain** — [Models](./domain/models.md) | [Business Rules](./domain/business-rules.md) | [Ubiquitous Language](./domain/ubiquitous-language.md)
+* **Application** — [Use-cases](./application/use-cases.md)
+* **Infrastructure** — [Integration](./infrastructure/integration.md)
+* **Presentation** — [API](./presentation/api.md) | [Console](./presentation/console.md) | [Webhook](./presentation/webhook.md)

tests/Functional/docs/specs/catalog/property/README.md

@@ -1 +1,5 @@
-# Application Use-cases
+# Application Use-cases
+
+This section describes the application-level operations on the Property module. These use-cases operate on the [Domain Models](../domain/models.md) and enforce the [Business Rules](../domain/business-rules.md).
+
+For the external-facing interfaces, see the [API endpoints](../presentation/api.md) and the [Console commands](../presentation/console.md).

tests/Functional/docs/specs/catalog/property/application/use-cases.md

@@ -1 +1,3 @@
-# Domain Business Rules
+# Domain Business Rules
+
+These rules apply to the entities defined in [Domain Models](./models.md). See also the [Ubiquitous Language](./ubiquitous-language.md) for term definitions.

tests/Functional/docs/specs/catalog/property/domain/business-rules.md

@@ -1 +1,5 @@
-# Domain Models
+# Domain Models
+
+The Property aggregate is the core of the Catalog context. For terminology definitions, see the [Ubiquitous Language](./ubiquitous-language.md). Validation constraints are documented in the [Business Rules](./business-rules.md).
+
+For how these models are used in practice, refer to the [Application Use-cases](../application/use-cases.md).