Add support for HTTP redirects

README.md

@@ -59,6 +59,56 @@ properties.
 [How to add a press release page.](doc/press.md)
+## Redirects
+
+Before creating a new page, make sure it's located correctly to [avoid future
+redirects](https://developers.google.com/speed/docs/insights/AvoidRedirects).
+Redirects affect the site performance and its structure as a whole. Sometimes
+they are necessary, though, and better than returning 404s.
+
+If you deprecate a webpage, don't just delete it, but make sure to redirect
+it to another page.
+
+To redirect a page to another one, add to the page's frontmatter a variable/value
+pair indicating the link to redirect it to. Redirects work for both internal and
+external pages.
+
+```md
+---
+# YAML frontmatter
+redirect_to: 'link-to-redirect-the-page-to'
+---
+```
+
+To redirect a given page to an internal page, use the relative path starting at the root of the
+website with `/`. See the examples below.
+
+### Redirect examples
+
+To redirect a certain page to the `about.gitlab.com` home page:
+
+```yaml
+redirect_to: '/'
+```
+
+To redirect a given page to an internal page, let's say, the handbook's homepage:
+
+```yaml
+redirect_to: '/handbook/'
+```
+
+To redirect a given page to a certain blog post:
+
+```yaml
+redirect_to: '/2018/08/22/gitlab-11-2-released/'
+```
+
+To redirect a given page to an external page, **always** start with the HTTP protocol:
+
+```yaml
+redirect_to: 'https://docs.gitlab.com'
+```
+
 ## PDF files
 [How to work with PDFs.](doc/pdf.md)

source/includes/layout/meta.html.haml

+- if current_page.data.redirect_to
+  %meta{ content: "0;url=#{current_page.data.redirect_to}", 'http-equiv' => "refresh"}
+
 - description = current_page.data.description
 - if !description
   - description = "Code, test & deploy with GitLab. Everyone can contribute!"