# 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](#getting-started)
- [Development](#development)
- [Content Management](#content-management)
- [GitLab CI/CD](#gitlab-cicd)

## Getting Started

## Development

1. Install Hugo: Follow the instructions on the [Hugo website](https://gohugo.io/getting-started/installing/) 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:
   ```bash
   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:
   ```yaml
   ---
   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](https://www.markdownguide.org/basic-syntax/).

## 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 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
   - Enable push mirroring

3. **Set Required Variables on GitLab**
   - From your GitLab repo go to: `Settings > CI/CD > Variables`
   - Add these variables:
     - `SURFER_TOKEN`: Your Surfer access token
       - Mark as "Masked and hidden"
   - 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/