Student guide

You write your thesis in Markdown. You upload the files by SFTP. The site shows your thesis at once, on screen and as an A4 print preview.

1. Connect

Setting	Value
Protocol	SFTP
Server	`thesis.vk.head-ge.ch`
Port	`2222`
Username	your HES-SO login (`firstname.lastname`)
Password	sent by email

Clients: Cyberduck or FileZilla. You land in your www folder. Everything you put there is online at https://thesis.vk.head-ge.ch/students/<username>/.

Your disk quota is 1 GB. Ask if you need more.

2. Folder structure

www/
├── thesis.yml        title, author, chapter order (see below)
├── text/             one Markdown file per chapter
├── images/           your images (served as-is, keep print resolution)
├── fonts/            your font files (optional)
└── css/
    ├── screen.css    your own look on screen (optional)
    └── print.css     your own look in print (optional)

You need only text/. Without your own css/ files, the default theme styles your thesis (see section 5). The example thesis shows every feature: https://thesis.vk.head-ge.ch/students/example/. You can download all its files as one .zip: see Example files at the end of the guide page.

Two addresses exist for your thesis:

…/students/<username>/ — reading version
…/students/<username>/?print — A4 print preview (Paged.js). …/students/<username>/print/ redirects there.

The page reloads by itself when you upload a file. If thesis.yml has an error, the page shows the error and the line number.

3. thesis.yml

title: My Thesis Title           # inline HTML allowed (&nbsp;, <wbr>)
title_lines:                     # one cover line per entry (optional, default: title)
  - My Thesis
  - Title
subtitle: A subtitle
description: One sentence for search engines and social previews.
lang: en
author:
  name: Jane Doe
  link: https://janedoe.example
  thesis: MA Thesis              # label before the name on the cover
tutor:
  name: Tutor Name
  link: https://tutor.example
school:                          # optional, default HEAD – Genève
  name: HEAD – Genève
  link: https://www.hesge.ch/head/
diploma: Master Visual Knowledge
year: 2026
www: thesis.vk.head-ge.ch/students/jane.doe   # "Read the thesis online" address on the cover
cover: images/cover.jpg          # share image (optional)
pdf: my-thesis.pdf               # uploaded PDF (optional)

quicklinks:                      # header links (optional; default: read online, print)
  - { label: Read online, href: "#nav" }
  - { label: Download as A4, href: my-thesis.pdf }
  - { label: Edit, href: https://example.org, target: _blank }

iframes: [example.org]           # extra iframe hosts; YouTube and Vimeo are always allowed

paged: "0.2"                     # print engine: "0.2" (default, the reference's) or "0.4" (Paged.js 0.4.3)

css:                             # stylesheets per mode, in load order (defaults shown)
  screen: [css/screen.css]
  print:
    - css/screen.css
    - /thesis/paged-0.2/pagedjs.css
    - { href: css/print.css, media: print }

parts:
  - title: Introduction
    file: text/1.intro.md
  - title: Chapter one
    file: text/2.chapter.md
  - title: References
    file: text/9.references.md
    template: references       # default | references | appendices | thanks | any lowercase name

Rules:

Paths are relative to www/. No ...
Without parts:, every text/*.md file is a chapter, in file-name order. The chapter title is the first # Heading of the file.
Without thesis.yml, the username is the title.
template: becomes the class of the chapter’s <section>. Your CSS styles it (section.references { … }). Chapters with a template other than default get an empty running title.
With paged: "0.2", the preview applies the @media screen rules of your CSS for the current window width. Print from the window width you designed for.
paged: "0.4" uses Paged.js 0.4.3. It ignores @media screen rules in the preview, so the preview does not depend on the window width. Page breaks can differ from "0.2".
The css.print list goes to Paged.js. Keep /thesis/paged-0.2/pagedjs.css in it: it styles the preview.
The name print is reserved. Do not create a folder called print.

4. Markdown

Standard Markdown plus:

Footnotes

Text with a note.[^key]

[^key]: The note text. Links and *emphasis* work.

On screen the note appears in the margin. In print it goes to the bottom of the page.

Figures

(figure: images/photo.jpg caption: The *caption*, 2024 class: full)

class: full — full width, into the wide margin in print.
class: notwhite — grey background for images with a white background.
print: full — full width in print only.

Margin notes with an image

Text about Tim Berners-Lee(imagenote: images/tim.jpg caption: Tim Berners-Lee, 1989) continues.

Write the shortcode directly after the word it annotates. In print, the note goes into the wide margin of the page. If a page has too many notes, the browser console shows A marginal note overflow on page N. Move a note or add <br class="breakpage"> before it.

Video

(video: https://www.youtube.com/watch?v=ID poster: images/poster.jpg caption: The film)

YouTube and Vimeo only. Print shows the poster image and the URL.

Columns, glossary, definitions

::: columns
Text in columns (references, for example).
:::

¶¶¶ glossary
::: term
Term
:   Definition of the term.
:::
¶¶¶

Page breaks and print-only content

<br class="breakpage">
<span class="breakprint">shown in print only</span>
<span class="breakscreen">shown on screen only</span>

Links and typography

Bare addresses become links (https://example.org, www.example.org, Are.na). Typography is corrected in the text: ... becomes …, -- becomes —, straight quotes become curly quotes, and French punctuation (: ; ! ? « ») gets its non-breaking spaces.

Not supported

^superscript^, ~subscript~, ==mark== and *[ABBR]: definition are not Markdown here. Write <sup>, <sub>, <mark> and <abbr title="…"> in HTML.

HTML

You can write HTML in Markdown. Scripts and event handlers are removed. Iframes are allowed for YouTube, Vimeo and the hosts in iframes:.

5. CSS

Without your own stylesheets, the site uses the default theme: the css/screen.css and css/print.css of the example thesis. Your thesis has this look as soon as you upload Markdown.

To change the look, put your own file in css/. The site then uses your file and not the default one. This works for each file separately:

css/screen.css — the reading version. The print preview loads it too, before print.css.
css/print.css — loaded with media="print". Paged.js reads it with an old CSS parser: no CSS nesting, no @layer, no @media (width >= …). Use @media (min-width: …) if you need media queries.

Your file replaces the default file completely. Start from a copy of the default one, then change it:

Download the example files (Example files at the end of the guide page) and unzip them.
Take css/screen.css, css/print.css and the fonts/ folder from the example. The stylesheets load the fonts from ../fonts/.
Change the files, then upload them into your css/ and fonts/ folders.

The print mechanics (page size, margins, running heads, footnotes, margin notes, chapter templates) are @page rules and classes in print.css. Keep them when you change the file.

Fonts: put the files in fonts/ and declare them in both CSS files:

@font-face {
  font-family: "MyFont";
  src: url(../fonts/MyFont.woff2) format("woff2");
}

To change the page format or margins, redeclare the pages in print.css:

@page :right { margin: 2cm 1.5cm 2cm 6cm; }
@page :left  { margin: 2cm 6cm 2cm 1.5cm; }

The wide margin holds the margin notes. Keep it on the gutter side.

6. Print to PDF

Open …/students/<username>/?print in Chrome.
Wait until the preview is complete. The console shows Paged.js: N pages.
File → Print. Destination: Save as PDF. Paper: A4. Margins: None. Options: check “Background graphics”, uncheck “Headers and footers”.
Save. The file name is the thesis title.

If the preview stays empty, print.css has a syntax that Paged.js cannot read. Fix the file and reload. The browser console shows the error.