Can I render HTML on GitLab?

Question

GitLab doesn't render HTML for me, but just display the source code:

Background: I used sphinx to generate the HTML and tried to show the doc at GitLab.

I looked at other projects' repositories, such as pandas, sphinx. They only have .rts files in the repository, and not HTML files. I guess they generate HTML for their websites but don't upload to Git.

I don't have a website and want to show doc at GitLab. Is there a way to do that? Or do I have to generate other formats (other than HTML, e.g. PDF) instead?

Thanks @Dónal. Looks like there is something for markdown https://github.com/sphinx-doc/sphinx/issues/4219. I'm looking into it — YJZ, Apr 09 '19 at 14:49

score 14 · Accepted Answer · edited Jun 20 '20 at 09:12

First of all, Git and products like GitLab and GitHub are different things. Git doesn't ever render anything; it's a version control system. It doesn't have a web interface.

Secondly, GitLab's core product isn't supposed to render anything. It's not a web host, it's a tool for hosting, sharing, and managing Git repositories. However you might want to try GitLab Pages:

GitLab Pages is a feature that allows you to publish static websites directly from a repository in GitLab.

You can use it either for personal or business websites, such as portfolios, documentation, manifestos, and business presentations. You can also attribute any license to your content.

Pages is available for free for all GitLab.com users as well as for self-managed instances (GitLab Core, Starter, Premium, and Ultimate).

GitLab Pages will publish content from the public/ directory of your repository, so you should move your files there. You will also need a .gitlab-ci.yml file in the root of your repository containing something like

image: alpine:latest

pages:
  stage: deploy
  script:
  - echo 'Nothing to do...'
  artifacts:
    paths:
    - public
  only:
  - master

(taken from the sample repository). Add that file, then commit and push. After deployment is complete, your site should be available at https://youruser.gitlab.io/yourproject.

Note that GitHub has a similar product (that works differently).

Finally,

I looked at other projects' repositories, such as pandas, sphinx. They only have .rts files in the repository, and not HTML files. I guess they generate HTML for their websites but don't upload to Git.

it's very likely that the reStructured Text files are the only source that exists, and that HTML is generated from them automatically. Sphinx this format by default. If you're interested in working from another format like Markdown or reStructured Text you may want to explore GitLab Pages' support for static site generators.

score 2 · Answer 2 · answered Nov 07 '19 at 09:31

There is a super easy solution I found on this post:

Before:
https://gitlab.com/[user]/[repository]/raw/[branch]/[filename.ext]

After:
Development (throttled)
https://gl.githack.com/[user]/[repository]/raw/[branch]/[filename.ext]

Production (CDN)
https://glcdn.githack.com/[user]/[repository]/raw/[branch]/[filename.ext]

score 2 · Answer 3 · answered Sep 02 '22 at 02:49

Another solution:

At the root of your repo, add a file called .gitlab-ci.yml containing the following lines:

pages:
 script:
 - mkdir .public
 - cp -r * .public
 - mv .public public
 artifacts:
    paths:
    - public

Your file should then be available at

 https://your-username.gitlab.io/project-name/filename.html

See this post for details: Gitlab: host and render HTML files

Can I render HTML on GitLab?

3 Answers3