Set up your public knowledgebase

This guide walks you through turning a connected repository into a public help center on your-team.moxiedocs.app. Nothing reaches GitHub or the public web until you approve it.

What you’ll need

• A Moxie Docs workspace with GitHub connected and at least one repository indexed
• Beta access to Public Knowledgebase (request access from Dashboard → Public Knowledgebase if you don’t have it yet)
• Permission to open pull requests on the repo where docs will land

How the flow works

1. Generate — Moxie drafts help-center pages from your codebase (privately in Moxie).
2. Approve — You review drafts in the inbox. Approval does not publish them.
3. Open PRs — Approved pages become pull requests of Markdown files in your target repo.
4. Merge — After merge, Moxie indexes the files into the public site cache.
5. Publish — You toggle pages live on {subdomain}.moxiedocs.app.

Approve and publish are independent gates. A page can sit merged-but-unpublished forever.

Step 1: Get beta access

1. Open Dashboard → Public Knowledgebase.
2. If you see a Request access panel, submit a request and wait for approval.
3. When access is granted, Moxie routes you into setup (or your existing review inbox).

Tip: Workspace admins may need a Moxie team member to grant the public_knowledgebase flag if you are in a private beta cohort.

Step 2: Run the setup wizard

1. Open Dashboard → Public Knowledgebase → Setup (or follow the redirect after access is granted).
2. Name & subdomain — Pick a globally unique subdomain. Your site will be https://{subdomain}.moxiedocs.app. Custom domains are not available in beta.
3. Target repo — Choose where approved Markdown lands (same repo or another connected repo). Generation always uses your active repository as the source of product context.
4. Docs folder — Path inside the target repo (default is often knowledgebase). Moxie creates it if needed.
5. Audience — Developer, end user, or both. This shapes tone and which page types get planned.
6. Review & launch — Confirm choices and start the first draft generation job.

You land in the Review inbox while drafts generate. Refresh if the list is still empty after a few minutes.

Step 3: Review and approve drafts

1. Open Dashboard → Public Knowledgebase → Review.
2. Expand a draft, read the Markdown preview, then Approve or Dismiss.
3. Use section batch actions when a whole group looks good.
4. Drafts marked Needs review — source files changed are stale updates; regenerate or dismiss them before publishing older content.

Optional: open a draft Preview to read it full-width before approving.

Step 4: Open PRs and merge

1. When at least one draft is approved, click Open PRs.
2. Moxie groups approved pages and opens pull request(s) on the target repository.
3. Review the PR on GitHub like any docs change, then merge.

Merged files become the durable copy in git. Moxie syncs them into the public site cache (including a fast path on push for knowledgebase paths).

Step 5: Publish pages on the hosted site

1. In the Review inbox, open the Published tab (or the list of pages ready to go live).
2. Toggle Publish on pages you want on the public site.
3. Open https://{subdomain}.moxiedocs.app and confirm the page appears.

Unpublish anytime from the same controls. Unpublished pages stay in git; they just do not render on the hosted site.

Step 6: Branding (optional)

1. Open Dashboard → Public Knowledgebase → Settings.
2. Set:
   • Title — help center name in the header
   • Logo URL — optional https:// image
   • Accent color — optional hex (e.g. #0ea5e9) for the header accent and active nav
3. Save and hard-refresh the public site.

Keeping docs current

• Regenerate — Queues a new generation pass grounded in the latest product model and feedback.
• Stale updates — Appear when source files used for a draft change after generation.
• Article feedback on the public site — Feeds future generation when readers report issues.
• Edit — Use the edit link on a published page to open Moxie’s repo doc editor for that Markdown file.

Troubleshooting

Symptom	What to try
No access to setup	Request access; confirm a teammate granted the public knowledgebase beta flag.
Empty review inbox after launch	Wait for the generation job; check indexing/jobs for kb_generate failures.
PR open fails	Confirm GitHub App access to the target repo and that the org can open PRs.
Site shows empty shell	Pages must be published after merge—not only approved.
Branding not showing	Logo must be HTTPS; accent must be #RGB or #RRGGBB. Hard-refresh the public URL.
Wrong kind of docs (internals)	Prefer product-facing README/marketing/UI signals; dismiss bad drafts and regenerate.

What beta does not include yet

• Custom domains (e.g. docs.yourcompany.com)
• Full white-label (removing the Moxie footer)
• Enterprise KB-only RBAC

Those ship after the subdomain beta is stable.