How to build a GitHub Pages site for team docs with AI
The problem
Our team used to document in Confluence. Recently the company decided to drop it. But honestly, Confluence was already failing us before that — information scattered across pages no one updated, outdated docs that were more misleading than helpful, and a tool that made editing feel like enough work that people just didn't bother.
As a data team, we had some documentation covered: technical specs lived in GitHub, metadata about tables and models lived in Unity Catalog of our data warehouse. But everything else — metrics definitions, roadmap, dashboard inventory, how-to guides for stakeholders — had no home. We needed a hub.
The solution
I built a GitHub Pages site for the Pro data team in about 30 minutes using Claude Code. No HTML knowledge required. No web developer involved. It has been live since, and the team uses it as their primary reference.
Why GitHub Pages works well for this:
- One permanent URL
- Free to host, version-controlled by default
- Engineers already trust GitHub — it fits naturally into how the team works
How to do it
1. Start with structure, not content. Before writing a single page, talk to Claude Code about what the site needs. Share your existing Confluence structure, describe your team's use cases, and let it propose a site map.
Here's what our actual site map looks like:
Pro Data Hub ├── Dashboards │ ├── Business Monitoring │ ├── Sales Monitoring │ ├── Scorecard │ ├── Marketing │ ├── Funnel View │ └── User DNA & Behaviour ├── Knowledge Base │ ├── Metrics Definitions │ ├── Table Reference │ ├── Architecture │ └── Genie Guide ├── Roadmaps ├── News └── Team
Agree on the structure before building anything — changing the navigation later is easy, but starting without a clear map means you'll be reorganising content before you've even filled it.
2. Pick a template. Claude Code can suggest one based on your needs, or you can describe what you want. Keep it simple — clear navigation and readable pages matter more than design.
3. Let Claude Code set up the repo and the site. It creates the GitHub repository, scaffolds the pages, and configures GitHub Pages. You review and approve. This is the part that used to require a developer.
4. Feed it content and adjust. Paste in your existing documentation (Confluence pages, Google Slides, PDFs, Google Sheets, Google Docs), define a template for the content, and iterate. You make the decisions; Claude handles the formatting and file structure.
5. Add automation. This is where it gets genuinely useful — and where I spent most of my time. Two examples from our setup:
Dashboard inventory synced from a Google Sheet. We maintain a spreadsheet tracking all our dashboards — name, owner, status, development stage, link. A GitHub Action runs every Monday morning, reads the sheet, and rewrites the dashboards page with the latest information. Status tags (Live, In Progress, Planned) update automatically. No manual HTML editing required.
Data model updates synced from Slack. When our data engineers post updates to a specific Slack channel — table deprecations, schema changes, migration notices — a daily GitHub Action picks up those messages, parses them, and adds formatted entries to a news page on the site. Stakeholders can check the site instead of digging through Slack history.
Neither automation required me to write the logic from scratch. I described what I wanted, Claude Code wrote it, I tested it and made small adjustments.
6. Share and collect feedback. Send the link to colleagues. The barrier to giving feedback on a clean webpage is much lower than on a Confluence page.
Honest challenges
GitHub access. Not everyone in my company has GitHub access by default. In practice this is easy to solve — access can be granted quickly, and most companies already have a process for it.
The jungle problem. If every team does this independently, we end up with dozens of disconnected GitHub Pages sites with no shared structure. The real answer is to agree on a hierarchy: company wiki, domain wiki, function wiki. Without that, you're moving the Confluence mess to a new address. But agreement at an organisational level takes time and requires the right people to drive it. Our solution: build the site now, and when a company or department agreement is in place, migrate the content to the future repo. Claude Code makes that migration straightforward.
Maintenance and contribution. How do you make people actively contribute? Easiness is the key. The more you can remove friction — through automation, through simple templates, through AI-assisted editing for non-technical colleagues — the more the site stays alive. I have more ideas on this; will share in a future post.
Closing
Documentation fails not because people don't care, but because the cost of maintaining it is always higher than the urgency of doing it. A static site built with AI doesn't eliminate that cost — but it lowers it significantly. Automation handles the most repetitive parts. A clear structure makes contributing feel less daunting. And when something needs to change, it takes minutes rather than a Jira ticket.
If your team is post-Confluence and looking for a new home for your docs, this is a practical starting point. It took an afternoon to build. The team has been using it ever since.