Update README with instructions on how to use

parent 72c99e68
Pipeline #16 passed with stage
in 1 minute and 13 seconds
Theme based on [Long Haul](https://github.com/brianmaierjr/long-haul)
## Development
## Writing new posts
1. Install `npm` and Ruby `bundler`
2. Install development dependencies: `./setup_dev.sh`
3. Run development server: `./run_dev.sh`
New posts should be placed under `_posts`. Directory structure is ignored, posts may
be grouped by year if it's desired.
## Building
### Post markup language
1. Ensure Sass files have been built properly: `npm run build-css`
1. Build Jekyll: `bundle exec jekyll build`
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`
## 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.
## Site Settings
......@@ -18,11 +130,16 @@ The main settings can be found inside the `_config.yml` file:
- **title:** title of your site
- **description:** description of your site
- **url:** your url
- **paginate:** the amount of posts displayed on homepage
- **baseurl:** base site path after the domain name
- **paginate:** the amount of posts displayed on events page
- **navigation:** these are the links in the main site navigation
- **social** diverse social media usernames (optional)
- **google_analytics** Google Analytics key (optional)
## License
Note that `baseurl` should always be blank: the CI will automatically replace
it with an appropriate value when building for GitLab Pages.
## License (theme)
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.
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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment