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.