## Problem to solve Editing content on a static site requires knowledge and experience with markdown syntax as well as an understanding of the underlying templating language and site architecture. This can make finding the right page to edit difficult for users that lack the necessary context or expertise. Once the right file is located, writing the content in a code editor provides an unfamiliar and under-optimized user experience. ## Audience * [Parker (Product Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#parker-product-manager) * [Presley (Product Designer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#presley-product-designer) Also: * UX Writers, Technical Writers, Copywriters * GitLab Team Members ## Background The GitLab Handbook is a statically generated site built using Middleman. As the GitLab team grows, it is important to reinforce our Handbook-first approach. To support this, we need to make the process for editing and creating pages easier. ## Proposal Our goal is to build a feature that adds value to the GitLab product, then quickly integrate it into the GitLab handbook. Before we can do that, we need to focus on an architecture and end-to-end user experience compatible with Middleman sites of fairly basic complexity. We'll provide a project template pre-configured with the necessary dependencies so that our users can build their own sites that take advantage of the static site editor. Once we establish the architecture, we'll move on to implementing it on the handbook and iterate on the user experience of the editor itself. ### User Journey * Create a new project using a `Middleman static site with visual editor` template * Template preconfigured with * Middleman base install * Custom Middleman extension to track the connection between source file and static output * Configuration for hosting on GitLab Pages * Configuration to enable editable page content * Documentation of the configuration and editing experience * A new project is created and ready to deploy immediately * After the first successful completion of the pipeline, the site is available at the domain configured in the Pages UI * Visit the production URL * Edit link is visible, fixed on the page * Click Edit to navigate to the Static Site Editor * Authenticate with GitLab, if not already authenticated with sufficient permissions * In the Static Site Editor, there is: * The page title and a way to return to the live site * A raw text area with the page's markdown content * A Submit button * Changes are made to the content and the user decides to Submit which: * Creates a new branch * Commits the changes to the newly created branch * Creates an MR * Displays a link to view the MR and a link to return to the production site ### Details & assumptions * Target platform is Middleman * User has a GitLab account * Content is written in a [CommonMark compatible](https://spec.commonmark.org/) Markdown flavor. * The actual editor will live under the GitLab domain, and as a result will not require any additional development servers, containers, or runtime execution of code on the production site. #### Default to on For this iteration, all markdown content in the top-level layout will be considered editable by the Static Site Editor. We will not yet support editing content in nested layouts or partials, nor will we allow the user to disable the editor for a specific page or layout type. ### What this MVP does not do These areas of a viable user journey are not included in the scope of this release but will be considered for future iteration: * [Edit page front matter](https://gitlab.com/groups/gitlab-org/-/epics/2794) * [Visual/WYSIWYG markdown editor](https://gitlab.com/groups/gitlab-org/-/epics/2793) * [Preview content changes on the site](https://gitlab.com/groups/gitlab-org/-/epics/2792) * [Access the static site editor from the GitLab Files UI or elsewhere within the GitLab product](https://gitlab.com/groups/gitlab-org/-/epics/2795) * Edit multiple pages in a single session * Provide additional information (description, labels, etc) with the commit or merge request * Create new pages * Move or delete pages * Edit content live on the page * Upload images and manage assets * [Configure the visibility or behavior of the edit button](https://gitlab.com/groups/gitlab-org/-/epics/2797) * Make changes to the template structure (re-order or add content) * Support Jekyll, Hugo, Gatsby, and other static site generators * Edit content other than Markdown * Edit structured content like JSON and YAML * Preview changes to a file in a split view/side-by-side mode * Validate changes or perform any linting on the edited content ## Permissions & Security Since the editing experience is going to be hosted inside GitLab, the standard permissions and authentication will be inherited from the project. ## Documentation * Documentation will be necessary within the template project, as part of a README.md * Documentation will need to be written in `docs.` * A particular call-out needs to be made that this is an alpha feature in very early development and is likely to change * Documentation for the Middleman extension will be necessary if we make it available to the public ## Success metrics ### Acceptance Criteria * I can open the static site editor from a live page (one hosted in a production environment) * I can make changes to the markdown content that has been defined as editable * I can commit my changes and create a new MR with one click ## Design An early visualization of what an Edit view might look like:  ## Unresolved aspects - [x] Where in the GitLab UI does the static site editing experience sit? It doesn't feel like its worth adding a menu item for it as we won't have any supporting UI to support it. - [x] Which WYSIWYG markdown editor to use