Proposal: Deploy GitLab Docs to localhost with GitLab CE and EE
Description
Goal
We need a website more customizable for GitLab Documentation, supporting frontmatter, custom styling, kramdown as markdown engine.
Problems
After going back and forth with different proposals to be able to do it, we struggle with:
- Removing
/help=> we achieve the goal, but create another problem: versioning docs. (https://gitlab.com/gitlab-org/gitlab-ce/issues/18739) - Adopt kramdown for docs => sounds weird having 2 different markdown engines in the same application (in case we maintain
/help) - Adopt kramdown entirely => it would be a problem to change the markdown engine for GitLab (https://gitlab.com/gitlab-org/gitlab-ce/issues/18552)
Solution (proposal)
The simplest proposal is to create a way to deploy docs.gitlab.com (an SSG) to localhost as part of the GitLab installation. It would solve all the urgent needs for docs. EE and CE would deploy their doc site from its individual documentation. It can even leave under /help, as long as instead of displaying plain markdown, it would display an SSG site as docs.gitlab.com.
A broader proposal would be creating this not only for our docs, but as a premium feature of GitLab Pages and/or Review Apps.
Future interations (broader proposal)
- Deploy Review Apps to localhost
- Create some sort of browser embed in GitLab (as Twitter and Facebook do): Review Apps embed in GitLab
- Create a way to deploy websites created with Pages to localhost (use case: company's documentation and guidelines)
Documentation blurb
To be added we if decide to make this proposal a feature instead of only solving our documentation issue.
Feature checklist
Make sure these are completed before closing the issue, with a link to the relevant commit.
- Feature assurance
- Documentation
- Added to features.yml
Activity
mentioned in issue #32514 (moved)
As said, I think this is too much work. If we're not just relying on online documentation, I'd say we should do https://gitlab.com/gitlab-org/gitlab-ce/issues/32514
