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.

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.

Need Help?​

For portal infrastructure issues, register a service request:

👉 ServiceNow – IIoT Information Portal