validmind · validbeck · Jul 3, 2024 · Jun 21, 2024 · Jun 21, 2024 · Jun 21, 2024
diff --git a/README.md b/README.md
@@ -2,13 +2,13 @@
 
 ![](site/about/ValidMind-logo-color.svg)
 
-This is the home for the user-facing documentation and related infrastructure for ValidMind. If you want to make updates to our external docs site, you're in the right place.
+This is the home for the user-facing documentation and related infrastructure for ValidMind. If you want to make updates to our external docs site, you're in the right place!
 
 ## Contributing to the documentation
 
 We believe in the power of collaboration and welcome contributions from the community. If you've noticed an issue or have ideas for improvement, please create a pull request or submit an issue. A member of ValidMind's documentation team will review your suggestions and support you in contributing to the docs. 
 
-- Follow the [Quickstart](https://docs.validmind.ai/guide/quickstart.html) for a 20 minute introduction to the Developer Framework and ValidMind Platform.
+- Follow the [Quickstart](https://docs.validmind.ai/guide/quickstart-try-developer-framework-with-jupyterhub.html) for a 15-minute introduction to the Developer Framework and ValidMind Platform.
 
 - Read the [Developer Framework docs](https://docs.validmind.ai/guide/developer-framework.html) for more information about ValidMind's open source tests and Jupyter notebooks.
 
@@ -25,21 +25,22 @@ You need:
 - For Windows operating systems, install the `make` command via [Cygwin](https://cygwin.com/install.html)
 
 ## How to contribute
+> First, read through and familiarize yourself with our [ValidMind style guide](https://docs.validmind.ai/about/style-guide.html).
 
-Our core docs are sourced in Quarto Markdown under [site/guide/](https://github.com/validmind/documentation/tree/main/site/guide). If you create new documentation, make sure to add it to the [_quarto.yml](https://github.com/validmind/documentation/blob/main/site/_quarto.yml) file.
+Our core docs are sourced in Quarto Markdown under [`site`](https://github.com/validmind/documentation/tree/main/site/). If you create new documentation, make sure to add it to the [`_quarto.yml`](https://github.com/validmind/documentation/blob/main/site/_quarto.yml) file.
 
 If you are creating a pull request, test your changes by rendering or previewing the site. Note that if this is your first time contributing, you will be asked to sign a contributor license agreement (CLA).
 
-## Preview the docs site
+### Preview the docs site
 
 ```bash
 cd site
 quarto preview
 ```
 
-## Render the docs site
+### Render the docs site
 
-Just render the site:
+To render the site:
 
 ```bash
 cd site
@@ -53,3 +54,70 @@ site
 └── _site ...
     └── *.html, *.css, *.png, *.js ...
 ```
+
+## Directory map
+
+### `site`
+Core files you manipulate live under `site` in these key directories that more or less correlate to the sections of the docs site reachable via the top navigation bar:
+
+- `about` 
+- `developer-framework` 
+- `faq` 
+- `get-started` 
+- `guide`  
+- `support` 
+
+These directories may have sub-directories depending on their size and grouped sub-topics contained within. 
+
+#### Special `site` directories
+- `releases` — Correlates to the "Releases" section under [About](https://docs.validmind.ai/about/overview.html).
+- `training` — Correlates to the "Training" section under [Get Started](https://docs.validmind.ai/training/training-overview.html).
+
+#### Supporting `site` directories
+- `_site` — This is where static files rendered by `quarto render` get placed.
+- `assets` — This is where general shared assets live (stylesheets, promotional images, etc.).
+- `notebooks` — This is where notebooks retrieved from the [`developer-framework` repo](https://github.com/validmind/developer-framework) live.
+- `tests` — This is where tests retrieved from the [`developer-framework` repo](https://github.com/validmind/developer-framework) live.
+- `wip` — Work in progress files should live here, and have [the `search` flag set to `false`](https://quarto.org/docs/websites/website-search.html#disabling-search).
+
+### Auxiliary directories
+
+- `site-unused` — Archived files get moved here. 
+- `templates` — You can find generic structural templates in this folder here to help you build your guides.
+
+## Working with files
+
+### `.qmd`
+> Files for the docs site are created using [Quarto Markdown](https://quarto.org/docs/authoring/markdown-basics.html) (`.qmd`). These, along with any Jupyter Notebooks pulled in from `developer-framework`, get rendered into HTML files. 
+
+#### Hyperlinks
+When constructing links, refer to the `.qmd` file as Quarto will properly render these into `.html` links on your behalf and check to see if the destinations are able to be resolved:
+
+| Correct | Incorrect |
+|---|---|
+| `[Get started with JupyterHub](get-started/developer/try-with-jupyterhub.qmd)` | `[Get started with JupyterHub](get-started/developer/try-with-jupyterhub.html)` |
+
+The only exceptions are within HTML, such as CSS-styled buttons which necessitate usage of `.html` href links:
+
+```html
+<a class="btn btn-primary" role="button" style="padding: 12px;color: var(--bs-white);background: #DE257E;border-radius: 4px;margin-top: 40px;font-family: 'Inter';font-style: normal;font-weight: 700;font-size: 14px;line-height: 100%;border: 1px solid var(--bs-pink);" href="get-started/developer/try-with-jupyterhub.html">QuickStart</a>
+```
+
+> You'll need to pay special attention to these links and manually test them to ensure that they are not broken whenever any changes to file destinations are made. 
+
+When constructing filepaths, including while using [Quarto's Includes](https://quarto.org/docs/authoring/includes.html) (single-sourcing feature), you'll also want start with the root directory whenever possible as this minimizes usage of unclear relative paths: 
+
+| Correct | Incorrect |
+|---|---|
+| `[Register models in the inventory](/guide/model-inventory/register-models-in-inventory.qmd)` | `[Register models in the inventory](../../register-models-in-inventory.qmd)` |
+
+### Jupyter Notebooks
+> Notebooks (`.ipynb` files) are NOT edited via this `documentation` repo, as any changes will be overridden. 
+
+Changes need to be made in the [root repository `developer-framework`](https://github.com/validmind/developer-framework) and pulled into this one with:
+
+```bash
+make get-source
+```
+
+
diff --git a/site/assets/css/styles.css → site-unused/assets/css/styles.css b/site/assets/css/styles.css → site-unused/assets/css/styles.css
diff --git a/site/guide/federal-reserve.textClipping → ...nused/assets/federal-reserve.textClipping b/site/guide/federal-reserve.textClipping → ...nused/assets/federal-reserve.textClipping
diff --git a/...-10f796f9-5015-4a29-8a08-2fca51b69af1.png → ...-10f796f9-5015-4a29-8a08-2fca51b69af1.png b/...-10f796f9-5015-4a29-8a08-2fca51b69af1.png → ...-10f796f9-5015-4a29-8a08-2fca51b69af1.png
diff --git a/...-393ebf78-b8ce-4c55-83ea-9cee2371705f.png → ...-393ebf78-b8ce-4c55-83ea-9cee2371705f.png b/...-393ebf78-b8ce-4c55-83ea-9cee2371705f.png → ...-393ebf78-b8ce-4c55-83ea-9cee2371705f.png
diff --git a/...-64f02550-f6db-4903-a17e-ec23d92c8377.png → ...-64f02550-f6db-4903-a17e-ec23d92c8377.png b/...-64f02550-f6db-4903-a17e-ec23d92c8377.png → ...-64f02550-f6db-4903-a17e-ec23d92c8377.png
diff --git a/site/assets/img/Frame 1.png → site-unused/assets/img/Frame 1.png b/site/assets/img/Frame 1.png → site-unused/assets/img/Frame 1.png
diff --git a/site/assets/img/Gradient_bg.svg → site-unused/assets/img/Gradient_bg.svg b/site/assets/img/Gradient_bg.svg → site-unused/assets/img/Gradient_bg.svg
diff --git a/site/assets/img/Group 37.png → site-unused/assets/img/Group 37.png b/site/assets/img/Group 37.png → site-unused/assets/img/Group 37.png
diff --git a/site/assets/img/Group 37.svg → site-unused/assets/img/Group 37.svg b/site/assets/img/Group 37.svg → site-unused/assets/img/Group 37.svg
diff --git a/site/assets/img/Group 38.png → site-unused/assets/img/Group 38.png b/site/assets/img/Group 38.png → site-unused/assets/img/Group 38.png
diff --git a/site-unused/closed-beta-banner.png → ...-unused/assets/img/closed-beta-banner.png b/site-unused/closed-beta-banner.png → ...-unused/assets/img/closed-beta-banner.png
diff --git a/site/guide/create-project.png → site-unused/assets/img/create-project.png b/site/guide/create-project.png → site-unused/assets/img/create-project.png
diff --git a/site/guide/developer-framework-workflow.png → ...sets/img/developer-framework-workflow.png b/site/guide/developer-framework-workflow.png → ...sets/img/developer-framework-workflow.png
diff --git a/site/guide/google-colab-secrets.png → ...nused/assets/img/google-colab-secrets.png b/site/guide/google-colab-secrets.png → ...nused/assets/img/google-colab-secrets.png
diff --git a/site/assets/img/image.png → site-unused/assets/img/image.png b/site/assets/img/image.png → site-unused/assets/img/image.png
diff --git a/site/guide/images.png → site-unused/assets/img/images.png b/site/guide/images.png → site-unused/assets/img/images.png
diff --git a/site/guide/latex-paste-mathtype.gif → ...nused/assets/img/latex-paste-mathtype.gif b/site/guide/latex-paste-mathtype.gif → ...nused/assets/img/latex-paste-mathtype.gif
diff --git a/site/guide/overview-simple.png → site-unused/assets/img/overview-simple.png b/site/guide/overview-simple.png → site-unused/assets/img/overview-simple.png
diff --git a/site/guide/search-demo.gif → site-unused/assets/img/search-demo.gif b/site/guide/search-demo.gif → site-unused/assets/img/search-demo.gif
diff --git a/site/guide/sort-demo.gif → site-unused/assets/img/sort-demo.gif b/site/guide/sort-demo.gif → site-unused/assets/img/sort-demo.gif
diff --git a/site/guide/type-equation-mathtype.gif → ...sed/assets/img/type-equation-mathtype.gif b/site/guide/type-equation-mathtype.gif → ...sed/assets/img/type-equation-mathtype.gif
diff --git a/site/guide/user-management-example.jpg → ...ed/assets/img/user-management-example.jpg b/site/guide/user-management-example.jpg → ...ed/assets/img/user-management-example.jpg
diff --git a/site-unused/architecture.qmd → site-unused/qmd/architecture.qmd b/site-unused/architecture.qmd → site-unused/qmd/architecture.qmd
diff --git a/site-unused/before-you-begin.qmd → site-unused/qmd/before-you-begin.qmd b/site-unused/before-you-begin.qmd → site-unused/qmd/before-you-begin.qmd
@@ -25,8 +25,8 @@ If your company has strict security requirements and requires you to connect via
 
 To follow the QuickStart, you need access to ONE of the following:
 
-- [JupyterHub](quickstart-try-developer-framework-with-jupyterhub.qmd) (recommended)
-- [Google Colaboratory (Colab)](quickstart-try-developer-framework-with-colab.qmd)
+- [JupyterHub](try-with-jupyterhub.qmd) (recommended)
+- [Google Colaboratory (Colab)](try-with-colab.qmd)
 - [Docker Desktop](quickstart-try-developer-framework-with-docker.qmd)
 
 To run our sample Jupyter Notebooks locally, your developer environment must support **Python {{< var python-version >}}**.
@@ -37,5 +37,5 @@ You need to be able to access our ValidMind Web UI from a modern browser such as
 
 ## What's next
 
-Continue with Explore the {{< var vm_dev >}}. We recommend using [JupyterHub](quickstart-try-developer-framework-with-jupyterhub.qmd). 
+Continue with Explore the {{< var vm_dev >}}. We recommend using [JupyterHub](try-with-jupyterhub.qmd). 
 
diff --git a/site-unused/cloud-platforms.qmd → site-unused/qmd/cloud-platforms.qmd b/site-unused/cloud-platforms.qmd → site-unused/qmd/cloud-platforms.qmd
diff --git a/site/guide/comment-on-validation-reports.qmd → ...sed/qmd/comment-on-validation-reports.qmd b/site/guide/comment-on-validation-reports.qmd → ...sed/qmd/comment-on-validation-reports.qmd
diff --git a/site-unused/configure-sso.qmd → site-unused/qmd/configure-sso.qmd b/site-unused/configure-sso.qmd → site-unused/qmd/configure-sso.qmd
diff --git a/site/guide/configure-the-platform.qmd → site-unused/qmd/configure-the-platform.qmd b/site/guide/configure-the-platform.qmd → site-unused/qmd/configure-the-platform.qmd
diff --git a/site-unused/create-documentation.qmd → site-unused/qmd/create-documentation.qmd b/site-unused/create-documentation.qmd → site-unused/qmd/create-documentation.qmd
@@ -8,7 +8,7 @@ Upload documentation and test results for a specific model, to review and valida
 ## Prerequisites
 
 - You hold the `Developer` or `Validator` role
-- The model you are documenting is [registered in the model inventory](register-models-in-model-inventory.qmd).
+- The model you are documenting is [registered in the model inventory](register-models-in-inventory.qmd).
 
 ## Steps
 

diff --git a/site/guide/create-inventory-models.qmd → site-unused/qmd/create-inventory-models.qmd b/site/guide/create-inventory-models.qmd → site-unused/qmd/create-inventory-models.qmd
diff --git a/...ide/customize-model-registration-form.qmd → ...qmd/customize-model-registration-form.qmd b/...ide/customize-model-registration-form.qmd → ...qmd/customize-model-registration-form.qmd
diff --git a/...customize-validation-report-templates.qmd → ...customize-validation-report-templates.qmd b/...customize-validation-report-templates.qmd → ...customize-validation-report-templates.qmd
diff --git a/site-unused/customize-workflows.qmd → site-unused/qmd/customize-workflows.qmd b/site-unused/customize-workflows.qmd → site-unused/qmd/customize-workflows.qmd
diff --git a/...guide/developer-getting-started-video.qmd → ...d/qmd/developer-getting-started-video.qmd b/...guide/developer-getting-started-video.qmd → ...d/qmd/developer-getting-started-video.qmd
diff --git a/site-unused/editions-and-features.qmd → site-unused/qmd/editions-and-features.qmd b/site-unused/editions-and-features.qmd → site-unused/qmd/editions-and-features.qmd
diff --git a/site-unused/faq-data-handling.qmd → site-unused/qmd/faq-data-handling.qmd b/site-unused/faq-data-handling.qmd → site-unused/qmd/faq-data-handling.qmd
@@ -17,7 +17,7 @@ The {{< var vm_dev >}} executes test suites and functions locally in your enviro
 
 ValidMind does not send datasets outside of your environment. Additionally, ValidMind adheres to a strict data confidentiality and retention policy, compliant with the SOC 2 security standard.
 
-For more information, refer to our [data privacy policy](../about/data-privacy-policy.qmd).
+For more information, refer to our [data privacy policy](/about/data-privacy-policy.qmd).
 
 ## Can the tool automatically document other non-standard ETL steps or performance metrics from notebooks?
 

diff --git a/site-unused/get-started-closed-beta.qmd → site-unused/qmd/get-started-closed-beta.qmd b/site-unused/get-started-closed-beta.qmd → site-unused/qmd/get-started-closed-beta.qmd
diff --git a/site-unused/index-old.qmd → site-unused/qmd/index-old.qmd b/site-unused/index-old.qmd → site-unused/qmd/index-old.qmd
@@ -57,12 +57,12 @@ html:
                                     </div>
                                 </div>
                             </div>
-                            <a class="btn btn-primary" role="button" style="padding: 12px;color: var(--bs-white);background: #DE257E;border-radius: 4px;margin-top: 64px;font-family: 'Inter';font-style: normal;font-weight: 700;font-size: 14px;line-height: 100%;border: 1px solid var(--bs-pink);" href="guide/quickstart-try-developer-framework-with-jupyterhub.html">QuickStart</a>
+                            <a class="btn btn-primary" role="button" style="padding: 12px;color: var(--bs-white);background: #DE257E;border-radius: 4px;margin-top: 64px;font-family: 'Inter';font-style: normal;font-weight: 700;font-size: 14px;line-height: 100%;border: 1px solid var(--bs-pink);" href="guide/try-with-jupyterhub.html">QuickStart</a>
                         </div>
                     </div>
                 </div>
                 <div class="col-lg-12 col-xl-1 col-xxl-1"></div>
-                <div class="col-xl-6 col-xxl-7 d-flex d-lg-flex justify-content-center justify-content-lg-center"><img class="img-fluid" src="assets/img/Group%2038-2.png" style="position: relative;overflow: clip;padding-top: 40px;"></div>
+                <div class="col-xl-6 col-xxl-7 d-flex d-lg-flex justify-content-center justify-content-lg-center"><img class="img-fluid" src="assets/img/validmind-demo-screen.png" style="position: relative;overflow: clip;padding-top: 40px;"></div>
             </div>
         </div>
     </section>
@@ -78,7 +78,7 @@ html:
                 </div>
                 <div class="col-xl-1" style="padding: 0px;"></div>
                 <div class="col" style="padding: 0;padding-left: 0;margin-bottom: 32px;">
-                    <div class="card" style="border-style: none;background: transparent;"><img class="card-img-top w-100 d-block" style="border-radius: 8px;" src="assets/img/f1.png">
+                    <div class="card" style="border-style: none;background: transparent;"><img class="card-img-top w-100 d-block" style="border-radius: 8px;" src="assets/img/validmind-flowchart.png">
                         <div class="card-body" style="padding-top: 12px;padding-bottom: 12px;">
                             <h4 class="card-title">Model Developers</h4>
                             <p class="card-text" style="margin-bottom: 0;">Automate your model documentation and testing tasks with the {{< var vm_framework >}}.</p><a class="text-nowrap" type="button" style="padding: 0;color: var(--bs-pink);background: transparent;border-radius: 4px;margin-top: 24px;font-family: 'Inter';font-style: normal;font-weight: 700;font-size: 14px;line-height: 100%;border: 1px none #475569;text-decoration: underline;" href="guide/get-started-developer-framework.html">Get started</a>
@@ -88,7 +88,7 @@ html:
                 </div>
                 <div class="col-xl-1 col-xxl-1" style="padding: 0px;width: 2%;"></div>
                 <div class="col" style="padding: 0;padding-right: 0px;">
-                    <div class="card" style="border-style: none;background: transparent;"><img class="card-img-top w-100 d-block" style="border-radius: 8px;" src="assets/img/f2.png">
+                    <div class="card" style="border-style: none;background: transparent;"><img class="card-img-top w-100 d-block" style="border-radius: 8px;" src="assets/img/validmind-validation.png">
                         <div class="card-body" style="padding-top: 12px;padding-bottom: 12px;">
                             <h4 class="card-title">Model Validators</h4>
                             <p class="card-text" style="margin-bottom: 0;">Review and evaluate models and documentation to ensure they comply with organizational &amp; regulatory requirements.</p><a class="text-nowrap" type="button" style="padding: 0;color: var(--bs-pink);background: transparent;border-radius: 4px;margin-top: 24px;font-family: 'Inter';font-style: normal;font-weight: 700;font-size: 14px;line-height: 100%;border: 1px none #475569;text-decoration: underline;" href="guide/preparing-validation-reports.html">Get started</a>
@@ -107,7 +107,7 @@ html:
                     <p style="margin-bottom: 28px;color: var(--bs-gray-400);padding: 16px;background: transparent;border-radius: 0;padding-top: 0;padding-bottom: 0;padding-right: 0;border: 1px none var(--bs-white);border-left-style: solid;border-left-color: var(--bs-gray-400);"><strong>Need some help? Try our self-service documentation or email us at:&nbsp;</strong><a href="mailto:[email protected]"><strong><span style="text-decoration: underline;">[email protected]</span></strong></a></p><a class="btn btn-secondary" role="button" style="padding: 12px;color: var(--bs-white);background: transparent;border-radius: 4px;margin-top: 4px;font-family: 'Inter';font-style: normal;font-weight: 700;font-size: 14px;line-height: 100%;margin-right: 8px;border: 1px solid var(--bs-white);border-left-color: var(--bs-white);" href="faq/faq.html">Frequently Asked Questions</a><a class="btn btn-primary" role="button" style="padding: 12px;color: var(--bs-white);background: #DE257E;border-radius: 4px;margin-top: 8px;font-family: 'Inter';font-style: normal;font-weight: 700;font-size: 14px;line-height: 100%;border: 1px solid var(--bs-pink);" href="https://validmind.com/contact/">Request A Demo</a>
                 </div>
                 <div class="col-lg-1" style="padding: 0;"></div>
-                <div class="col-lg-5 col-xl-5 d-md-flex d-lg-flex d-xl-flex justify-content-md-center justify-content-lg-center align-items-lg-end justify-content-xl-center" style="padding: 0;padding-right: 0;margin-bottom: -40px;"><img class="img-fluid" src="assets/img/Group%2026.png" style="max-width: 100%;"></div>
+                <div class="col-lg-5 col-xl-5 d-md-flex d-lg-flex d-xl-flex justify-content-md-center justify-content-lg-center align-items-lg-end justify-content-xl-center" style="padding: 0;padding-right: 0;margin-bottom: -40px;"><img class="img-fluid" src="assets/img/validmind-support.png" style="max-width: 100%;"></div>
             </div>
         </div>
     </section>

diff --git a/site-unused/join-closed-beta.qmd → site-unused/qmd/join-closed-beta.qmd b/site-unused/join-closed-beta.qmd → site-unused/qmd/join-closed-beta.qmd
diff --git a/site-unused/login.qmd → site-unused/qmd/login.qmd b/site-unused/login.qmd → site-unused/qmd/login.qmd
diff --git a/site-unused/manage-users-and-roles.qmd → site-unused/qmd/manage-users-and-roles.qmd b/site-unused/manage-users-and-roles.qmd → site-unused/qmd/manage-users-and-roles.qmd
diff --git a/...unused/mermaid-diagrams-dev-framework.qmd → ...ed/qmd/mermaid-diagrams-dev-framework.qmd b/...unused/mermaid-diagrams-dev-framework.qmd → ...ed/qmd/mermaid-diagrams-dev-framework.qmd
diff --git a/site-unused/mrm-lifecyle.qmd → site-unused/qmd/mrm-lifecyle.qmd b/site-unused/mrm-lifecyle.qmd → site-unused/qmd/mrm-lifecyle.qmd
diff --git a/site-unused/mrm-three-lines-of-defense.qmd → ...unused/qmd/mrm-three-lines-of-defense.qmd b/site-unused/mrm-three-lines-of-defense.qmd → ...unused/qmd/mrm-three-lines-of-defense.qmd
diff --git a/site-unused/mrm.qmd → site-unused/qmd/mrm.qmd b/site-unused/mrm.qmd → site-unused/qmd/mrm.qmd
diff --git a/site-unused/onboard-initial-users.qmd → site-unused/qmd/onboard-initial-users.qmd b/site-unused/onboard-initial-users.qmd → site-unused/qmd/onboard-initial-users.qmd
diff --git a/site/guide/restapi.qmd → site-unused/qmd/restapi.qmd b/site/guide/restapi.qmd → site-unused/qmd/restapi.qmd
diff --git a/site-unused/review-documentation.qmd → site-unused/qmd/review-documentation.qmd b/site-unused/review-documentation.qmd → site-unused/qmd/review-documentation.qmd
diff --git a/site-unused/tutorials.qmd → site-unused/qmd/tutorials.qmd b/site-unused/tutorials.qmd → site-unused/qmd/tutorials.qmd