Raibid Labs Documentation

Public vs Private Documentation

5 min read

Public vs Private Documentation

Quick reference comparing the public and private documentation repositories.

Side-by-Side Comparison

FeaturePublic Docs (docs)Internal Docs (docs-internal)
Repositoryraibid-labs/docsraibid-labs/docs-internal
VisibilityPublicPrivate
AggregatesPublic repos onlyAll repos (public + private)
DeploymentGitHub PagesLocal/Cloudflare Pages/Artifacts
AccessAnyoneOrganization members only
URLhttps://raibid-labs.github.io/docsCustom or local only
Auto-syncDaily at 2 AM UTCDaily at 2 AM UTC
ContentOpen source docsConfidential + public docs

Configuration Differences

Public Docs (config/ignorelist.json)

{
  "exclude_private": true,
  "require_docs_directory": true,
  "repositories": ["docs"]
}

Internal Docs (config/ignorelist.json)

{
  "exclude_private": false,
  "require_docs_directory": true,
  "repositories": ["docs", "docs-internal"]
}

Key Difference: exclude_private setting determines which repos are included.

When to Use Each

Use Public Docs (docs) For:

  • ✅ Open source project documentation
  • ✅ Public API documentation
  • ✅ Community-facing guides
  • ✅ Contributing guidelines
  • ✅ Public architecture overviews
  • ✅ Tutorial content
  • ✅ External developer resources

Use Internal Docs (docs-internal) For:

  • ✅ Private repository documentation
  • ✅ Confidential architecture details
  • ✅ Internal processes and workflows
  • ✅ Security implementation details
  • ✅ Infrastructure documentation
  • ✅ Business logic and algorithms
  • ✅ Team-specific guides
  • ✅ Deployment procedures with secrets

Workflow Comparison

Public Docs Workflow

graph LR
    A[GitHub API] -->|Discover public repos| B[Filter by ignorelist]
    B -->|Add as submodules| C[Git Submodules]
    C -->|Pull docs| D[Build with Quartz]
    D -->|Deploy| E[GitHub Pages]
    E -->|Public access| F[Anyone can view]

Internal Docs Workflow

graph LR
    A[GitHub API] -->|Discover all repos| B[Filter by ignorelist]
    B -->|Add as submodules| C[Git Submodules]
    C -->|Pull docs| D[Build with Quartz]
    D -->|Deploy| E[Cloudflare Pages + Access]
    E -->|Authenticated| F[Org members only]

Access Control

Public Docs

  • Read access: Everyone on the internet
  • Write access: Organization members with repo permissions
  • Edit workflow: Fork, edit, pull request

Internal Docs

  • Read access: Organization members only
  • Write access: Organization members with repo permissions
  • Edit workflow: Direct commit or pull request

Deployment Options

Public Docs

OptionStatusCostSetup
GitHub Pages✅ EnabledFreeAutomatic

Internal Docs

OptionRecommendedCostSetup Complexity
Local buildsGood for small teamsFreeEasy
GitHub Actions artifactsGood for occasional viewingFreeEasy
Cloudflare Pages + AccessBest for frequent accessFree (<50 users)Moderate
GitHub Enterprise PagesEnterprise only$21/user/monthEasy

Maintenance

Both repositories share the same automation scripts, making maintenance straightforward:

Shared Scripts

  • discover-repos.nu - Repository discovery
  • sync-submodules.nu - Submodule management
  • update-docs.nu - Documentation indexing
  • build-site.nu - Build pipeline

Repository-Specific

  • config/ignorelist.json - Different settings per repo
  • .github/workflows/sync-and-deploy.yml - Different deployment targets
  • quartz.config.ts - Different site titles/branding

Cost Analysis

Public Docs

  • Hosting: $0 (GitHub Pages)
  • CI/CD: $0 (GitHub Actions free tier)
  • Total: $0/month
  • Hosting: $0 (Cloudflare Pages)
  • Authentication: $0 (Cloudflare Access, <50 users)
  • CI/CD: $0 (GitHub Actions free tier)
  • Total: $0/month

Note: Both solutions are completely free for most organizations.

Migration Paths

From Public-Only to Two-Repo

✅ Current status - Just add internal repo following the setup guide

From Two-Repo to Single-Repo Dual-Build

If you later want to consolidate (advanced):

  1. Make public docs repo private
  2. Implement dual-build system:
    • Public build (filtered content)
    • Full build (all content)
  3. Deploy public build to GitHub Pages
  4. Deploy full build to Cloudflare Pages + Access
  5. Archive docs-internal repo

Complexity: High | Benefit: Single source of truth

Recommendation: Stick with two-repo approach unless you have specific needs for consolidation.

Security Considerations

Public Docs

  • ⚠️ Never commit secrets or sensitive information
  • ⚠️ Review all docs before making repo public
  • ⚠️ Use .gitignore for sensitive files
  • ✅ Great for open source transparency

Internal Docs

  • ⚠️ Still avoid committing secrets (use env vars/secrets)
  • ⚠️ Review access permissions regularly
  • ⚠️ Monitor for unauthorized access attempts
  • ✅ Safe for confidential architecture and processes

Best Practices

Documentation Organization

Public Docs:

docs/content/
├── projects/          # Public project documentation
├── guides/            # Public getting started guides
└── api/               # Public API documentation

Internal Docs:

docs/content/
├── projects/          # All project documentation
├── guides/            # Internal processes and guides
├── architecture/      # Confidential system architecture
├── infrastructure/    # Infrastructure and deployment
└── security/          # Security implementations

Content Tagging

Use frontmatter tags to categorize content:

Public Docs:

---
tags: [public, tutorial, api, getting-started]
---

Internal Docs:

---
tags: [internal, confidential, architecture, infrastructure]
---

Quick Decision Tree

Do you need to share docs publicly?
├─ Yes → Use public docs repo
│   └─ Do you also have private repos with docs?
│       ├─ Yes → Also setup internal docs repo
│       └─ No → Only public docs repo needed
└─ No → Only internal docs repo needed

FAQ

A: Yes, but links from public → internal will be broken for external users. Use conditional content if needed.

Q: How do I move a doc from internal to public?

A:

  1. Move the doc in the source repository from private → public
  2. Update the repository visibility if needed
  3. Wait for next sync or trigger manually

Q: Can I have different themes for each?

A: Yes, edit quartz.config.ts in each repository independently to customize branding and themes.

Q: What if I accidentally commit secrets to public docs?

A:

  1. Immediately rotate the compromised secrets
  2. Remove from git history: git filter-branch or BFG Repo-Cleaner
  3. Force push cleaned history
  4. Notify security team

Q: How do I control who can access internal docs?

A: If using Cloudflare Access:

  1. Configure access policies (GitHub OAuth, email domains, etc.)
  2. Regularly review access logs
  3. Use short session timeouts
  4. Enable 2FA requirements

Resources

Last updated: 2025-10-29

Graph View

Backlinks