Proposal: Sync Select Documentation Sections to the GhostBSD Website
Objective
To improve consistency, reduce duplication, and present a more polished experience to users, I propose that specific sections of the GhostBSD documentation (hosted on ReadTheDocs) be synchronized with the main website.
Rather than copying content manually or maintaining parallel versions, we can automate this process so that designated documentation sections (e.g., About, FAQ, Contribute, or Getting Started) serve as the single source of truth and are reflected on the website automatically.
Problem
Many portions of the website mirror content that already exists, or should exist, in the official documentation. Maintaining them separately results in:
Content drift and inconsistencies
Wasted effort in editing the same material twice
Confusion for newcomers when the website and documentation say different things
Solution
Select key documentation files (like about.md, faq.md, contributing.md) as canonical sources. Then use a GitHub Actions workflow to automatically sync those files to the GhostBSD website repository.
This allows the documentation to remain the primary source of technical and community information, while the website presents up-to-date, polished summaries for new users and visitors.
Proposed Workflow
Identify which documentation sections should also appear on the website.
Mark or organize those files clearly in the docs repo (e.g., under docs/websync/).
Use a GitHub Actions workflow to:
Detect changes to these specific files
Copy them into the corresponding location in the GhostBSD website repository
Push the changes automatically
Example: GitHub Actions Workflow
name: Sync Selected Docs to Website
on:
push:
paths:
- 'docs/websync/*.md'
jobs:
sync-docs:
runs-on: ubuntu-latest
steps:
- name: Checkout docs repo
uses: actions/checkout@v4
- name: Clone website repo
uses: actions/checkout@v4
with:
repository: ghostbsd/ghostbsd-website
token: ${{ secrets.WEBSITE_REPO_TOKEN }}
path: website-repo
- name: Copy selected docs to website
run: |
cp docs/websync/*.md website-repo/content/pages/
- name: Commit and push updates
run: |
cd website-repo
git config user.name "GhostBSD Bot"
git config user.email "bot@ghostbsd.org"
git add content/pages/
git commit -m "Sync selected documentation pages"
git push
Benefits
Aligns key messaging between website and documentation
Reduces editorial overhead and duplication
Prevents stale content and confusion
Provides a sustainable path for long-term consistency
