README.md 3.27 KB
Newer Older
JackV's avatar
JackV committed
1 2
# POuL reveal.js template

Davide Depau's avatar
Davide Depau committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
This is the `reveal.js` slides template for all POuL lessons.

It is mandatory for new courses to either use this or the Beamer base template.

## Important - Slides versioning

Slides repositories should be placed under the appropriate suborganization, under
[/corsi](https://gitlab.poul.org/corsi).

All years slides should be **in the same repo**, even if they use different
technologies. Use a branch `revealjs`/`beamer` to distinguish the two trees.

All years slides must be tagged appropriately:

```bash
git tag -m 2019 2019
```

If you need to move a tag, add `--force`. You might need to ask a sysadmin if you
need to force-push.
JackV's avatar
JackV committed
23

JackV's avatar
JackV committed
24 25
## Getting Started

Davide Depau's avatar
Davide Depau committed
26 27
In order for the slides to work (ie. display anything) you need to run:
`git submodule update --init --depth 1`
JackV's avatar
JackV committed
28

Davide Depau's avatar
Davide Depau committed
29
In case you need the mathjax submodule as well
JackV's avatar
JackV committed
30 31
`git submodule update --init --depth 1 --recursive`

JackV's avatar
JackV committed
32 33 34 35
## How do I use this thing?

### Where do I write my stuff?

Davide Depau's avatar
Davide Depau committed
36 37 38 39
1. Create a new repo into the appropriate sub-organization
1. Clone this repo
1. Change origin to your repo
1. Push
Roberto Bochet's avatar
Roberto Bochet committed
40 41
1. Add author's info in `./slides/intro.html` and `./slides/outro.html`
1. Put your content in `./slides/content.md` or add slides files in `./slides/` and link these in `./index.html`
JackV's avatar
JackV committed
42 43 44

### How do I write my stuff?

Davide Depau's avatar
Davide Depau committed
45
Using Vim.
JackV's avatar
JackV committed
46

Davide Depau's avatar
Davide Depau committed
47
[Here][markdown-guide] you can find a comprehensive guide to the Markdown syntax.
JackV's avatar
JackV committed
48 49 50 51

Remember to use three dashes (`---`) to create a new slide horizontally and
four dashes (`----`) to create a new one vertically.

Davide Depau's avatar
Davide Depau committed
52
Use `Notes:` to add reader notes to your slide.
JackV's avatar
JackV committed
53

Roberto Bochet's avatar
Roberto Bochet committed
54 55
Alternatively you can write your slides with pure **html**

Davide Depau's avatar
Davide Depau committed
56
### How do I see my stuff?
JackV's avatar
JackV committed
57

Roberto Bochet's avatar
Roberto Bochet committed
58
- You can run `./deploy.py` with Python 3 and open the provided link in your browser.
JackV's avatar
JackV committed
59

Davide Depau's avatar
Davide Depau committed
60
## How do I make a PDF out of the slides?
JackV's avatar
JackV committed
61

Davide Depau's avatar
Davide Depau committed
62
Append `?print-pdf` at the end of the URL.
JackV's avatar
JackV committed
63

Davide Depau's avatar
Davide Depau committed
64 65
For instance if you're running the `deploy.py` script locally the URL will be
something like `http://127.0.0.1:8080/?print-pdf`.
JackV's avatar
JackV committed
66

Davide Depau's avatar
Davide Depau committed
67
Then just use the print function of your browser to make a PDF of the page.
JackV's avatar
JackV committed
68

Davide Depau's avatar
Davide Depau committed
69 70
On **Chrome/ium** make sure you **scroll to the top** of your slides before printing,
otherwise, for whatever reason, the background of the slides will be borked.
JackV's avatar
JackV committed
71

Davide Depau's avatar
Davide Depau committed
72 73
On **Firefox** it is advised to enable *Print Backgrounds* under the *Options* tab,
to select paper size *Choukei 2 Envelope* and *Landscape* orientation.
JackV's avatar
JackV committed
74

Davide Depau's avatar
Davide Depau committed
75 76
[download]: https://gitlab.poul.org/corsi/revealjs-poul/repository/archive.zip?ref=master
[markdown-guide]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
JackV's avatar
JackV committed
77

Davide Depau's avatar
Davide Depau committed
78
## GitLab Pages slides preview
JackV's avatar
JackV committed
79

Davide Depau's avatar
Davide Depau committed
80 81
It is possible to use GitLab Pages to preview the slides in order to send them for review
to the mailing list.
JackV's avatar
JackV committed
82

Davide Depau's avatar
Davide Depau committed
83 84 85 86
#### Important
GitLab Pages **must not** be used to actually publish the slides, and links to it
**must not** be given to course attendants. Use [slides.poul.org](https://slides.poul.org)
instead.
JackV's avatar
JackV committed
87 88


Davide Depau's avatar
Davide Depau committed
89 90
A `.gitlab-ci.yml` config is provided in this template. It simply copies the whole
`master` branch of the repo to the Pages website.
JackV's avatar
JackV committed
91

Davide Depau's avatar
Davide Depau committed
92
To use it:
JackV's avatar
JackV committed
93

Davide Depau's avatar
Davide Depau committed
94 95 96
- Enable CI for your repository:
  - Go to `Settings` > `General` > `Visibility`
  - Enable `Pipelines` under the `Repository` section
JackV's avatar
JackV committed
97

Davide Depau's avatar
Davide Depau committed
98 99
A CI build job for the `master` branch should run automatically. If it doesn't, go to
`CI / CD` and click `Run Pipeline`.
JackV's avatar
JackV committed
100

Davide Depau's avatar
Davide Depau committed
101
You can find the link to your Pages preview under `Settings` > `Pages`.