Skip to main content

Way of Working

This page explains how to contribute content to the PCP Improvement Program Documentation Portal, where to find the CI/CD pipeline, and how to troubleshoot build errors.

🚀 TL;DR – How to add or edit a page​

  1. Go to the repo: PCP-Improvement-Program-Documentation in ADO
  2. Navigate to portal/pcp-improvement-program-docs/docs/
  3. Edit an existing file or create a new .md file
  4. Commit and push to main
  5. Wait ~3 minutes — the portal rebuilds and deploys automatically
How do I know it worked?

Check the pipeline status. Green = changes are live at https://docs.polaris.automation.abb.com

Important rules
  • Keep all files only in portal/pcp-improvement-program-docs/docs/ — files elsewhere won't appear on the portal
  • The filename becomes the URL, e.g. My-Page.md → /pcp-improvement-program/My-Page
  • Links to other portal pages must use relative paths: [text](./Page-Name) ✅, not /Page-Name ❌
  • If you add an image — put it in portal/pcp-improvement-program-docs/static/.attachments/, otherwise the build will fail

Repository​

All documentation content lives in the ADO repository:

PCP-Improvement-Program-Documentation

The main branch (main) is the source of truth. Changes pushed to main automatically trigger a build and deployment.

Where to Edit Content​

All documentation pages are located in:

portal/pcp-improvement-program-docs/docs/
  • Each page is a .md or .mdx file
  • The filename becomes the URL slug (e.g. my-page.md → /pcp-improvement-program/my-page)
  • index.md is the landing page at /pcp-improvement-program/

Adding a new page​

  1. Create a new .md file in portal/pcp-improvement-program-docs/docs/
  2. Optionally add front matter to control order and title:
---
sidebar_position: 2
title: My Page Title
---

# My Page Title

Content goes here.
  1. Push to main — the portal rebuilds automatically.

Adding images​

  1. Place image files in portal/pcp-improvement-program-docs/static/.attachments/
  2. Reference them in Markdown:
![Alt text](/.attachments/my-image.png)
warning

If you reference an image that is not in the repository, the build will fail.

CI/CD Pipeline​

The pipeline runs automatically on every push to main.

View pipeline runs: 👉 PCP-Improvement-Program-CICD

Steps performed:

  1. Build — docusaurus build compiles the portal
  2. Deploy — pushes the static output to Azure Static Web Apps

Build takes approximately 2–3 minutes. After a successful run, changes are live at:

👉 https://docs.polaris.automation.abb.com

Common Build Errors​

❌ Image not found​

Error: Image static/.attachments/my-image.png used in ../docs/index.md not found.

Fix: Add the image file to portal/pcp-improvement-program-docs/static/.attachments/ or remove the reference from the Markdown file.

❌ MDX compilation failed​

Error: MDX compilation failed for file "..."

Fix: Check the file for invalid syntax — unclosed JSX tags, special characters (<, >) not escaped, or invalid front matter.

❌ Glossary validation errors​

[glossary-plugin] Glossary file has validation errors: "terms" array missing

This is a warning only — the build continues. The glossary at portal/glossary/glossary.json needs a terms array to work correctly, but this does not block the deployment.

❌ Broken links (Page Not Found)​

If clicking a link on the portal returns Page Not Found, the link is using an absolute path.

Fix: Use relative paths in Markdown links:

[My Page](./My-Page)   ✅
[My Page](/My-Page)    ❌

Adding Videos​

Azure Static Web Apps file size limit: 30 MB

Do not commit video files larger than 30 MB to the repository. Deployment will fail.

Small videos (< 30 MB)​

  1. Place the video file in portal/pcp-improvement-program-docs/static/videos/
  2. Reference it in Markdown:
<video width="640" height="360" controls>
  <source src="/videos/my-video.mp4" type="video/mp4"/>
  Your browser does not support the video tag.
</video>

Large videos (> 30 MB)​

Upload to SharePoint / Microsoft Stream and embed using an <iframe>:

<iframe width="640" height="360"
  src="https://your-sharepoint-embed-url"
  frameborder="0" allowfullscreen>
</iframe>

Need Help?​

For portal infrastructure issues, register a service request:

👉 ServiceNow – IIoT Information Portal