With GitLab Pages, you can publish your Lotus Docs site directly from a repository in GitLab.

  • Use for any personal or business website.
  • Native support for Hugo.
  • Create websites for your projects, groups, or user account.
  • Host your site on your own GitLab instance or on GitLab.com for free.
  • Connect your custom domains and TLS certificates.
  • Attribute any license to your content.

GitLab makes it easy to build, deploy, and host your Lotus Docs website via their free GitLab Pages service.


  1. A GitLab Account
  2. Git
  3. Create a Hugo site using the Lotus Docs theme


Use the following steps to get your Lotus Docs site up and running on GitLab Pages.

  1. Create a new repo on GitLab e.g. https://gitlab.com/colinwilson/colinwilson.gitlab.io. Select GitLab Pages as the Project deployment target:

  2. Create a new Hugo project using the hugo new command:

      hugo new site colinwilson.gitlab.io && cd colinwilson.gitlab.io

    Initialize your project as a Hugo Module using the hugo mod init command:

      hugo mod init my-docs-site
  3. Update your site’s config file (hugo.toml / hugo.yaml / hugo.json) to include the required theme modules and update your baseURL to your intended GitLab Pages domain e.g. colinwilson.gitlab.io. You can also configure a [[menu.primary]] item. This creates a link on the landing page to the docs/ section.

  4. Create some example content.

       hugo new docs/example-page.md

    Update the front matter draft parameter in the created example-page.md file to false.

    title: "Example Page"
    date: 2023-08-25T23:36:29+01:00
    draft: false
  5. Create an empty .gitlab-ci.yml file at the root of your local repository.

  6. Copy and paste the YAML below into the job file you created.

      image: registry.gitlab.com/pages/hugo/hugo_extended:0.118.2
      HUGO_ENV: production
        - docker
        - linux
        - apk add --no-cache go curl bash nodejs
        # - hugo mod get -u $THEME_URL
        ## Uncomment the following if you use PostCSS. See https://gohugo.io/hugo-pipes/postcss/
        #- npm install postcss postcss-cli autoprefixer
        - docker
        - linux
        - hugo
        - docker
        - linux
        - hugo
          - public
  7. Create a .gitignore file. Copy the contents below into it. This prevents your local /public directory (and other resources) being committed to to your GitLab repository.

  8. Your site structure should now look similar to the one below:

      ├── archetypes/
      ├── assets/
      ├── content/
      │   └── docs/
      │       └── example-page.md
      ├── data/
      ├── i18n/
      ├── layouts/
      ├── static/
      ├── themes/
      ├── .gitignore
      ├── .gitlab-ci.yml
      ├── .hugo_build.lock
      ├── go.mod
      ├── go.sum
      └── hugo.toml
  9. Use git int to initialize your project as a repository, then commit all the changes to your local repository with a commit message of something like “🎉 initial commit”. Push your local repo to the repository you created on GitLab in step 1.

  10. Revisit your repository on GitLab, navigate to Build > Pipelines, and you should see that your Hugo site was successfully built.

    GitLab pipelines screenshot

  1. You should now be able to see your site at the baseURL (e.g. https://colinwilson.gitlab.io) defined in your hugo.toml / hugo.yaml / hugo.json config file

Last updated 02 Oct 2023, 16:33 +0100 . history

Was this page helpful?