Static Site Editor enables users to edit content on static websites without
prior knowledge of the underlying templating language, site architecture, or
prior knowledge of the underlying templating language, site architecture, or
Git commands. A contributor to your project can quickly edit a Markdown page
Git commands. A contributor to your project can quickly edit a Markdown page
and submit the changes for review.
and submit the changes for review.
## Use cases
## Use cases
The Static Site Editors allows collaborators to submit changes to static site
The Static Site Editor allows collaborators to submit changes to static site
files seamlessly. For example:
files seamlessly. For example:
- Non-technical collaborators can easily edit a page directly from the browser; they don't need to know Git and the details of your project to be able to contribute.
- Non-technical collaborators can easily edit a page directly from the browser;
they don't need to know Git and the details of your project to be able to contribute.
- Recently hired team members can quickly edit content.
- Recently hired team members can quickly edit content.
- Temporary collaborators can jump from project to project and quickly edit pages instead of having to clone or fork every single project they need to submit changes to.
- Temporary collaborators can jump from project to project and quickly edit pages instead
of having to clone or fork every single project they need to submit changes to.
## Requirements
## Requirements
- In order use the Static Site Editor feature, your project needs to be
- In order use the Static Site Editor feature, your project needs to be
pre-configured with the [Static Site Editor Middleman template](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman).
pre-configured with the [Static Site Editor Middleman template](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman).
-The editor needs to be logged into GitLab and needs to be a member of the
-You need to be logged into GitLab and be a member of the
project (with Developer or higher permission levels).
project (with Developer or higher permission levels).
## How it works
## How it works
The Static Site Editor is in an early stage of development and only works for
The Static Site Editor is in an early stage of development and only supports
Middleman sites for now. You have to use a specific site template to start
Middleman sites for now. You have to use a specific site template to start
using it. The project template is configured to deploy a [Middleman](https://middlemanapp.com/)
using it. The project template is configured to deploy a [Middleman](https://middlemanapp.com/)
static website with [GitLab Pages](../pages/index.md).
static website with [GitLab Pages](../pages/index.md).
Once your website is up and running, you'll see a button **Edit this page** on
Once your website is up and running, an **Edit this page** button displays on
the bottom-left corner of its pages:
the bottom-left corner of its pages:
...
@@ -61,61 +53,64 @@ click of a button:
...
@@ -61,61 +53,64 @@ click of a button:
You can also edit the page's front matter both in WYSIWYG mode via the side-drawer and in Markdown
mode.
When an editor submits their changes, in the background, GitLab automatically
When an editor submits their changes, in the background, GitLab automatically
creates a new branch, commits their changes, and opens a merge request. The
creates a new branch, commits their changes, and opens a merge request. The
editor lands directly on the merge request, and then they can assign it to
editor lands directly on the merge request, and then they can assign it to
a colleague for review.
a colleague for review.
## Getting started
## Set up your project
First, set up the project. Once done, you can use the Static Site Editor to
First, set up the project. Once done, you can use the Static Site Editor to
easily edit your content.
easily [edit your content](#edit-content).
### Set up your project
1. To get started, create a new project from the [Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman)
template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork)
1. To get started, create a new project from the
or [create a new project from a template](../../../gitlab-basics/create-project.md#built-in-templates).
[Static Site Editor - Middleman](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman)
1. Edit the [`data/config.yml`](#configuration-files) configuration file
template. You can either [fork it](../repository/forking_workflow.md#creating-a-fork)
to replace `<username>` and `<project-name>` with the proper values for
or [create a new project from a template](../../../gitlab-basics/create-project.md#built-in-templates).
your project's path. This triggers a CI/CD pipeline to deploy your project
1. Edit the `data/config.yml` file adding your project's path.
with GitLab Pages.
1. Editing the file triggers a CI/CD pipeline to deploy your project with GitLab Pages.
1. When the pipeline finishes, from your project's left-side menu, go to **Settings > Pages** to find the URL of your new website.
1. When the pipeline finishes, from your project's left-side menu, go to **Settings > Pages** to find the URL of your new website.
1. Visit your website and look at the bottom-left corner of the screen to see the new **Edit this page** button.
1. Visit your website and look at the bottom-left corner of the screen to see the new **Edit this page** button.
Anyone satisfying the [requirements](#requirements)will be able to edit the
Anyone satisfying the [requirements](#requirements)can edit the
content of the pages without prior knowledge of Git or of your site's
content of the pages without prior knowledge of Git or of your site's
codebase.
codebase.
NOTE: **Note:**
## Edit content
From GitLab 13.1 onward, the YAML front matter of Markdown files is hidden on the
WYSIWYG editor to avoid unintended changes. To edit it, use the Markdown editing mode, the regular
After setting up your project, you can start editing content directly from the Static Site Editor.
GitLab file editor, or the Web IDE.
To edit a file:
NOTE: **Note:**
1. Visit the page you want to edit.
A new configuration file for the Static Site Editor was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4267)
1. Click the **Edit this page** button.
in GitLab 13.4. Beginning in 13.5, the `.gitlab/static-site-editor.yml` file will store additional
1. The file is opened in the Static Site Editor in **WYSIWYG** mode. If you
configuration options for the editor. When the functionality of the existing `data/config.yml` file
wish to edit the raw Markdown instead, you can toggle the **Markdown** mode
is replicated in the new configuration file, `data/config.yml` will be formally deprecated.
in the bottom-right corner.
1. When you're done, click **Submit changes...**.
1. Describe your changes (add a commit message).
1. Click **Submit changes**.
1. A new merge request is automatically created and you can assign a colleague for review.
### Use the Static Site Editor to edit your content
### Text
For instance, suppose you are a recently hired technical writer at a large
> Support for `*.md.erb` files [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223171) in GitLab 13.2.
company and a new feature has been added to the company product.
1. You are assigned the task of updating the documentation.
The Static Site Editors supports Markdown files (`.md`, `.md.erb`) for editing text.
1. You visit a page and see content that needs to be edited.
1. Click the **Edit this page** button on the production site.
1. The file is opened in the Static Site Editor in **WYSIWYG** mode. If you wish to edit the raw Markdown
instead, you can toggle the **Markdown** mode in the bottom-right corner.
1. You edit the file right there and click **Submit changes**.
1. A new merge request is automatically created and you assign it to your colleague for review.
## Videos
### Images
> - Support for adding images through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216640) in GitLab 13.1.
You can add image files on the WYSIWYG mode by clicking the image icon (**{doc-image}**).
From there, link to a URL, add optional [ALT text](https://moz.com/learn/seo/alt-text),
and you're done. The link can reference images already hosted in your project, an asset hosted
externally on a content delivery network, or any other external URL. The editor renders thumbnail previews
so you can verify the correct image is included and there aren't any references to missing images.
default directory (`source/images/`).
### Videos
> - Support for embedding YouTube videos through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216642) in GitLab 13.5.
> - Support for embedding YouTube videos through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216642) in GitLab 13.5.
...
@@ -126,6 +121,63 @@ The following URL/ID formats are supported:
...
@@ -126,6 +121,63 @@ The following URL/ID formats are supported:
> - Markdown front matter hidden on the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216834) in GitLab 13.1.
> - Ability to edit page front matter [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235921) in GitLab 13.5.
Front matter is a flexible and convenient way to define page-specific variables in data files
intended to be parsed by a static site generator. It is commonly used for setting a page's
title, layout template, or author, but can be used to pass any kind of metadata to the
generator as the page renders out to HTML. Included at the very top of each data file, the
front matter is often formatted as YAML or JSON and requires consistent and accurate syntax.
To edit the front matter from the Static Site Editor you can use the GitLab's regular file editor,
the Web IDE, or easily update the data directly from the WYSIWYG editor:
1. Click the **Page settings** button on the bottom-right to reveal a web form with the data you
have on the page's front matter. The form is populated with the current data:
1. Update the values as you wish and close the panel.
1. When you're done, click **Submit changes...**.
1. Describe your changes (add a commit message).
1. Click **Submit changes**.
1. Click **View merge request** and GitLab will take you there.
Note that support for adding new attributes to the page's front matter from the form is not supported
yet. You can do so by editing the file locally, through the GitLab regular file editor, or through the Web IDE. Once added, the form will load the new fields.
## Configuration files
The Static Site Editor uses Middleman's configuration file, `data/config.yml`
to customize the behavior of the project itself and to control the **Edit this
page** button, rendered through the file [`layout.erb`](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/-/blob/master/source/layouts/layout.erb).
To [configure the project template to your own project](#set-up-your-project),
you must replace the `<username>` and `<project-name>` in the `data/config.yml`
file with the proper values for your project's path.
[Other Static Site Generators](#using-other-static-site-generators) used with
the Static Site Editor may use different configuration files or approaches.
## Using Other Static Site Generators
Although Middleman is the only Static Site Generator currently officially supported
by the Static Site Editor, you can configure your project's build and deployment
to use a different Static Site Generator. In this case, use the Middleman layout
as an example, and follow a similar approach to properly render an **Edit this page**
button in your Static Site Generator's layout.
## Upgrade from GitLab 12.10 to 13.0
In GitLab 13.0, we [introduced breaking changes](https://gitlab.com/gitlab-org/gitlab/-/issues/213282)
to the URL structure of the Static Site Editor. Follow the instructions in this
- The Static Site Editor still cannot be quickly added to existing Middleman sites. Follow this [epic](https://gitlab.com/groups/gitlab-org/-/epics/2784) for updates.
- The Static Site Editor still cannot be quickly added to existing Middleman sites.
Follow this [epic](https://gitlab.com/groups/gitlab-org/-/epics/2784) for updates.
