updated bridge doc page + readme

Author: MitchellShiell

README.md

@@ -3,6 +3,9 @@
 
 Bridge is a single, easy-to-navigate hub that beautifully renders all our product documentation from the `/docs` folder of all our GitHub repositories. 
 
+> [!NOTE]  
+> Overture Docs started under the name Bridge to reflect its ability to bridge information across multiple repositories. Bridge was also chosen in fitting with Overtures Orchestral theme.>
+
 ## Documentation Framework
 
 Overture has three user profiles:
@@ -17,10 +20,10 @@ Our documentation is split up as follows:
 
 | Documentation | User Profile | Description
 |---|---|---|
-| Developer/Product Documentation | Software Engineers & Developers | Technical resources for those working on or contributing to the project. | 
-| Platform Guides | IT Specialists & Informaticians | Instructive guides covering platform setup, maintenance and usage for end-users and administrators. |
+| Product Documentation (Housed here) | Software Engineers & Developers | Technical resources for those working on or contributing to the project. | 
+| Platform Guides (Overture.bio)  | IT Specialists & Informaticians | Instructive guides covering platform setup, maintenance and usage for end-users and administrators. |
 
-## How OvertureDocs Works
+## How Overture Docs Works
 
 - **Docusaurus**: We use Docusaurus to render the site, providing a sleek and navigable interface for our documentation.
 
@@ -40,6 +43,11 @@ Our documentation is split up as follows:
 
 - **Robust Error Handling**: Docusaurus has excellent error catching, particularly for broken and missing links, reducing the need for manual testing.
 
+![Pro Tip](./website/docs/03-other-software/images/proTip.png 'Use Overture Docs repo to search across all Overture repos')
+
+> [!TIP]  
+> The Overture Docs repo contains everything, therefore finding & tracking links and content across all our repos has never been easier.
+
 ## Getting Started
 
 ### Running it Locally
@@ -66,7 +74,7 @@ npm start
 
 ### Adding Submodules
 
-Use the following command to add a new submodule:
+Use the following command from the submodules directory to add a new submodule:
 
    ```bash
    git submodule add -b <branchName> <GitHub repository URL> module_name
@@ -123,3 +131,102 @@ plugins: ['./docsPlugin.ts'],
 ```
 
 The source of this fix can be found [here](https://github.com/facebook/docusaurus/issues/3272#issuecomment-688409489).
+
+## Globally imported Mdx components
+
+We can import components by default across all our mdx files reducing the head matter when using these components in mdx documents. This can be configured from the `/src/theme/MDXComponents.ts`:
+
+```ts title="MDXComponents.ts"
+import type {ComponentType} from 'react';
+import MDXComponents from '@theme-original/MDXComponents';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+const components: typeof MDXComponents & {
+    Tabs: ComponentType<any>;
+    TabItem: ComponentType<any>;
+    DocCardList: ComponentType<any>;
+} = {
+  ...MDXComponents,
+  Tabs,
+  TabItem,
+  DocCardList,
+};
+
+export default components;
+```
+
+## Custom Components 
+
+There are three custom components built for this site all located in the components directory as follows:
+
+```
+.
+└── /src/
+    └── components/
+        ├── FundingStatment
+        ├── SiteMap
+        └── SwaggerAPIDoc
+```
+
+### Site Map
+
+### Site Map
+
+- The sitemap component renders the frontpage navigation of the website, organized in a mosaic layout with left and right columns
+- Categories can be added by extending the `const categories:` object (lines 24-45) with new entries containing:
+  - `title`: Category display name
+  - `description`: Brief category description
+- Products are defined in `const products:` array (lines 47-61) with each product requiring:
+  - `title`: Product name
+  - `link`: URL path
+  - `description`: Brief description 
+  - `category`: Must match a category key
+  - `image`: Optional icon path
+
+The layout groups products into their respective categories and automatically distributes them between the left column (`core`, `development`) and right column (`platform`, `misc`, `standards`).
+
+This component also includes our funding statement, the copy used can be updated directly from the component on line 90.
+
+> [!NOTE] Improvement Consideration
+> The current implementation uses hardcoded arrays (leftColumnCategories and rightColumnCategories) for column distribution. This is not ideal however it is the simplest method to organize our site content in its ideal layout. 
+
+### Sidebar Funding Statement
+
+A simple React component that displays funding attribution information on the bottom left of all sidebars. It uses CSS Modules for scoped styling (styles.module.css). 
+
+> [!NOTE] Improvement Consideration
+> Consider making the content configurable by accepting props rather than hardcoding the grant information, allowing reuse for different funding sources.
+
+### Swagger API Embed
+
+The `SwaggerAPIDoc` component renders API documentation completely client-side by:
+
+1. Importing local JSON specification files (`songAPI.json`, `scoreAPI.json`, `maestroAPI.json`)
+2. Using these static JSON files to generate the documentation UI, meaning:
+   - No actual API calls are made
+   - Documentation works offline
+   - No backend connectivity required
+   - Safe for internal/private API documentation
+   - Specifications can be version controlled alongside the code
+
+Usage example with local JSON:
+```jsx
+// Your JSON spec file (e.g., songAPI.json)
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Song API",
+    // ... rest of your API specification
+  }
+}
+
+// Component usage remains the same
+<SwaggerAPIDoc specName="song" />
+```
+
+The `tryItOutEnabled={false}` setting further reinforces this by preventing any attempts to make actual API calls from the documentation interface.
+
+> [!NOTE] Improvement Consideration
+> Consider making the content configurable by accepting a path prop rather than having to add the spec to the component itself.

submodules/.github

@@ -159,6 +159,7 @@ const components: typeof MDXComponents & {
 export default components;
 ```
 
+
 ## Custom Components 
 
 There are three custom components built for this site all located in the components directory as follows:
@@ -174,8 +175,62 @@ There are three custom components built for this site all located in the compone
 
 ### Site Map
 
+- The sitemap component renders the frontpage navigation of the website, organized in a mosaic layout with left and right columns
+- Categories can be added by extending the `const categories:` object (lines 24-45) with new entries containing:
+  - `title`: Category display name
+  - `description`: Brief category description
+- Products are defined in `const products:` array (lines 47-61) with each product requiring:
+  - `title`: Product name
+  - `link`: URL path
+  - `description`: Brief description 
+  - `category`: Must match a category key
+  - `image`: Optional icon path
+
+The layout groups products into their respective categories and automatically distributes them between the left column (`core`, `development`) and right column (`platform`, `misc`, `standards`).
+
+This component also includes our funding statement, the copy used can be updated directly from the component on line 90.
+
+:::tip Improvement Consideration
+The current implementation uses hardcoded arrays (leftColumnCategories and rightColumnCategories) for column distribution. This is not ideal however it is the simplest method to organize our site content in its ideal layout. 
+:::
+
 ### Sidebar Funding Statement
 
+A simple React component that displays funding attribution information on the bottom left of all sidebars. It uses CSS Modules for scoped styling (styles.module.css). 
+
+:::tip Improvement Consideration
+Consider making the content configurable by accepting props rather than hardcoding the grant information, allowing reuse for different funding sources.
+:::
+
 ### Swagger API Embed
 
+The `SwaggerAPIDoc` component renders API documentation completely client-side by:
+
+1. Importing local JSON specification files (`songAPI.json`, `scoreAPI.json`, `maestroAPI.json`)
+2. Using these static JSON files to generate the documentation UI, meaning:
+   - No actual API calls are made
+   - Documentation works offline
+   - No backend connectivity required
+   - Safe for internal/private API documentation
+   - Specifications can be version controlled alongside the code
+
+Usage example with local JSON:
+```jsx
+// Your JSON spec file (e.g., songAPI.json)
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Song API",
+    // ... rest of your API specification
+  }
+}
+
+// Component usage remains the same
+<SwaggerAPIDoc specName="song" />
+```
+
+The `tryItOutEnabled={false}` setting further reinforces this by preventing any attempts to make actual API calls from the documentation interface.
 
+:::tip Improvement Consideration
+Consider making the content configurable by accepting a path prop rather than having to add the spec to the component itself.
+:::