Add latest changes from gitlab-org/gitlab@13-5-stable-eev13.5.0-rc42

1 files changed, 123 insertions, 46 deletions

diff --git a/doc/user/project/static_site_editor/index.md b/doc/user/project/static_site_editor/index.md
index ce14cefba92..8a2f62ec7a2 100644
--- a/doc/user/project/static_site_editor/index.md
+++ b/doc/user/project/static_site_editor/index.md
@@ -6,50 +6,43 @@ type: reference, how-to
 description: "The static site editor enables users to edit content on static websites without prior knowledge of the underlying templating language, site architecture or Git commands."
 ---
 
-# Static Site Editor
+# Static Site Editor **(CORE)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/28758) in GitLab 12.10.
 > - WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214559) in GitLab 13.0.
-> - Support for adding images through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216640) in GitLab 13.1.
-> - Markdown front matter hidden on the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216834) in GitLab 13.1.
-> - Support for `*.md.erb` files [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223171) in GitLab 13.2.
 > - Non-Markdown content blocks uneditable on the WYSIWYG mode [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216836) in GitLab 13.3.
 
-DANGER: **Danger:**
-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
-[snippet](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/snippets/1976539)
-to update your project with the latest changes.
-
-Static Site Editor enables users to edit content on static websites without
+Static Site Editor (SSE) enables users to edit content on static websites without
 prior knowledge of the underlying templating language, site architecture, or
 Git commands. A contributor to your project can quickly edit a Markdown page
 and submit the changes for review.
 
 ## 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:
 
-- 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.
-- 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
 
 - 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).
-- The editor needs to be logged into GitLab and needs to be a member of the
-project (with Developer or higher permission levels).
+  pre-configured with the [Static Site Editor Middleman template](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman).
+- You need to be logged into GitLab and be a member of the
+  project (with Developer or higher permission levels).
 
 ## 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
 using it. The project template is configured to deploy a [Middleman](https://middlemanapp.com/)
 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:
 
 ![Edit this page button](img/edit_this_page_button_v12_10.png)
@@ -65,44 +58,128 @@ 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
 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
-easily edit your 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)
-or [create a new project from a template](../../../gitlab-basics/create-project.md#built-in-templates).
-1. Edit the `data/config.yml` file adding your project's path.
-1. Editing the file triggers a CI/CD pipeline to deploy your project with GitLab Pages.
+easily [edit your content](#edit-content).
+
+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)
+   or [create a new project from a template](../../../gitlab-basics/create-project.md#built-in-templates).
+1. Edit the [`data/config.yml`](#configuration-files) configuration file
+   to replace `<username>` and `<project-name>` with the proper values for
+   your project's path. This 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. 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
 codebase.
 
-NOTE: **Note:**
-From GitLab 13.1 onwards, 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
-GitLab file editor, or the Web IDE.
+## Edit content
+
+> - Support for modifying the default merge request title and description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216861) in GitLab 13.5.
+
+After setting up your project, you can start editing content directly from the Static Site Editor.
+
+To edit a file:
+
+1. Visit the page you want to edit.
+1. Click the **Edit this page** button.
+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. When you're done, click **Submit changes...**.
+1. (Optional) Adjust the default title and description of the merge request that will be submitted with your changes.
+1. Click **Submit changes**.
+1. A new merge request is automatically created and you can assign a colleague for review.
+
+### Text
+
+> Support for `*.md.erb` files [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223171) in GitLab 13.2.
+
+The Static Site Editors supports Markdown files (`.md`, `.md.erb`) for editing text.
+
+### 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
 
-### Use the Static Site Editor to edit your content
+> - Support for embedding YouTube videos through the WYSIWYG editor [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216642) in GitLab 13.5.
 
-For instance, suppose you are a recently hired technical writer at a large
-company and a new feature has been added to the company product.
+You can embed YouTube videos on the WYSIWYG mode by clicking the video icon (**{live-preview}**).
+The following URL/ID formats are supported:
 
-1. You are assigned the task of updating the documentation.
-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.
+- YouTube watch URL (e.g. `https://www.youtube.com/watch?v=0t1DgySidms`)
+- YouTube embed URL (e.g. `https://www.youtube.com/embed/0t1DgySidms`)
+- YouTube video ID (e.g. `0t1DgySidms`)
+
+### Front matter
+
+> - 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:
+
+   ![Editing page front matter in the Static Site Editor](img/front_matter_ui_v13_4.png)
+
+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
+[snippet](https://gitlab.com/gitlab-org/project-templates/static-site-editor-middleman/snippets/1976539)
+to update your project with the 13.0 changes.
 
 ## Limitations
 
-- 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.