Creating a Static Site with Decap CMS: Headless CMS on Git

Decap CMS supports several authentication backends:

• GitHub OAuth—via Netlify Identity or a third-party OAuth proxy.
• GitLab—similarly.
• Git Gateway—a Netlify-specific proxy that doesn’t require direct repository access.

For non-Netlify hosting, use a separate OAuth server:

backend: name: github repo: username/my-site base_url: https://your-oauth-server.com 

A minimalistic OAuth proxy on Express deploys on Railway or Fly.io in 30 minutes.

Project Structure

my-site/ ├── public/ │ └── admin/ │ ├── index.html # CMS interface │ └── config.yml # Collection configuration ├── content/ │ ├── posts/ │ │ ├── first-post.md │ │ └── second-post.md │ └── pages/ │ └── about.md ├── src/ │ └── ... # Frontend code └── astro.config.mjs 

The CMS entry point is a CDN script in public/admin/index.html. No npm packages for the interface—just load [email protected] from CDN.

Collection Configuration

# public/admin/config.yml backend: name: github repo: username/my-site branch: main media_folder: public/images/uploads public_folder: /images/uploads locale: en collections: - name: posts label: Posts folder: content/posts create: true slug: "{{year}}-{{month}}-{{day}}-{{slug}}" fields: - { label: Title, name: title, widget: string } - { label: Publish Date, name: date, widget: datetime } - { label: Cover Image, name: cover, widget: image, required: false } - { label: Description, name: description, widget: text, required: false } - { label: Tags, name: tags, widget: list, required: false } - { label: Content, name: body, widget: markdown } - name: pages label: Pages files: - label: About Us name: about file: content/pages/about.md fields: - { label: Title, name: title, widget: string } - { label: Content, name: body, widget: markdown } 

Reading Content in Astro

// src/pages/blog/[slug].astro --- import { getCollection } from 'astro:content' export async function getStaticPaths() { const posts = await getCollection('posts') return posts.map(post => ({ params: { slug: post.slug }, props: { post }, })) } const { post } = Astro.props const { Content } = await post.render() --- <article> <h1>{post.data.title}</h1> <time>{post.data.date.toLocaleDateString('en-US')}</time> <Content /> </article> 

Our Practical Case: Documentation Portal (From Our Practice)

For one of our clients—a technical documentation portal with over 50 pages—we migrated from a WordPress site with a MySQL database to a static site built with Astro and Decap CMS. The project used to require a $30/month VPS for the database and backend, and editors struggled with the slow WordPress admin. After migration:

• Hosting costs dropped to zero (GitHub Pages).
• Build time reduced by 75% (from 8 minutes to 2 minutes) using Astro's incremental builds.
• Editors now work in a clean, fast interface with real-time preview.
• Every change is versioned in Git—rollback is a single revert commit.

This case demonstrates our guaranteed expertise and proven experience with headless CMS.

Work Process

What’s Included and Deliverables

• Backend development: configuring Decap CMS, setting up OAuth authentication.
• Integration with a static site generator (Astro, Next.js, Hugo).
• CI/CD setup for automatic build and deployment.
• Detailed documentation on content structure and deployment procedures.
• Provision of admin access credentials and repository access.
• Editor training (1–2 hours) on using the CMS interface.
• One month of support after launch—bug fixes and minor adjustments.

Timelines: business card site or blog—3–7 days; corporate site with 5–8 page types, custom widgets, and CI/CD—2–3 weeks.

Request a Consultation

Contact us—we’ll tell you if Decap CMS fits your tasks, estimate timelines and cost. We’ve been doing web development for over 5 years and have completed more than 50 projects on headless CMS. Get a consultation on your project.