README.md 4.16 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
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

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

You need `docker`:

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

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.

## 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.

## Editing CSS (Sass SCSS)

1. Install `npm`
2. Run `npm run build-css` to rebuild `assets/style.css` from `assets/scss`
3. Make sure you commit it, the CI does NOT rebuild the CSS.
brianmaierjr's avatar
brianmaierjr committed
128
129
130
131
132

## Site Settings

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

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

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

## License (theme)
146

147
148
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.