Multi-repository documentation aggregator for the Open Service Portal project, built with Docusaurus.
This repository automatically collects and publishes documentation from all Open Service Portal repositories to a unified documentation site at docs.openportal.dev.
- Automatic Documentation Collection: GitHub Actions fetch docs from all repos daily
- Multi-Docs Support: Each repository gets its own documentation section
- Unified Navigation: Easy navigation between different project components
- Version Control: Each doc section links back to its source repository
- Auto-deployment: Pushes to main automatically deploy to docs.openportal.dev
docusaurus/
βββ docs/ # Main documentation
βββ external-docs/ # Auto-collected docs (gitignored)
β βββ portal-workspace/ # Workspace documentation
β βββ app-portal/ # Backstage app docs
β βββ catalog/ # Catalog documentation
β βββ templates/ # All template docs
βββ scripts/
β βββ collect-docs.sh # Local doc collection script
βββ .github/workflows/
β βββ deploy.yml # Auto-deploy to GitHub Pages
βββ docusaurus.config.ts # Docusaurus configuration
- Node.js 20 or higher
- npm
- Clone this repository:
git clone https://github.com/open-service-portal/docusaurus.git
cd docusaurus
- Install dependencies:
npm install
- Collect documentation from other repos:
./scripts/collect-docs.sh
- Start the development server:
npm start
The site will be available at http://localhost:3000.
npm run build
This command generates static content in the build
directory.
The documentation hub aggregates content from:
- portal-workspace: Main workspace and architecture documentation
- app-portal: Backstage application documentation
- catalog: Template catalog documentation
-
Crossplane Templates:
- template-dns-record
- (more to be added)
-
Backstage Service Templates:
- service-nodejs-template
- service-mongodb-template
- service-cluster-template
- service-firewall-template
- service-dnsrecord-template
- service-mongodb-golden-path-template
The site automatically deploys to GitHub Pages when:
- Changes are pushed to the
main
branch - Daily at 2 AM UTC (to fetch latest docs from all repos)
- Manually triggered via GitHub Actions
To add documentation from a new repository:
- Update
.github/workflows/deploy.yml
to clone and copy the new repo's docs - Update
scripts/collect-docs.sh
for local development - Add a new plugin section in
docusaurus.config.ts
if it needs its own route - Update navigation in
docusaurus.config.ts
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
The site is configured to deploy to docs.openportal.dev
. DNS configuration:
- CNAME record:
docs.openportal.dev
βopen-service-portal.github.io
This project is part of the Open Service Portal and follows the same licensing terms.