Conversation
There was a problem hiding this comment.
Pull request overview
This PR reorganizes and expands the MkDocs documentation to introduce a new “Concepts” section, add a Tutorials landing page, and consolidate security/auth guidance (including recommendations to change default credentials) while updating cross-page links accordingly.
Changes:
- Adds new Concepts pages (Architecture, OOB Management, Control Modes, Security Overview) and updates navigation to include them.
- Adds a Tutorials overview landing page and updates entry points to route readers through it.
- Refactors/retargets several legacy Reference/Get Started links (certificates, passwords/security, scaling) and expands logging documentation.
Reviewed changes
Copilot reviewed 26 out of 26 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Adds Concepts section + Tutorials overview to nav; removes duplicated “Get Help” blocks from other sections. |
| docs/videos.md | Updates provisioning certificate link to Concepts remote provisioning page. |
| docs/index.md | Updates Tutorials CTA to point to the new Tutorials overview page. |
| docs/Tutorials/overview.md | New Tutorials landing page with grouped links and call-to-action buttons. |
| docs/Reference/logging.md | Expands logging docs with log-level configuration and Docker log usage. |
| docs/Reference/architectureOverview.md | Replaces large concept content with a shorter overview and links to new Concepts pages. |
| docs/Reference/RPC/transitionDeviceRPC.md | Updates passwords/security reference link to Concepts security overview. |
| docs/Reference/RPC/overview.md | Reworks RPC-Go version guidance and adds a v2 vs v3 comparison table. |
| docs/Reference/Console/configuration.md | Adds a production warning to change default Console/Web UI credentials. |
| docs/Reference/Certificates/tls.md | Retargets “Remote Provisioning” link to Concepts remote provisioning page. |
| docs/Reference/Certificates/generateProvisioningCert.md | Retargets vendor/purchase link to Concepts remote provisioning page. |
| docs/Reference/Certificates/enrollCustomCertAMT.md | Retargets vendor/purchase link to Concepts remote provisioning page. |
| docs/GetStarted/overview.md | Adds a “Which Path Should I Choose?” Cloud vs Enterprise comparison table. |
| docs/GetStarted/Enterprise/manageDevice.md | Refreshes “Next steps” with clearer follow-on resource grouping and links. |
| docs/GetStarted/Enterprise/createProfileCCM.md | Updates passwords/security reference link to Concepts security overview. |
| docs/GetStarted/Enterprise/createProfileACM.md | Updates provisioning certificate + passwords/security links to Concepts pages. |
| docs/GetStarted/Cloud/manageDevice.md | Fixes wording and adds links for Deployment and MQTT monitoring next steps. |
| docs/GetStarted/Cloud/loginToUI.md | Updates provisioning certificate link to Concepts remote provisioning page. |
| docs/GetStarted/Cloud/createProfileCCM.md | Updates passwords/security reference link to Concepts security overview. |
| docs/GetStarted/Cloud/createProfileACM.md | Updates provisioning certificate + passwords/security links to Concepts pages. |
| docs/Deployment/overview.md | Adds a Scaling & Infrastructure section linking to scaling tutorial overview. |
| docs/Concepts/security.md | New Security Overview page consolidating passwords, certificates, and hardening links. |
| docs/Concepts/remoteProvisioning.md | Updates/cleans remote provisioning doc links and structure. |
| docs/Concepts/oobManagement.md | New OOB Management concept page (in-band vs OOB, power, KVM). |
| docs/Concepts/controlModes.md | New ACM vs CCM concept page with comparisons and links back to workflows. |
| docs/Concepts/architecture.md | New Architecture & Components concept page (with diagram + connection models). |
Comments suppressed due to low confidence (3)
docs/Concepts/remoteProvisioning.md:31
- The Remote Provisioning diagram uses
..\..\assets\..., which resolves outsidedocs/and won’t finddocs/assets/. Fromdocs/Concepts/remoteProvisioning.md, the relative path should only go up one level (e.g.,..\assets\images\...) so the image renders.
docs/Concepts/remoteProvisioning.md:24 - Markdown formatting typo:
**A provisioning certificate*:**has mismatched emphasis markers and will render incorrectly. Remove the stray*so the term is bolded consistently.
docs/Concepts/remoteProvisioning.md:6 - This Concepts page starts with a level-2 heading (
## What is remote provisioning?) and has multiple leading blank lines. Since the other new Concepts pages use an H1 title, add a top-level# Remote Provisioningheading (and trim excess leading whitespace) to keep page titles/TOC consistent in MkDocs Material.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/GetStarted/Cloud/loginToUI.md
Outdated
| <div style="text-align:center;"> | ||
| <iframe width="600" height="337" src="https://www.youtube.com/embed/RYzrHHpMIas" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> | ||
| <figcaption><b>Getting Started Part 2</b>: Follow along to learn about the Sample Web UI and the various profiles: CIRA Configs, AMT Profiles, and Domain Profiles. <b>Additional Resources: </b><a href="../../Reference/architectureOverview#passwords">Passwords and What They Mean</a>, <a href="../../Reference/Certificates/remoteProvisioning">Provisioning Certificates</a>, and <a href="../../Reference/MEBX/dnsSuffix">Setting a DNS Suffix via MEBX</a></figcaption> | ||
| <figcaption><b>Getting Started Part 2</b>: Follow along to learn about the Sample Web UI and the various profiles: CIRA Configs, AMT Profiles, and Domain Profiles. <b>Additional Resources: </b><a href="../../Reference/architectureOverview#passwords">Passwords and What They Mean</a>, <a href="../../Concepts/remoteProvisioning">Provisioning Certificates</a>, and <a href="../../Reference/MEBX/dnsSuffix">Setting a DNS Suffix via MEBX</a></figcaption> |
There was a problem hiding this comment.
The "Passwords and What They Mean" link points to ../../Reference/architectureOverview#passwords, but docs/Reference/architectureOverview.md no longer contains a passwords section/anchor, so this link will be broken. Update the href to the new Security content (e.g., ../../Concepts/security.md or the specific section anchor for passwords/credentials).
docs/videos.md
Outdated
| <p>See how to setup Device Management Toolkit locally using Docker. <br><br><b>Additional Resources: </b><a href="https://www.intel.com/content/www/us/en/developer/topic-technology/edge-5g/hardware/vpro-platform-retail.html">Intel vPro Platform</a></p> | ||
| <p></p> | ||
| <p>Learn how to create custom profiles for device configuration and activation. <br><br><b>Additional Resources: </b><a href="../Reference/architectureOverview#passwords">Passwords and What They Mean</a>, <a href="../Reference/Certificates/remoteProvisioning">Provisioning Certificates</a>, and <a href="../Reference/MEBX/dnsSuffix">Setting a DNS Suffix via MEBX</a></p> | ||
| <p>Learn how to create custom profiles for device configuration and activation. <br><br><b>Additional Resources: </b><a href="../Reference/architectureOverview#passwords">Passwords and What They Mean</a>, <a href="../Concepts/remoteProvisioning">Provisioning Certificates</a>, and <a href="../Reference/MEBX/dnsSuffix">Setting a DNS Suffix via MEBX</a></p> |
There was a problem hiding this comment.
The "Passwords and What They Mean" link targets ../Reference/architectureOverview#passwords, but the passwords section/anchor was removed from Reference/architectureOverview.md, so this will be a dead link. Point this to the new Security Overview page instead (e.g., ../Concepts/security.md).
| Figure 1 illustrates the high-level architecture of Device Management Toolkit microservice architecture. | ||
|
|
||
| <figure class="figure-image"> | ||
| <img src="..\..\assets\images\diagrams\CloudArchitecturalFlow.svg" style="height:800px" alt="Figure 1: Deploy Device Management Toolkit"> |
There was a problem hiding this comment.
The image path goes up two directories (..\..\assets\...), but the repo’s assets live under docs/assets/. From docs/Concepts/architecture.md, the correct relative path should only go up one level (e.g., ..\assets\images\...), otherwise the diagram won’t render.
| <img src="..\..\assets\images\diagrams\CloudArchitecturalFlow.svg" style="height:800px" alt="Figure 1: Deploy Device Management Toolkit"> | |
| <img src="..\assets\images\diagrams\CloudArchitecturalFlow.svg" style="height:800px" alt="Figure 1: Deploy Device Management Toolkit"> |
* docs: add recommendation for auth changes * docs: add more logging information
PR Checklist
What are you changing?
Anything the reviewer should know when reviewing this PR?