README.md 3.12 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 40
1. Create a new repo into the appropriate sub-organization
1. Clone this repo
1. Change origin to your repo
1. Push
1. Edit `content.md` and `index.html`
JackV's avatar
JackV committed
41 42 43

### How do I write my stuff?

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

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

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
51
Use `Notes:` to add reader notes to your slide.
JackV's avatar
JackV committed
52

Davide Depau's avatar
Davide Depau committed
53
### How do I see my stuff?
JackV's avatar
JackV committed
54

Davide Depau's avatar
Davide Depau committed
55 56 57
- You can display `index.html` with your browser
  or
- You can run `deploy.py` with Python 3 and open the provided link in your browser.
JackV's avatar
JackV committed
58

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

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

Davide Depau's avatar
Davide Depau committed
63 64
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
65

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

Davide Depau's avatar
Davide Depau committed
68 69
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
70

Davide Depau's avatar
Davide Depau committed
71 72
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
73

Davide Depau's avatar
Davide Depau committed
74 75
[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
76

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

Davide Depau's avatar
Davide Depau committed
79 80
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
81

Davide Depau's avatar
Davide Depau committed
82 83 84 85
#### 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
86 87


Davide Depau's avatar
Davide Depau committed
88 89
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
90

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

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

Davide Depau's avatar
Davide Depau committed
97 98
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
99

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