Skip to content

Strategy: Public Documentation with Security Filtering

Objective: Publish documentation to a public URL (GitHub Pages) for stakeholders without GitHub accounts, while stripping out sensitive/internal information.

1. The Architecture: "The Air Gap"

Since your main repository is Private, we cannot simply turn on GitHub Pages for it without keeping it private (or paying for Enterprise). To make it truly public and safe, we use a Two-Repository Model.

flowchart LR
    Private[🔒 Private Monorepo]
    Public[🌍 Public Docs Repo]
    Web[🖥️ GitHub Pages Site]

    Private -->|1. Filter & Build| Dist[Build Artifacts]
    Dist -->|2. Push| Public
    Public -->|3. Deploy| Web
  1. Source: Your current documentation/ folder (Private).
  2. Filter: A script runs in CI to copy only allowed files to a temporary build zone.
  3. Target: A separate public repository (e.g., SD-HOA/singular-dream-docs) that hosts only the sanitized static HTML (or Markdown).

2. The Solution: MkDocs + Material Theme

The GitHub Wiki is great for devs, but for stakeholders, we want a polished website. MkDocs with Material Theme is the industry standard for this because:

  1. It consumes your existing Markdown structure natively.
  2. It looks professional/branded "out of the box."
  3. It supports "Search" that we can scope to public info only.

3. The Filtering Protocol (Security)

We cannot rely on "remembering" to exclude files. We need a Logic Gate.

A. The "Internal by Default" Approach (Ultra-Secure)

We assume everything is private unless explicitly marked Public.

  • Pros: Zero risk of accidental leaks.
  • Cons: You must manually tag every file you want to publish.

B. The "Public by Default" Approach (Maintenance Friendly)

We publish everything except what is marked Private.

  • Pros: Easy maintenance.
  • Cons: Risk of forgetting to tag a new sensitive file.

Recommendation: "Hybrid Allowlist"

We define specific Safe Directories (like blueprints, standards) to publish, but filter out specific Tags.

Mechanism: Add a YAML Frontmatter block to files containing secrets:

---
security: internal
---
# Private Admin Guide...

The Filter Script (Concept):

// tools/publish-docs.ts
const files = listMarkdownFiles();
for (const file of files) {
  const content = read(file);
  const frontmatter = parse(content);

  if (frontmatter.security === "internal") continue; // SKIP
  if (file.path.includes("08_security")) continue; // SKIP ENTIRE FOLDER

  copyToPublicBuild(file);
}

4. Automation Workflow (GitHub Action)

We create a workflow .github/workflows/deploy-public-docs.yml.

The Pipeline

  1. Trigger: On push to main (paths: documentation/**).
  2. Checkout: Get private code.
  3. Sanitize:
    • Run ts-node tools/filter-docs.ts.
    • This script copies allowable files to dist/docs.
  4. Build:
    • Run mkdocs build inside dist/.
    • This generates the HTML site.
  5. Deploy:
    • Use peaceiris/actions-gh-pages to push the HTML to the gh-pages branch of your Public Repo.

5. Next Steps to Implement

  1. Create the Public Repo: Create SD-HOA/singular-dream-docs (Public, Empty).
  2. Install MkDocs:
    • pip install mkdocs-material (or python based)
    • Or use a containerized builder.
  3. Write the Filter Script: A simple TypeScript script to implement the rules above.
  4. Configure .github/workflows: Glue it together.

This ensures that stakeholders get a URL like https://sd-hoa.github.io/singular-dream-docs/ which is always standard, fast, and free of secrets.