GitLab Pages

Overview link

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.

Prerequisites link

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

Procedure link

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.

   info

   Refer to the quickstart guide if you wish install the Lotus Docs theme in a manner other than Hugo Modules (below).

   
        baseURL = 'https://colinwilson.gitlab.io'
       languageCode = 'en-us'
       title = 'My New Hugo Site'
   
       [module]
           [[module.imports]]
               path = "github.com/colinwilson/lotusdocs"
               disable = false
           [[module.imports]]
               path = "github.com/gohugoio/hugo-mod-bootstrap-scss/v5"
               disable = false
   
       [markup.goldmark.renderer]
           unsafe = true
   
       [[menu.primary]]
           name  = "Docs"
           url = "/docs/"
           identifier = "docs"
           weight = 10
   
       

   
       baseURL: 'https://colinwilson.gitlab.io'
       languageCode: en-us
       title: My New Hugo Site
       module:
         imports:
           - path: github.com/colinwilson/lotusdocs
             disable: false
           - path: github.com/gohugoio/hugo-mod-bootstrap-scss/v5
             disable: false
       markup:
         goldmark:
           renderer:
             unsafe: true
       menu:
         primary:
           - name: Docs
             url: /docs/
             identifier: docs
             weight: 10
   
       

   
       {
         "baseURL": "https://colinwilson.gitlab.io",
         "languageCode": "en-us",
         "title": "My New Hugo Site",
         "module": {
           "imports": [
             {
               "path": "github.com/colinwilson/lotusdocs",
               "disable": false
             },
             {
               "path": "github.com/gohugoio/hugo-mod-bootstrap-scss/v5",
               "disable": false
             }
           ]
         },
         "markup": {
           "goldmark": {
             "renderer": {
               "unsafe": true
             }
           }
         },
         "menu": {
           "primary": [
             {
               "name": "Docs",
               "url": "/docs/",
               "identifier": "docs",
               "weight": 10
             }
           ]
         }
       }
   
       

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.

     /.gitlab-ci.aml
     

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

     image: registry.gitlab.com/pages/hugo/hugo_extended:0.118.2
   
   variables:
     HUGO_ENV: production
   
   default:
     tags:
       - docker
       - linux
     before_script:
       - 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
   
   test:
     tags:
       - docker
       - linux
     script:
       - hugo
     rules:
       - if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH
   
   pages:
     tags:
       - docker
       - linux
     script:
       - hugo
     artifacts:
       paths:
         - public
     rules:
       - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
     

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.

     /public
   /assets/jsconfig.json
   resources/_gen/
   .hugo_build.lock
     

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

     colinwilson.gitlab.io/
     ├── 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.

    

12. 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