README.md 4.03 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

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

You need `docker`:

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

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.

Roberto Bochet's avatar
Roberto Bochet committed
104 105
**Note:** you have to init submodule

106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124
## 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
125 126 127 128
## Site Settings

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

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

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

## License (theme)
142

143 144
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.