[![pipeline status](https://gitlab.poul.org/sito/poul-jekyll/badges/master/pipeline.svg)](https://gitlab.poul.org/sito/poul-jekyll/commits/master)

Theme based on [Long Haul](https://github.com/brianmaierjr/long-haul)

## Writing new posts

New posts should be placed under `_posts`. Directory structure is ignored, posts may
be grouped by year if it's desired.

### Post markup language

Any language supported by Jekyll can be used. Markdown and HTML are advised.

### Post file name

Posts must follow the following naming pattern:

`yyyy-mm-dd-slug.md` (or `.html`)

Posts will be available at:

`https://www.poul.org/yyyy/mm/slug/`

### Post metadata

Posts **must** begin with metadata. Metadata will not be kept as-is in the final result
but it will be used for page and website rendering. Metadata is in YAML format.

This is an example:

```yml
---
layout: post
title: Corsi Linux 2019
categories:
- Corsi Linux
- Events
tags:
- Linux
- ansible
- docker
- firewall
- networking
- scalability
- backup
- systemd
- boot
---
```

- **layout:** Post layout, pick one from the `_layouts` directory or add yours. `post` should work fine.
- **title:** It will be displayed in the post list and at the top of the post.
- **categories:** They **must** be consistent. Posts lacking the `Events` category will not show up in the home page under "Latest events". All the other categories of posts that have the `Events` category will show up in the home page under "Past events".
- **tags:** Currently ignored. It should be still filled in, it might be used for further development.

### Internal links/image links

To get an internal link, always use this syntax:

`{{ site.baseurl }}/{% link _posts/2019-05-18-bla-bla.md %}`

This will be rendered to:

`/baseurl/2019/05/bla-bla/`

Always specify the file name when adding links: if for whatever reason permalinks to
an article or page should change, this will automatically update all links.


### WordPress alert boxes

A bunch of alert boxes plugins that were installed in WordPress have been ported to
Jekyll.

For example:

```
{% include alerts/important.html content="Il corso è totalmente gratuito e non necessita di iscrizione"%}
```

These boxes are available:

- `important.html`
- `notice.html`
- `red.html`
- `warning.html`

### Sample post

A sample post is available at `/examples/1970-01-01-sample_post`. View it in the website for a quick demo.

## Local preview (i.e. to see posts before commiting)

Please read the notes below first!

You need `docker`:

```bash
docker run --rm --volume="$PWD:/srv/jekyll" -p 4000:4000 -it jekyll/jekyll jekyll serve --incremental
```

You can also run the container with `podman`:

```bash
podman run --rm --volume="$PWD:/srv/jekyll:z" -p 4000:4000 -e JEKYLL_UID=48 -e JEKYLL_GID=48 -it jekyll/jekyll jekyll serve --incremental
```

Site preview will be available at [localhost:4000](http://localhost:4000).

**Note:** the BITS button may not work when running locally.

**Note:** images from old posts will not display as they're not included in the repository.

**Note:** you have to init submodule (`git submodule update --init`)

## Preview on GitLab Pages

1. Make sure you're working on a fork
2. Enable CI for your fork:
  1. Go to Settings, General, Visibility (sidebar)
  2. Under Repository, enable Pipelines
3. From now on, pushes will trigger a build. To build manually:
  1. Go to CI/CD (sidebar)
  2. Click Run Pipeline
4. Your preview website will be available at the page mentioned in Settings, Pages.

**Note:** the BITS button may not work when run from GitLab Pages.

**Note:** images from old posts will not display as they're not included in the repository.

## Deploy to main website

Simply push to `master` branch in the main repository.

## Site Settings

The main settings can be found inside the `_config.yml` file:

- **title:** title of your site
- **description:** description of your site
- **url:** your url
- **baseurl:** base site path after the domain name
- **paginate:** the amount of posts displayed on events page
- **navigation:** these are the links in the main site navigation
- **social** diverse social media usernames (optional)
- **google_analytics** Google Analytics key (optional)

Note that `baseurl` should always be blank: the CI will automatically replace
it with an appropriate value when building for GitLab Pages.

## License (theme)

This is [MIT](LICENSE) with no added caveats, so feel free to use this Jekyll
theme on your site without linking back to me or using a disclaimer.