README.md 4.44 KB
Newer Older
Roberto Bochet's avatar
Roberto Bochet committed
1 2
[![pipeline status](https://gitlab.poul.org/sito/poul-jekyll/badges/master/pipeline.svg)](https://gitlab.poul.org/sito/poul-jekyll/commits/master)

Davide Depau's avatar
Davide Depau committed
3 4
Theme based on [Long Haul](https://github.com/brianmaierjr/long-haul)

5
## Writing new posts
Davide Depau's avatar
Davide Depau committed
6

7 8
New posts should be placed under `_posts`. Directory structure is ignored, posts may
be grouped by year if it's desired.
Davide Depau's avatar
Davide Depau committed
9

10
### Post markup language
Davide Depau's avatar
Davide Depau committed
11

12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
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`

Davide Depau's avatar
Davide Depau committed
88 89
### Sample post

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

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

94 95
Please read the notes below first!

96 97 98
You need `docker`:

```bash
Roberto Bochet's avatar
Roberto Bochet committed
99
docker run --rm --volume="$PWD:/srv/jekyll" -p 4000:4000 -it jekyll/jekyll jekyll serve --incremental
100 101
```

102 103 104 105 106 107
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
```

108 109 110 111 112 113
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.

114
**Note:** you have to init submodule (`git submodule update --init`)
Roberto Bochet's avatar
Roberto Bochet committed
115

116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
## 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.

brianmaierjr's avatar
brianmaierjr committed
135 136 137 138
## Site Settings

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

139
- **title:** title of your site
brianmaierjr's avatar
brianmaierjr committed
140 141
- **description:** description of your site
- **url:** your url
142 143
- **baseurl:** base site path after the domain name
- **paginate:** the amount of posts displayed on events page
Brian Maier Jr.'s avatar
Brian Maier Jr. committed
144
- **navigation:** these are the links in the main site navigation
145 146
- **social** diverse social media usernames (optional)
- **google_analytics** Google Analytics key (optional)
brianmaierjr's avatar
brianmaierjr committed
147

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

## License (theme)
152

153 154
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.