Single source of truth for GitLab Pages docs
History
I'll start with some history:
- In the beginning we had https://gitlab.com/gitlab-org/gitlab-ee/tree/8-14-stable-ee/doc/pages which hosted both user and admin docs.
- in 8.17 I moved it under https://gitlab.com/gitlab-org/gitlab-ee/blob/8-17-stable-ee/doc/user/project/pages/index.md and https://gitlab.com/gitlab-org/gitlab-ee/blob/8-17-stable-ee/doc/administration/pages/index.md for user and admin docs respectively.
- Also in 8.17, we introduced new info on pages https://gitlab.com/gitlab-org/gitlab-ce/tree/71fbbc9da428268411c5a3cef319f7537b63d199/doc/pages, BUT this was not picked into stable due to last minute merge (my fault) and now
/help
has different content https://gitlab.com/help/pages/README than what we have in the docs portal https://docs.gitlab.com/ce/pages/.
So, right now we're in a position where we have two places where Pages docs are stored, doc/pages/
, and user/project/pages/
.
There is also an issue where we needed to remove README.md
because of a redirect loop, and this broke the inline links inside GitLab https://gitlab.com/gitlab-org/gitlab-ce/issues/28714.
This would all have been prevented, had we placed the new docs under user/project/pages/
. We need to fix this ASAP.
Proposal
We need to move all docs in one location while still early and include the fix in the patch release. According to https://docs.gitlab.com/ce/development/doc_styleguide.html#location-and-naming-of-documents, the single source of truth should be user/project/pages/
.
TODO list
-
Bring back doc/pages/README.md
which redirects to the correct location. -
Copy doc/user/project/pages/index.md
todoc/user/project/pages/introduction.md
-
Move doc/pages/index.md
todoc/user/project/pages/index.md
-
Copy doc/pages/getting_started_part_one.md
todoc/user/project/pages/getting_started_part_one.md
-
Copy doc/pages/getting_started_part_two.md
todoc/user/project/pages/getting_started_part_two.md
-
Copy doc/pages/getting_started_part_three.md
todoc/user/project/pages/getting_started_part_three.md
-
Check internal links
This would lead to:
- Visiting https://docs.gitlab.com/ce/pages/README.html or https://docs.gitlab.com/ce/pages/index.html should redirect you to https://docs.gitlab.com/ce/user/project/pages/index.html
- Visiting https://docs.gitlab.com/ce/pages/getting_started_part_one.html should redirect to https://docs.gitlab.com/ce/user/project/pages/getting_started_part_one.html
- Visiting https://docs.gitlab.com/ce/pages/getting_started_part_two.html should redirect to https://docs.gitlab.com/ce/user/project/pages/getting_started_part_two.html
- Visiting https://docs.gitlab.com/ce/pages/getting_started_part_three.html should redirect to https://docs.gitlab.com/ce/user/project/pages/getting_started_part_three.html
- The new user docs will be under https://docs.gitlab.com/ce/user/project/pages/introduction.html