88 lines
3.9 KiB
Markdown
88 lines
3.9 KiB
Markdown
# 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 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/
|