diff options
Diffstat (limited to 'doc/development/documentation/index.md')
| -rw-r--r-- | doc/development/documentation/index.md | 43 |
1 files changed, 20 insertions, 23 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 9f9c6288963..ec57de35dfb 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -77,13 +77,24 @@ whether the move is necessary), and ensure that a technical writer reviews this change prior to merging. If you indeed need to change a document's location, do not remove the old -document, but instead replace all of its content with a new line: +document, but instead replace all of its content with the following: ```md -This document was moved to [another location](path/to/new_doc.md). +--- +redirect_to: '../path/to/file/index.md' +--- + +This document was moved to [another location](../path/to/file/index.md). ``` -where `path/to/new_doc.md` is the relative path to the root directory `doc/`. +Where `../path/to/file/index.md` is usually the relative path to the old document. + +The `redirect_to` variable supports both full and relative URLs, for example +`https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`. +It ensures that the redirect will work for <https://docs.gitlab.com> and any `*.md` paths +will be compiled to `*.html`. +The new line underneath the frontmatter informs the user that the document +changed location and is useful for someone that browses that file from the repository. For example, if you move `doc/workflow/lfs/index.md` to `doc/administration/lfs.md`, then the steps would be: @@ -92,12 +103,16 @@ For example, if you move `doc/workflow/lfs/index.md` to 1. Replace the contents of `doc/workflow/lfs/index.md` with: ```md + --- + redirect_to: '../../administration/lfs.md' + --- + This document was moved to [another location](../../administration/lfs.md). ``` 1. Find and replace any occurrences of the old location with the new one. - A quick way to find them is to use `git grep`. First go to the root directory - where you cloned the `gitlab` repository and then do: + A quick way to find them is to use `git grep` on the repository you changed + the file from: ```shell git grep -n "workflow/lfs/lfs_administration" @@ -124,24 +139,6 @@ Things to note: built-in help page, that's why we omit it in `git grep`. - Use the checklist on the "Change documentation location" MR description template. -### Alternative redirection method - -You can also replace the content -of the old file with a frontmatter containing a redirect link: - -```yaml ---- -redirect_to: '../path/to/file/README.md' ---- -``` - -It supports both full and relative URLs, e.g. `https://docs.gitlab.com/ee/path/to/file.html`, `../path/to/file.html`, `path/to/file.md`. Note that any `*.md` paths will be compiled to `*.html`. - -NOTE: **Note:** -This redirection method will not provide a redirect fallback on GitLab `/help`. When using -it, make sure to add a link to the new page on the doc, otherwise it's a dead end for users that -land on the doc via `/help`. - ### Redirections for pages with Disqus comments If the documentation page being relocated already has Disqus comments, |