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

Davide Depau's avatar
Davide Depau committed
45
46
47
48
49
50
51
52
All user-supplied content MUST be placed under the `slides` directory.

This allows to easily merge changes from this template without breaking the
slides.

If you're updating old slides you should resolve all the conflicts yourself and
migrate to the new layout described here.

JackV's avatar
JackV committed
53
54
### How do I write my stuff?

Davide Depau's avatar
Davide Depau committed
55
Using Vim.
JackV's avatar
JackV committed
56

Davide Depau's avatar
Davide Depau committed
57
[Here][markdown-guide] you can find a comprehensive guide to the Markdown syntax.
JackV's avatar
JackV committed
58
59
60
61

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

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

Davide Depau's avatar
Davide Depau committed
66
### How do I see my stuff?
JackV's avatar
JackV committed
67

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

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

72
Click on the printer symbol in the bottom-left corner to get the printable version of the slides.
JackV's avatar
JackV committed
73

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

Davide Depau's avatar
Davide Depau committed
76
77
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
78

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

Davide Depau's avatar
Davide Depau committed
82
83
[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
84

Davide Depau's avatar
Davide Depau committed
85
## GitLab Pages slides preview
JackV's avatar
JackV committed
86

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

Davide Depau's avatar
Davide Depau committed
90
91
92
93
#### 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
94
95


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

Davide Depau's avatar
Davide Depau committed
99
To use it:
JackV's avatar
JackV committed
100

Davide Depau's avatar
Davide Depau committed
101
102
103
- Enable CI for your repository:
  - Go to `Settings` > `General` > `Visibility`
  - Enable `Pipelines` under the `Repository` section
JackV's avatar
JackV committed
104

Davide Depau's avatar
Davide Depau committed
105
106
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
107

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