Gitlab hero border pattern left svg Gitlab hero border pattern right svg

Category Direction - Static Site Editor

Static Site Editor

Stage Maturity Content Last Reviewed
Create Viable 2020-12-29

Introduction and how you can help

This is the category direction page for the Static Site Editor in GitLab. This page belongs to the Editor group of the Create stage and is maintained by Sr. Product Manager, Eric Schurter.

Established as a category in late 2019, the Static Site Editor is relatively new to GitLab. Our direction is evolving quickly as we iterate on our initial MVC and work to deliver value to as many GitLab users as possible. We'd love to hear from you, especially if you manage or collaborate on static websites.

Sharing your questions or feedback directly on is the best way to contribute to our category direction. Please don't hesitate to leave a comment on our issues or epics and, of course, we welcome community contributions. If you'd rather provide feedback privately or schedule a video call, you can email our Product Manager, (Eric Schurter).


Our mission is to ensure that creating and editing content on static websites does not require deep knowledge of any particular templating language, Markdown syntax, or git branching workflows. The Static Site Editor category is focused on delivering a familiar and intuitive content editing experience that enables efficient collaboration on static sites across all users, on any platform, regardless of their technical experience.

Static websites are a flexible and performant option for many types of sites, including blogs, documentation portals, and portfolios. These use cases necessitate the ability for content to be edited quickly, frequently, and often away from a desktop computer. For this reason, the goal is to deliver a delightful content editing experience on desktops, tablets, and mobile devices.

Target Audience

Challenges to address

Creating, configuring, and hosting a static website

From choosing a programming language and a static site generator to configuring a deployment pipeline and managing their domain, users are required to make a series of decisions and piece together multiple services to create and deploy a static website from scratch. If they want to collaborate on content, yet another service might be added into the mix to manage content and provide an editing experience accessible by everyone. Users need a single place to create, configure, edit, and host their static web content.

This is a workflow that GitLab is well positioned to address and the Static Site Editor is one of the last remaining pieces needed to deliver this end-to-end experience. This opportunity is one that we have not fully addressed in the current iteration of the Static Site Editor, but it will be an area where we will be investing time to validate the problem space.

Editing content on an existing static page

Collaborating on static web content can be a challenging, even intimidating experience for a variety of reasons.

To get around these problems, developers have to decide whether they are either going to force their contributors to learn the technical skills required to edit content or integrate with a headless CMS or other abstraction of the data model. The former can be prohibitive to collaboration and the latter can be costly and complicated to maintain.

Creating new content on a static website

Workflows that require creating, moving, or deleting content on a static website suffer from the same challenges as editing, but introduce additional complexities, especially for users who aren't familiar with the project's information architecture and directory structure. Users can struggle to:

Similar workarounds are in place for these workflows, but often rely on either learned behavior or managing content in only the most advanced, fully-featured content management systems.

Publishing quality content to a static website

Once the edits have been made, the content still has to get built and deployed before it is available on the web. This can be a time-consuming process and one that can fail in many places along the way.

The Git-based workflow is perfectly suited to handle these challenges, but it does require a significant amount of prior knowledge around version control and local development environments. A proper CMS can abstract all of this away from the user, but often does so at the expense of flexibility, preventing those who do know the inner-workings of Git from performing advanced tasks.

Where we are Headed

Contributors want to limit context switching between the site itself and the underlying repository structure, so the editing experience for content hosted on a static site should be accessible and available in the context of the webpage itself.

The editing experience will be intuitive and scalable for those who do not know, or do not wish to write, Markdown. To compliment a more "what you see is what you get" (WYSIWYG) editing experience, we'll make it possible to preview the edits live and in real-time on the site using the page's custom styles and layout.

At the end of the journey, publishing content to the site will be improved by abstracting and streamlining a lot of the process related to creating branches, committing changes, and creating merge requests while maintaining the power of a versioned, distributed, git-based backend.

What's Next & Why

Now that the Static Site Editor is available to everyone in the form of a Middleman-based project template and fully integrated into the GitLab Handbook, we are focused on:

  1. Implement a new, modular rich text editor
  2. Making the editor more configurable to better support real-world projects
  3. Handling more complex publishing workflows
  4. Making it easier to access the static site editor
  5. Extending the reach of the static site editor

A new foundation for editing rich text

The Static Site Editor is effectively a rich text Markdown editor with specific extensions and capabilities to support managing content intended to be parsed by a static site generator. The current architecture is a tightly-coupled package that includes a rich text HTML editor, a Markdown parser, and a code editor. Extending the functionality of this foundation has become challenging and we now have an opportunity to step back and architect a solution focused on extensibility and reusability.

The new architecture is based on a looser coupling of the three main elements:

  1. A rich text editor
  2. A Markdown parser
  3. A source code editor

We already have a great source code editor in GitLab. Editing source code in the single file editor, Snippets, or the Static Site Editor should be a consistent experience, so we'll use Editor Lite.

One of the most significant challenges in scaling the Static Site Editor comes in to play when we think about how the editor is going to interact with elements that aren't Markdown. Static site generators can interpret templating markup, embedded helpers, partials, or even data files. The current architecture relies on the visual editor itself to identify non-Markdown content at runtime. This is a fragile approach and can impact performance. By decoupling the rich text, visual editor from the Markdown parser itself, we're able to:

  1. extend the Markdown parser separately to support different syntax or languages
  2. extend the Editor separately to visualize custom components sent by the Markdown parser
  3. entirely replace the Markdown parser without impacting the Editor, for example using a server-side endpoint to translate Markdown to HTML
  4. use the Editor many other places in GitLab, including the Wiki and issue descriptions, and realize a consistent and maintainable rich text editing experience

Configuring the Static Site Editor

Publishing workflows

Editor discoverability


What is Not Planned Right Now

Right now, we are not planning on investing any time in developing a new framework for generating static sites or forking an existing project to extend its functionality. We are also not choosing a single static site generator on which to build our product. Instead, our goal is to provide a solution that works across many, if not all, of the most popular platforms like Middleman, Jekyll, Hugo, and Gatsby.

The Static Site Editor group is not working toward a solution that allows users to create static sites from scratch without writing code. The initial setup of a static site will, for now, remain something that requires at least some technical knowledge and configuration.

We are also not planning to build a way to visually edit relational databases, API, or other dynamic content. As the group name suggests, our focus is on bringing a user-friendly interface for editing static content.

While we hope to provide visual formatting tools for a more familiar text editing experience, the underlying text markup language will remain Markdown. We will not support writing content in alternative markup languages like LaTeX, Org-mode, or Asciidoc.

Maturity Plan

This category is currently at the Viable maturity level (see our definitions of maturity levels).

The Category Strategy epic is where we're planning the work necessary to reach Complete maturity. This includes a re-architecture of the WYSIWYG editor to deliver a block-based editing experience, a way to create new pages and make multiple edits across multiple pages, extending the editor to support other static site generators beyond Middleman, and a way to re-use content across multiple pages. We plan on reaching Complete maturity by July 22, 2021.

User success metrics

It doesn't matter as much to us whether a merge request gets deployed and while we hope everyone gets a chance to try out the Static Site Editor, simply opening up the editor doesn't mean you've contributed any content. Our primary performance indicator revolves entirely around a commit action, which is an indication of a successful contribution.

We want to encourage more people to commit more often. This would mean that users of services outside of GitLab to edit content can be brought into the platform to streamline their collaboration. It also means that existing users will be exposed to more features GitLab has to offer across the many stages of the DevOps workflow.

Why is this important?

A delightful, accessible editing experience is the last piece of the puzzle for enabling end-to-end management of static sites within GitLab. The end goal is to streamline collaboration with engineers by bringing users into GitLab rather than spreading the work across multiple products, resulting in both cost and time efficiencies for our users.

Competitive Landscape

Products that directionally inspire our vision for editing static sites:

Products that help people in organizations collaborate on information together like our Handbook:

Git is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license