Building a GitLab Docs site

How to Use GitLab
1

Hi!

My team wants to create a website using GitLab to host our documentation. They want a landing page with subjects in alphabetical order that users can click on, which will take them to other HTML pages on each topic. The website needs to be accessible only to our team members (who have GitLab accounts and are in one group).

I have already converted many pages to HTML using asciidoctor (from an adoc file).

I came across this tutorial: Building a new GitLab Docs site with Nanoc, GitLab CI, and GitLab Pages | GitLab

Can this tutorial work for my project, or is there a better or easier tutorial that can achieve what I want?

Thank you for any tips on how to start this project!

2

Hello! :wave:

It’s great that you’re looking to use GitLab to host your team’s documentation. I’m here to help you get started on this project. Based on your requirements, the tutorial you mentioned could work for you, but with a few modifications. I’ll outline the steps and provide additional resources where needed.

  1. Creating a repository for your documentation website: First, create a new repository for your documentation website within the GitLab group your team members belong to. This ensures that only team members with access to the group can view and contribute to the repository. Here’s a guide on how to create a new project in GitLab.
  2. Setting up Nanoc: Follow the tutorial Building a new GitLab Docs site with Nanoc, GitLab CI, and GitLab Pages to set up Nanoc in your project. This will help you create a static site for your documentation.
  3. Organizing your content: To display your documentation subjects in alphabetical order on the landing page, you can modify the layouts/default.html file in your Nanoc project. Use the sorted_articles helper to sort the articles alphabetically. Here’s a snippet of how to do this:
    `<% sorted_articles = @items.select { |i| i[:kind] == 'article' }.sort_by { |i| i[:title] } %>
    <ul>
      <% sorted_articles.each do |a| %>
        <li><a href="<%= a.path %>"><%= a[:title] %></a></li>
      <% end %>
    </ul>`
  1. Converting your Asciidoctor files: Since you’ve already converted many pages to HTML using Asciidoctor, you can simply include these HTML files in the content directory of your Nanoc project. You may need to adjust the frontmatter and layout to match your project’s structure.
  2. Restricting access to your website: By default, GitLab Pages websites are publicly accessible. To restrict access to your team members, you can enable GitLab Pages Access Control. This will require users to sign in with their GitLab accounts before they can access the website.

Once you’ve completed these steps, you should have a documentation website hosted on GitLab Pages that’s accessible only to your team members.

If you’re not committed to using nanoc for this project, you can use literally any static site generator to host HTML content with GitLab pages. See here for some examples: GitLab Pages examples · GitLab

If you need any further assistance, feel free to ask. Good luck with your project! :rocket:

1 Like
3

Thank you so much for your answer! I will try that!

1 Like