website/readme.md

# VeruA.ch Website

 <a href="https://github.com/gohugoio/hugo/releases/tag/v0.124.1" alt="Contributors">
    <img src="https://img.shields.io/static/v1?label=min-HUGO-version&message=0.121.2&color=f00&logo=hugo" />
  </a>
  <a href="https://go.dev" alt="Contributors">
    <img src="https://img.shields.io/static/v1?label=min-go-version&message=1.20.5&color=f00&logo=go" />
  </a>
    <a href="https://go.dev" alt="Contributors">
    <img src="https://img.shields.io/static/v1?label=min-node-version&message=20&color=f00&logo=npm" />  
  </a>

<h3 >currently under development on:  <a target="_blank" href="https://verua.dev-1.andreashnida.de/" rel="nofollow"> verua.dev-1.andreashnida.de 👀 </a>
</h3>

Development site: <a target="_blank" href="https://preview.verua.info/" rel="nofollow">preview.verua.info</a>  
Production site: <a target="_blank" href="https://verua.info/" rel="nofollow">verua.info</a>

ℹ This site is based on <a href="https://github.com/zeon-studio/hugoplate">Hugoplate Boilerplate Theme for Hugo</a>. For specifics on how to use the theme, please refer to the <a href="https://github.com/zeon-studio/hugoplate/blob/main/README.md">README</a> of the theme.

## Table of Contents

- [Usage / Update Content](#usage--update-content)
  - [Editing Content](#editing-content)
  - [Images](#images)
  - [Shortcodes](#shortcodes)
- [Custom Shortcodes exclusively for VeruA.ch](#custom-shortcodes-exclusively-for-veruach)
  - [Alert](#alert)
  - [Aligncenter](#aligncenter)
  - [Card](#card)
  - [Columns](#columns)
  - [Font-Awesome Icon](#font-awesome-icon)
  - [Section](#section)
  - [formEventDropdown](#formeventdropdown)
- [Deployment](#deployment)
- [Development](#development)

## Usage / Update Content

To use the theme, and to update your content, you need to clone the repository, update your content in the `content` folder and push your changes to the main branch which will trigger a deployment.

```bash
# Clone the repository
git clone https://code.verua.online/rabeweb/verua.ch_src.git

# connect to your gitea instance
cd verua.ch_src
git push -u origin main
```

[⬆](#table-of-contents)

### Editing Content

The content is written in the [markdown](https://www.markdownguide.org/getting-started/) format. You also use html tags to format your content but the ending still stays .md for markdown. These files are found in the `content` folder. For linking german and french content, you use the translation key syntax. This means that you put a key in the frontmatter of both files you want to link to.

```yaml
---
title: "VeruA ** Verwaltung und Abrechnung"
translationKey: "a-page-about-cats"
---
```

For example, the german version of the VeruA.ch website is located in the `content/german` folder. The french version is located in the `content/french` folder. Both are linked by the translation key `a-page-about-cats`.

[⬆](#table-of-contents)

### Images

Images are stored in the `static/images` folder. You can use the `![]()` syntax to insert images into your markdown files.

Everything that is in the `static/images` folder will be copied to the `public/images` folder during the build process. This means that you can use relative paths to your images in your markdown files like this: `![](images/my-image.png)`.

[⬆](#table-of-contents)

### Shortcodes

You can use shortcodes to add custom functionality to your markdown files. You can find a list of available shortcodes in the [Hugoplate documentation](https://github.com/zeon-studio/hugoplate/blob/main/README.md#shortcodes).

There are some shortcodes that are specific to the VeruA.ch website. These Shortcodes are defined in the `layouts/shortcodes` folder. You can find a list of available exclusive shortcodes like columns and sections further down in this document.

[⬆](#table-of-contents)

## Custom Shortcodes exclusively for VeruA.ch

<small>/themes/hugoplate/layouts/shortcodes/</small>

- **Alerts**: Create alerts with custom text and styles.
- **Aligncenter**: Center content horizontally.
- **Cards**: Create beautiful cards with custom content and images.
- **Columns**: Create responsive columns with custom content and images.
- **Icons**: Use icons from the Font Awesome library to add icons to your website.
- **Sections**: Create sections with custom content and images.

[⬆](#table-of-contents)

### Alert

The alert shortcode is used to create alerts with custom text and styles.

**Pfad:** themes/hugoplate/layouts/shortcodes/alert.html

`{{% alert background-color="slate-800" %}}`

Content

`{{% /alert %}}`

[⬆](#table-of-contents)

### Aligncenter

The aligncenter shortcode is used to center content horizontally.

**Pfad:** themes/hugoplate/layouts/shortcodes/aligncenter.html

`{{% aligncenter %}}`

Content

`{{% /aligncenter %}}`

[⬆](#table-of-contents)

### Card

The card shortcode is used to create beautiful cards with custom content and images.

**Pfad:** themes/hugoplate/layouts/shortcodes/card.html

`{{% card %}}`

Content

`{{% /card %}}`

Kann ein `Background` - Attribut haben:

`{{% card background="images/startseite-slide.jpg" %}}`

Kann ein `Light-Text` - Attribut haben:

`{{% card light-text="true" %}}`

Kann ein `Title` - Attribut haben:

`{{% card title="Card Title" %}}`

[⬆](#table-of-contents)

### Columns

**Pfad:** themes/hugoplate/layouts/shortcodes/columns.html

Columns are seperated by the '..column..' shortcode.

`{{% columns %}}`

Content

`..column..`

Content

`..column..`

Content

`{{% /columns %}}`

[⬆](#table-of-contents)

### Font-Awesome Icon

Find all open source icons on [Font Awesome](https://fontawesome.com/search?m=free&o=r)

`{{% icon name="user" color="black" size="5xl" %}}`

Für "size" und "color" werden Tailwind CSS Klassen benutzt.

E.g. https://tailwindcss.com/docs/text-color

die Klassennamen jeweils OHNE "text-" einfügen:
text-gray-50 -> color="gray-50"

text-5xl -> size="5xl"

[⬆](#table-of-contents)

### Section

It is a good idea to use the section shortcode to separate your content into sections and keep consistent margins and page widths.

**Pfad:** themes/hugoplate/layouts/shortcodes/section.html

`{{% section %}}`

Content

`{{% /section %}}`

Kann ein `Background` - Attribut haben:

`{{% section background="images/startseite-slide.jpg" %}}`

[⬆](#table-of-contents)

### formEventDropdown

**Pfad:** themes/hugoplate/layouts/shortcodes/formEventDropdown.html

`{{< formEventDropdown >}}`

Renders a dropdown form field with the available events. You set the events in the `schulungstermine` parameter in the frontmatter of the page.

[⬆](#table-of-contents)

## Deployment

Deployment is done via Gitea Runners. The deployment is triggered by a push to the `main` branch. The deployment will automatically build the site and deploy it to the production or preview environment.

You can control where the site is deployed by setting the 'environment' variable in the `hugo.toml` file. The value should be either `production` or `development`.

This also controls the creation of the robots.txt file. If the value is `development`, the robots.txt file will be created with the following content:

```r
User-agent: *
Disallow: /
```

Credentials and targets are stored as secrets in your Gitea instance.

You can also run the site locally. Please refer to the 'Development' section for more information.

ℹ You will find the workflow file in `/.gitea/workflows/build-and-deploy-pipeline.yaml`

[⬆](#table-of-contents)

## Development

To run the site locally, you can use the following commands:

```bash

# Project setup
npm run project-setup

# Install dependencies
npm install

# Start the development server
npm run dev
```

The site will be available at `http://localhost:8080`.