Git-based CMS: editing Markdown and publishing updates

Let editors publish through a Git-based CMS without treating every file edit as live. Compare Markdown storage, review, previews and deployment checks.

A Git-based CMS lets editors change website content through an editing interface while Git records the file changes. Publishing depends on the configured review and deployment workflow. A saved draft can remain private while the public buying guide keeps its earlier wording.

Choose Git-backed editing when your team wants content changes reviewed alongside the site’s files. Choose a flat-file CMS when file storage suits your hosting, even if Git plays no part in publishing.

Git, Markdown and flat files are different choices

Git records versions, Markdown describes text formatting and a flat-file CMS stores content in files. These choices can overlap, but each answers a different question.

Consider a fictional retailer updating a rainwear buying guide. The editor needs to change the advice, replace a photograph and correct a delivery-policy reference.

Authoring choices for the same buying guide

ApproachWhere the guide livesHow the editor changes itWhen it fits
Markdown files edited directlyFiles in a Git repositoryA text editor and a proposed file changeEditors know Markdown and can work with developers on review
Decap CMS with its GitHub backendContent files committed to a repositoryConfigured form fields and a Markdown editorEditors need a content interface while developers retain Git review
GravFiles used by the hosted CMSThe chosen editing tools for that installationThe team wants file-based publishing without requiring a Git-driven release

Decap documents both direct publication and an editorial workflow. With its default configuration, saving writes to the configured publication branch. Enabling its editorial workflow introduces draft branches and pull requests, which are proposed changes awaiting a merge.

Grav’s documentation describes a file-based platform using Markdown and YAML configuration. That makes it a flat-file example. Git-based approval is a separate implementation choice.

A Markdown field inside another CMS tells you how text is entered. It does not establish where the CMS stores that text or whether saving creates a Git commit. Ask where the rainwear guide’s authoritative content lives before selecting an editor.

Give editors the access their job requires

Authentication establishes who the editor is, while repository permissions and branch rules determine what they can change. The CMS’s visible workflow must match those controls.

For Decap’s direct GitHub backend, the documentation requires editors to have repository push access and sign in with GitHub. Authentication also needs a supported server-side arrangement. A CMS login alone does not establish restricted content-only permissions.

Use the following responsibility split when designing the retailer’s workflow:

  1. The developer configures the content fields, repository connection and publishing branch. They also maintain authentication and the hosting integration.
  2. The editor changes the buying guide on a draft branch and submits it for review. An unsaved local draft exists only in the editor’s working environment.
  3. The policy owner checks any changed delivery promise against the store’s current policy. The reviewer checks the rendered guide and its image.
  4. The authorised publisher merges the approved change after required checks pass. The hosting integration then builds and deploys the publication branch.

Configure repository rules to enforce this split. GitHub branch protection can require approvals and passing status checks, subject to the repository’s plan and settings. Review bypass permissions too, because an administrator’s exception can undermine the intended approval boundary.

In Decap’s editorial workflow, publishing merges the pull request. Treat that permission as release authority wherever the host automatically deploys merged changes. A CMS status called Ready does not replace enforced approval rules.

Follow the change into the public site

A buying-guide update reaches shoppers only after its content and assets pass the publishing pipeline. Trace one version through each stage so an editor’s successful save cannot hide a failed release.

  1. Validate the changed file. Require the guide’s title, route and expected content fields, and reject malformed metadata before merge.
  2. Resolve its photograph. Confirm the stored media path matches the public image URL and that the file exists in the build input. Decap configures upload storage and public media paths separately.
  3. Build a preview of the proposed change. Netlify Deploy Previews provide a separate site for supported pull-request workflows. Open the guide there and inspect its links and delivery wording.
  4. Merge the approved version. Record the commit associated with the release and confirm the host builds that version successfully.
  5. Open the public guide. Confirm the revised sentence and photograph appear at the intended route. Compare the deployment’s commit with the approved commit if the page remains stale.

An editor preview shows how content might render within the CMS. A deployed preview exercises more of the actual site. Neither establishes that the production URL serves the approved version.

If a connected answer service imports this guide, include its refresh in the release check. Ask a question answered by the changed passage and inspect the source version it uses. A new public page does not automatically update a separately stored answer source.

Match publication failures to their checks

SymptomResponsible checkNext action
The file has an invalid required fieldContent validation or the site buildCorrect the file before approving it
The proposed change cannot mergeBranch rules, reviewer approval or failing status checksResolve the named requirement without bypassing review
The guide has a broken photographMedia-path validation and rendered previewCorrect the file reference or include the missing asset
The public guide retains old adviceDeployment version and public-route checkFind the failed build, wrong branch or stale cache before declaring publication complete

Handle concurrent edits and recovery

Concurrent edits need a review of the combined result, especially when two people change the same policy reference. A Git difference shows changed lines, but someone must still judge whether the resulting advice is correct.

Suppose one editor replaces the rainwear photograph while another changes the delivery wording. Separate file changes can merge cleanly. Two edits to the same lines can require conflict resolution. Even a clean merge needs a final preview because related changes can disagree without causing a textual conflict.

Restore an earlier content version through a new reviewed change. Compare that version with the retailer’s current policy before publishing it. Reverting the whole buying guide could also restore an expired delivery promise or discard a newer product recommendation.

Recovery ends when the corrected guide renders publicly with its intended image and policy reference. If an answer service consumes the guide, confirm its source updates too.

Budget for hosting, authentication maintenance and build failures alongside the editor interface. Someone must renew credentials, update dependencies, manage editor departures and preserve recoverable media. A free CMS licence or repository does not assign those jobs.

Before adopting the workflow, have an editor submit one guide change and have the designated publisher release it. Keep the setup only if both people can identify the approved version, the public version and the route for correcting a mistake.

Give your store its own shopping agent

Customers ask in their own words. Your agent finds, compares and checks out from your catalogue, right on your site.

See it in actionFree trial · Simple setup