docs-portal-sync-and-deploy

Synchronizes research documentation into a MkDocs portal and deploys it to GitHub Pages.

1|Updated Sep 1, 2026
One-click install
npx skills add https://github.com/nvtruongops/pi-guard --skill docs-portal-sync-and-deploy-nvtruongops
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: docs-portal-sync-and-deploy
Source: https://github.com/nvtruongops/pi-guard/tree/main/.agents/skills/docs-portal-sync-and-deploy
Command: npx skills add https://github.com/nvtruongops/pi-guard --skill docs-portal-sync-and-deploy-nvtruongops

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires mkdocs, mkdocs-material.

What problem does it solve? Keeping a thesis, research reports, and reference lists in sync with a public documentation website is error-prone: links break, citation anchors go missing, and paywalled DOIs frustrate readers. This Skill standardizes the entire sync-and-publish workflow so the documentation portal stays consistent and deployable. ## Core Features & Use Cases - Automated Portal Aggregation: Runs build scripts that collect thesis chapters, review reports, and references from the repository into the MkDocs-based Github-Page directory. - Quality Auditing: Validates workspace boundaries, immutable files, JSON manifests, link integrity, YouTube oEmbed status, and Open-Access PDF availability before publishing. - One-Command Deployment: Builds with MkDocs in strict mode and publishes to the gh-pages branch, followed by a live HTTP health check. - Use Case: After updating a thesis chapter, run the 7-step SOP to regenerate the portal, pass all local QA checks, push to main, and deploy the updated site to GitHub Pages. ## Quick Start Ask the agent to sync the latest thesis and report changes into the documentation portal, run the full local validation suite, and deploy the site to GitHub Pages.

Frequently Asked Questions about docs-portal-sync-and-deploy

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I deploy an MkDocs site to GitHub Pages?

Run python -m mkdocs gh-deploy --force from the repository root after building the portal content. This compiles the site from the Github-Page directory using mkdocs.yml and pushes the static output to the gh-pages branch.

How do I fix missing anchor warnings in MkDocs strict mode?

Open the flagged Markdown file, find the citation like [[N]](#refN), and ensure the references section contains a matching HTML anchor such as <a id="refN"></a>. Rebuild with mkdocs --strict until no warnings remain.

How do I handle paywalled DOI links that return HTTP 403?

Do not hyperlink the DOI directly; write it as inline code text like DOI: 10.xxxx/yyyy. Then add an Open-Access PDF link from arXiv, OpenAlex, or Semantic Scholar so readers can access the paper.

Can team members edit the documentation portal directly?

No. Members work only inside their workspaces/<member>/ sandbox directories. Only the designated leader runs the sync scripts, merges into Final-Report and Github-Page, and publishes to main and gh-pages.

Why does the YouTube link verification fail during the audit?

The verification script queries the official YouTube oEmbed endpoint for each video URL. It fails when a video is private, deleted, or region-restricted, so replace it with a publicly available video link.