MEDLab Hugo Base Theme

This is the base theme for MedLab Hugo projects. This theme provides a starting point for creating websites using Hugo, a powerful static site generator.

Table of Contents

• Getting Started
• Development
• Content Management
• GitLab CI/CD

Getting Started

Development

1. Install Hugo: Follow the instructions on the Hugo website to install Hugo on your machine.
2. Clone the repository: Clone this repository to your local machine using Git.
3. Navigate to the project directory: Open a terminal and navigate to the directory where you cloned the repository.
4. Start the Hugo server: Run the following command to start the Hugo server:

   hugo server
   

5. Open your web browser: Open your web browser and go to http://localhost:1313 to view the website.

Content Management

1. Add content: Create new Markdown files in the content directory to add content to your website. You can create subdirectories to organize your content.
2. Front matter: Each Markdown file should have front matter at the top of the file. The front matter is a YAML block that contains metadata about the page, such as the title, date, and layout. Here is an example of front matter:

   ---
   title: "My Page Title"
   date: 2023-10-01
   layout: "single"
   ---
   

3. Markdown syntax: Use Markdown syntax to format your content. You can use headings, lists, links, images, and other Markdown features to create your content. For more information on Markdown syntax, see the Markdown documentation.

GitLab CI/CD

This project includes automated CI/CD pipelines that handle building and deploying your Hugo site. The pipeline automatically builds your site when changes are pushed to the publish branch and deploys it to a Surfer instance.

Pipeline Overview

• Build Stage: Compiles Hugo site with optimizations
• Deploy Stage: Deploys to Surfer using cloudron-surfer

Setting up the pipeline

We will use Gitea (git.medlab.host) as the external repository and GitLab for CI/CD. You will need the following:

• A GitLab account
• A Gitea repository (Also works with most other Git hosting service)
• A Surfer instance along with the access token

1. Create GitLab Project

   • For external repositories (like git.medlab.host):
     • Use GitLab's "Run CI/CD for external repo" option
     • This creates a mirrored GitLab project

2. Configure Gitea Repository Mirroring

   • From your Gitea repo go to: Settings > Repository > Mirror Settings
   • Add your GitLab repository URL
   • Add GitLab user credentials under Authorization
   • Check "Sync when commits are pushed" and disable Mirror Interval

3. Set Required Variables on GitLab

   • Get an access token from the Surfer server by going to /_admin and getting the "Access Tokens" dialog from the three-dot menu
   • From your GitLab repo go to: Settings > CI/CD > Variables
   • Add a variable:
     • SURFER_TOKEN (key): Your Surfer access token (value)
       • Mark as "Masked and hidden"
       • Uncheck "Protect variable"
   • In the .gitlab-ci.yml file, set the following variable:
     • SURFER_SERVER: Your Surfer server URL
       • Example: "https://www.example.com/"
       • If you don't want to be visible to the public you can set this variable in GitLab CI/CD settings as well.

4. Deployment Process

   • Push changes to the publish branch to trigger deployment
   • Pipeline will:
     1. Build Hugo site (with minification)
     2. Deploy to Surfer
   • Monitor progress in GitLab's CI/CD Pipeline view

Important Notes

• Ensure .gitlab-ci.yml exists in your repository root
• The pipeline uses hugomods/hugo:node for Hugo Extended support
• Deployments only trigger on the publish branch

For more details about Surfer deployment, see: https://docs.cloudron.io/apps/surfer/