README.md 4.29 KB
Newer Older
Davide Depau's avatar
Davide Depau committed
1
2
Theme based on [Long Haul](https://github.com/brianmaierjr/long-haul)

3
## Writing new posts
Davide Depau's avatar
Davide Depau committed
4

5
6
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
7

8
### Post markup language
Davide Depau's avatar
Davide Depau committed
9

10
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
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
86
87
88
### Sample post

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

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

92
93
Please read the notes below first!

94
95
96
You need `docker`:

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

100
101
102
103
104
105
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
```

106
107
108
109
110
111
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.

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

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

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

137
- **title:** title of your site
brianmaierjr's avatar
brianmaierjr committed
138
139
- **description:** description of your site
- **url:** your url
140
141
- **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
142
- **navigation:** these are the links in the main site navigation
143
144
- **social** diverse social media usernames (optional)
- **google_analytics** Google Analytics key (optional)
brianmaierjr's avatar
brianmaierjr committed
145

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

## License (theme)
150

151
152
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.