Use Nanoc Environments to build a custom embedded version of the Docs site

This has been floating around in my head for a while, I'm not 100% sure how we should do it or if it's even possible, but I'd like to try it. Apologies for the mind barf that follows.

There are a number of drawbacks to removing the Help section from the self-hosted instance entirely. Notably: firewalls, ease of access, possible downtime for docs.gitlab.com, etc. This is a potential alternative without those drawbacks, and without the drawbacks of the Rails-app-rendered Help section.

Essentially the goal would be to ship this Nanoc site inside the GitLab CE/EE Rails application. Currently we have the Rails app dynamically render the Markdown inside the doc folder, which is bad for a number of reasons. Environments can be (ab)used to modify the site's layout and other functions depending on the environment in which the site is being compiled. In theory we could have the docs site be generated with modifications so it can be embedded in the Rails app itself.

This has some engineering difficulties associated with it. How do we package this with the Rails app? The Help section works because the Rails app parses the Markdown on-demand. This would require packaging the static site with the Rails app which would require either including the code for this site in the main GitLab repository or... something else? With Omnibus we could compile the Nanoc site ourselves for inclusion in the Rails app. Unfortunately, this wouldn't work for source installs. In theory we could just have source installs link to docs.gitlab.com and Omnibus installs would include it, but that assumes that all our big customers would be using Omnibus (are they?), and would also leave source install users in the dust. We could possibly host the site as a vanilla Rack app alongside the main Rails app and just direct /help/ to it, that's how the Sidekiq Web UI works right now.

TL;DR: Unfortunately removing the Help section entirely has some significant drawbacks. I'd like to figure out a way to create a custom-built package of the Nanoc site to be included in the self-hosted GitLab application. This would be nearly identical to the Docs site on docs.gitlab.com, but without the extra sections or versions, while using all the same rendering so we don't have to maintain two entirely separate means of rendering the documentation (as we do now).

Thoughts?

One other problem is relative URLs, the site has to be hosted at /help/ relative to the instance to ensure compatibility in every situation. However, when I've tried messing with Nanoc at a relative URL everything pretty much broke. I wonder if the root_url in the config needs to be defined as instance.gitlab.com/help/, for example?

Hmm, my random thoughts (might reconsider later).

• We have links pointing to /help in various places in GitLab itself that makes it hard to remove the docs from it.
• It might make more sense to ship nanoc's public/ dir with GitLab and serve with NGINX say under help.example.com. That introduces drawbacks like:
  1. How would the internal Rails links would work since they point to /help (might be easy to solve with a wrapper link).
  2. There would be two help pages help.example.com and example.com/help
  3. We would ship the information twice actually since all source docs would still be under doc/ and the rendered ones in nanoc's public/.
  4. Using GitLab with a relative URL...
• Our main issue is how /help looks like because we cannot use yaml frontmatter or other fancy things nanoc and kramdown provide (things like https://about.gitlab.com/handbook/marketing/developer-relations/technical-writing/markdown-guide/#classes-ids-and-attributes). We care about the content as well as the layout. But what if we didn't? Does it really matter if users see the frontmatter at the top of a page?
• Would our lives be much easier if we finally switched to kramdown? https://gitlab.com/gitlab-org/gitlab-ce/issues/18552

---

We have to consider some things here. We ship every month, that's... fast. How many versions are we gonna support in the docs portal? What if we had another domain, say archive.docs.gitlab.com which will hold all versions lower than the last 2? We'd only have to update it once a month whenever a new release comes out. The main docs.gitlab.com portal will host master, current stable, current stable-1.

As for the drawbacks claim "firewalls, ease of access, possible downtime for docs.gitlab.com":

1. firewalls - That's debatable. Users would still be able to download the source code or even the artifacts of the site and build it themselves, like they already do with GitLab. But that's kind of a dick move to transfer the burden to them. On the other hand, it keeps up back from delivering an awesome portal.
2. ease of access - That's true that having the docs embedded in GitLab makes it easier to browse but there are limitations like search, slowness, etc.
3. downtime for docs.gitlab.com - I can't argue with that We will still have the main repo and the mirror to GitHub, but that's not an counter argument

added backstage label