initial template

README.md

@@ -0,0 +1,80 @@
+# 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
+
+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 Repository Mirroring** (for external hosting)
+   - Navigate to: `Settings > Repository > Mirror Settings`
+   - Add your GitLab repository URL
+   - Enable push mirroring
+
+3. **Set Required Variables**
+   - 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
+- Build artifacts are retained for 1 hour
+
+For more details about Surfer deployment, see: https://docs.cloudron.io/apps/surfer/