## Problem to solve One of the most frequent points of feedback from our roll-out of the Static Site Editor in the GitLab Handbook has been the volume of changes made to the source file simply as a result of opening the page in the WYSIWYG editor. We have tried to [limit this](https://gitlab.com/gitlab-org/gitlab/-/issues/218474) by matching the expected Markdown formatting to the documented [GitLab Markdown style guide](https://about.gitlab.com/handbook/markdown-guide/). However, the reality is that many of the pages on the GitLab handbook to not adhere strictly to this style guide. The WYSIWYG editor has to convert the Markdown to HTML, then back to Markdown using the "correct" and more strict syntax. The unfortunate result, especially on very long pages, is that many lines of code are changed. This might mean converting unordered lists from using `*` to `-`, adjusting spacing and indentation, applying "proper" emphasis syntax to bold and italic text, or removing extra blank lines. Combined with a limitation of the MR page where extremely long diffs can't be visualized, this can mean the page can't be effectively reviewed in the Merge Request. ## Important note It's worth calling out that this is somewhat amplified by the format and complexity of the GitLab handbook itself. On a project that was edited exclusively with the Static Site Editor or written with more strict Markdown syntax, the MRs would be nowhere near as noisy. ## Proposals There are several approaches we can take with this and the solution might be a combination of more than one. Some ideas that have come out of discussions and user feedback are: 1. Limit the scope of changes to only the lines of code that are _actually_ edited by the user. In effect, ignore the formatting on anything the user didn't touch. 1. Pre-commit the formatting changes to an MR and then submit the user input as a second commit. This would result in the same number of changes but at least the diffs for the specific commit with the intentional changes would be distinguished from the formatting. 1. Move toward a more intentional, user-triggered "Clean up" button in the UI that would perform the formatting step. ## Examples - [This MR](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests/64347/diffs) was intended to change one letter. It resulted in changes to 102 lines of code. ## Strategy ### Separate changes into a different commit * [x] [Commit pre-formatted changes to facilitate the visualization of changes introduced by the user](https://gitlab.com/gitlab-org/gitlab/-/issues/277083). * [ ] [Display a warning sign when the Static Site Editor applies a significant amount of formatting changes](https://gitlab.com/gitlab-org/gitlab/-/issues/277086) ### Markdown formatting tool * [ ] [Implement a markdown formatter tool](https://gitlab.com/gitlab-org/gitlab/-/issues/285242) * [ ] [Apply markdown formatter tool to changes submitted via the Static Site Editor](https://gitlab.com/gitlab-org/gitlab/-/issues/285251) * [ ] [Restart the initiative of pre-formatting handbook pages](https://gitlab.com/gitlab-com/www-gitlab-com/-/issues/8892) * [ ] Evaluate the possibility of applying the formatter in a CI Job in `www-gitlab-com`.