Add pages job in yaml document

doc/ci/yaml/README.md

@@ -509,6 +509,35 @@ rspec:
 The cache is provided on best effort basis, so don't expect that cache will be
 always present. For implementation details please check GitLab Runner.
 
+### pages
+
+`pages` is a special job that is used to upload static content to GitLab that
+can be used to serve your website. It has a special syntax, so the two
+requirements below must be met:
+
+1. Any static content must be placed under a `public/` directory
+1. `artifacts` with a path to the `public/` directory must be defined
+
+The example below simply moves all files from the root of the project to the
+`public/` directory. The `.public` workaround is so `cp` doesn't also copy
+`public/` to itself in an infinite loop:
+
+```
+pages:
+  stage: deploy
+  script:
+  - mkdir .public
+  - cp -r * .public
+  - mv .public public
+  artifacts:
+    paths:
+    - public
+  only:
+  - master
+```
+
+Read more on [GitLab Pages user documentation](../../pages/README.md).
+
 ## Validate the .gitlab-ci.yml
 
 Each instance of GitLab CI has an embedded debug tool called Lint.

doc/pages/README.md

@@ -64,7 +64,7 @@ In brief, this is what you need to upload your website in GitLab Pages:
    (ask your administrator). This is very important, so you should first make
    sure you get that right.
 1. Create a project
-1. Provide a specific job named [`pages`](../ci/yaml/README.md#pages) in
+1. Provide a specific job named [`pages`][pages] in
    [`.gitlab-ci.yml`](../ci/yaml/README.md)
 1. A GitLab Runner to build GitLab Pages
 
@@ -112,7 +112,7 @@ access it under `http(s)://groupname.example.io`.
 
 To make use of GitLab Pages, your `.gitlab-ci.yml` must follow the rules below:
 
-1. A special `pages` job must be defined
+1. A special [`pages`][pages] job must be defined
 1. Any static content must be placed under a `public/` directory
 1. `artifacts` with a path to the `public/` directory must be defined
 
@@ -222,3 +222,4 @@ to private, internal or public.
 [pages-daemon]: https://gitlab.com/gitlab-org/gitlab-pages
 [gitlab ci]: https://about.gitlab.com/gitlab-ci
 [gitlab runner]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner
+[pages]: ../ci/yaml/README.md#pages