README.md 3.31 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
In order for the slides to work (ie. display anything) you need to run:
Roberto Bochet's avatar
Roberto Bochet committed
27
`git submodule update --init`
JackV's avatar
JackV committed
28

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

You can add `--depth 1` to the previous commands to improve the update speed but only if you are using the latest `reveal.js` module.
JackV's avatar
JackV committed
33

JackV's avatar
JackV committed
34 35 36 37
## How do I use this thing?

### Where do I write my stuff?

Davide Depau's avatar
Davide Depau committed
38 39 40 41
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
42 43
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
44 45 46

### How do I write my stuff?

Davide Depau's avatar
Davide Depau committed
47
Using Vim.
JackV's avatar
JackV committed
48

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

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

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

Davide Depau's avatar
Davide Depau committed
58
### How do I see my stuff?
JackV's avatar
JackV committed
59

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

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

64
Click on the printer symbol in the bottom-left corner to get the printable version of the slides.
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`.