# Publi

A CLI utility to turn markdown files into webpages or printable document.

## Rationale

A lightweight alternative to existing presentation software (e.g. Powerpoint slideshow, Beamer presentation, or Pandoc converter).

It favors drafting ideas in Markdown, presenting and interacting with them in a browser, publishing them as a printable document.

The challenge that presentation materials always face is that, to be effectively presented, their content needs to be sparse, and to be effectively distributed, their content needs to be plentiful. Publi is an attempt to address that challenge.

## Installation

Right now, you can only install Publi by building it from source.

Below is how you would install it on Unix-like systems. [Go](https://go.dev) is required and the version `1.23.0` is recommended.

```sh
git clone https://gitlab.com/periode/publi
cd publi
go install .
```

Styles, scripts and templates are embedded in the binary and require no separate installation step. You can use the base files as a starting point. They are located in [internal/assets](./internal/assets) and [internal/templates](./internal/templates).

To customise them, copy the reference config and point it at your own files:

```sh
mkdir -p ~/.publi
cp ./assets/config.yaml ~/.publi/config.yaml
# edit ~/.publi/config.yaml to override individual asset paths
```

## Usage

Publi can either `render` a single HTML file or `bind` multiple related HTML files.

To render a single file:

```bash
publi render [source.md] -o [destination_folder] -c [config]
```

To bind multiple files into a collection:

```bash
publi bind [_index.md]
publi bind [_index.md] --mode combined
```

## Output formats

Publi supports different kinds of output formats. It can generate single files or whole collections, and lay them out for web view or for print view.

### Separated / combined

There are two different output modes for `bind`: `separated` (default) and `combined`.

The `separated` mode generates one HTML file per section plus an index page with links to each. It is aimed at presenting a document in a web browser, and focuses on large fonts, lots of white space and hidden notes.

The `combined` mode generates a single HTML file containing all files in order, with a global table of contents and per-section appendices.

### Web / print

By default, all publi files generate web-ready HTML.

To generate a PDF, open the rendered document in a browser, click the `print` button on the bottom left to automatically layout the document using [pagedJS](https://pagedjs.org/), and then `CMD/CTRL+P` to save it as PDF.

## Web features

The web view includes a few interactions, accessible through the buttons in the bottom left corner:

1. __print__ lays out the document to be saved as a PDF (see [Output formats](#output-formats))
2. __board__ toggles a textarea overlay on which you can write plaintext
3. __notes__ toggles the display of presenter notes
4. __screen__ toggles fullscreen view

## Writing Markdown

`publi` relies on generic Markdown syntax with a few quirks:

- the HTML comments tag `<!-- -->` is used to generate the equivalent of presenter notes, hidden by default on the web version, shown on the print version
- the front matter syntax is used to add metadata
- the horizontal line `---` is used to add vertical spacing equivalent to `100vh` in web CSS, or suggest a `page-break` in print CSS

A template markdown file would look something like that:

```gfm
---
date: '2025-04-07'
slug: 'some-thoughts'
author: 'Louise Michel'
---

# How to change things

Notes from my time in Paris.

<!-- It was the best of times, it was the worst of times-->

---

## How it all started

---

The people were hungry and the elites incompetent.

<!-- So far, nothing new under the sun. -->

---

Ce qui devait arriver arriva.
```

## Configuration

 You can adjust the styles and the scripts used by pointing to your own files in the stylesheet provided at `Config.PrintStylePath`.

## Notes

All icons from [Remix Icon](https://remixicon.com/).
