commit - be287bea29d2b7f0494bc0cfb1b2bb2713a31b98
commit + 97a534a90733f873f1ed2846bc82a2d016797ccb
blob - 1e77dbb163b0cb929af2889796ed5c9a6aa01b2f
blob + 6833fc7c9e81360319e09d86f3f7fb25d676951b
--- README.md
+++ README.md
# Slides
Slides in your terminal — personal fork of [maaslalani/slides](https://github.com/maaslalani/slides)
-with real LaTeX rendering, real images (including animated GIFs) with
-captions, numbered bibliography/citations, and progressive reveal, built
-for academic and scientific presentations.
+with real LaTeX, real images (including animated GIFs), bibliography/citations,
+progressive reveal, and plots from executed code, built for academic and
+scientific presentations.
<p align="center">
<img src="./assets/slides-1.gif?raw=true" alt="Slides Presentation" />
### What's different from upstream
-* **LaTeX math** — `$...$` inline math renders as Unicode text inline with
- the surrounding prose; `$$...$$` block math renders as a real image via
- [tectonic](https://tectonic-typesetting.github.io/) + Ghostscript.
-* **Real images** — `` shows the actual image (not
- just alt text) via the Kitty Graphics Protocol, with the caption
- rendered below it, including animated GIFs playing back for real. Falls
- back to plain alt text on terminals without Kitty graphics support.
+* **LaTeX math** — `$...$` inline math renders as Unicode text; `$$...$$`
+ block math renders as a real image via [tectonic](https://tectonic-typesetting.github.io/) + Ghostscript.
+* **Real images** — `` shows the actual image via the
+ Kitty Graphics Protocol, caption included, animated GIFs playing back
+ for real. Falls back to plain alt text without Kitty graphics support.
* **Bibliography & citations** — `[@key]` citations are numbered by order
- of first appearance and resolved against a `.bib` file, with a
- References slide generated automatically at the end. See
- `bibliography` under [Configuration](#configuration).
+ of first appearance against a `.bib` file, with a References slide
+ generated automatically. Enabled via `bibliography` in the frontmatter.
* **Progressive reveal** — `<!-- pause -->` splits a slide into steps
revealed one keypress at a time.
-* **Plots from executed code** — any image file a `ctrl+e` code block
- saves (a Julia/Python/R plot, ...) is shown below its output; Julia
- specifically gets ANSI-colored UnicodePlots and a headless GR/Plots.jl
- backend for free.
-* Layout/margin/sizing tuned for presenting on a projector (see
- `examples/` for a real worked example — not checked in, but built the
- same way you would build your own).
+* **Plots from executed code** — any image a `ctrl+e` code block saves is
+ shown below its output. Julia specifically gets ANSI-colored
+ UnicodePlots and a headless GR/Plots.jl/CairoMakie backend for free.
+* Layout/margin/sizing tuned for presenting on a projector.
-Everything else — navigation, search, code execution, SSH — works exactly
-like upstream `slides`, documented below.
+Everything else — navigation, search, pre-processing, SSH — works exactly
+like upstream `slides`.
### Installation
go install
```
-Or, with the Nix flake in this repo (also brings in `tectonic` and
-`ghostscript` for LaTeX rendering, and `julia-bin` for the Julia code
-execution extras):
+Or, with the Nix flake in this repo (also brings in `tectonic`,
+`ghostscript`, and `julia-bin`):
```
nix build # ./result/bin/slides
-# or, for a dev shell with go/gopls/tectonic/ghostscript on PATH:
-nix develop
+nix develop # dev shell with everything on PATH
```
### Usage
-Create a simple markdown file that contains your slides:
-````markdown
-# Welcome to Slides
-A terminal based presentation tool
-
----
-
-## Everything is markdown
-In fact, this entire presentation is a markdown file.
-
----
-
-## Everything happens in your terminal
-Create slides and present them without ever leaving your terminal.
-
----
-
-## Code execution
-```go
-package main
-
-import "fmt"
-
-func main() {
- fmt.Println("Execute code directly inside the slides")
-}
```
-
-You can execute code inside your slides by pressing `<C-e>`,
-the output of your command will be displayed at the end of the current slide.
-
----
-
-## Pre-process slides
-
-You can add a code block with three tildes (`~`) and write a command to run *before* displaying
-the slides, the text inside the code block will be passed as `stdin` to the command
-and the code block will be replaced with the `stdout` of the command.
-
-```
-~~~graph-easy --as=boxart
-[ A ] - to -> [ B ]
-~~~
-```
-
-The above will be pre-processed to look like:
-
-┌───┐ to ┌───┐
-│ A │ ────> │ B │
-└───┘ └───┘
-
-For security reasons, you must pass a file that has execution permissions
-for the slides to be pre-processed. You can use `chmod` to add these permissions.
-
-```bash
-chmod +x file.md
-```
-
-````
-
-Checkout the [example slides](./examples).
-
-Then, to present, run:
-```
slides presentation.md
```
-If given a file name, `slides` will automatically look for changes in the file and update the presentation live.
+Space/`j`/`k`/arrows to move between slides, `/` to search, `ctrl+e` to
+run a code block, `y` to yank one, `gg`/`G` to jump to the first/last
+slide. `slides` also reads from `stdin` and reloads live on file changes.
-`slides` also accepts input through `stdin`:
-```
-curl http://example.com/slides.md | slides
-```
+Frontmatter (`theme`, `author`, `date`, `paging`, `bibliography`) is
+optional — see [examples/metadata.md](./examples/metadata.md).
-Go to the first slide with the following key sequence:
-* <kbd>g</kbd> <kbd>g</kbd>
+See [examples/](./examples) for every feature above in a working
+presentation: LaTeX, images, GIFs, bibliography, reveal, Julia plots, and
+everything inherited from upstream.
-Go to the next slide with any of the following key sequences:
-* <kbd>space</kbd>
-* <kbd>right</kbd>
-* <kbd>down</kbd>
-* <kbd>enter</kbd>
-* <kbd>n</kbd>
-* <kbd>j</kbd>
-* <kbd>l</kbd>
-* <kbd>Page Down</kbd>
-* number + any of the above (go forward n slides)
-
-Go to the previous slide with any of the following key sequences:
-* <kbd>left</kbd>
-* <kbd>up</kbd>
-* <kbd>p</kbd>
-* <kbd>h</kbd>
-* <kbd>k</kbd>
-* <kbd>N</kbd>
-* <kbd>Page Up</kbd>
-* number + any of the above (go back n slides)
-
-Go to a specific slide with the following key sequence:
-
-* number + <kbd>G</kbd>
-
-Go to the last slide with the following key:
-
-* <kbd>G</kbd>
-
-### Search
-
-To quickly jump to the right slide, you can use the search function.
-
-Press <kbd>/</kbd>, enter your search term and press <kbd>Enter</kbd>
-(*The search term is interpreted as a regular expression. The `/i` flag causes case-insensitivity.*).
-
-Press <kbd>ctrl+n</kbd> after a search to go to the next search result.
-
-### Code Execution
-
-If slides finds a code block on the current slides it can execute the code block and display the result as virtual text
-on the screen.
-
-Press <kbd>ctrl+e</kbd> on a slide with a code block to execute it and display the result.
-
-Execution runs in the background, so a slow first run (Julia compiling a
-plotting library, for example) doesn't freeze the presentation — a spinner
-shows while it's working. If the code saves an image file (a plot,
-typically), it's shown below the text output, the same way a regular
-image would be.
-
-Julia gets three extras, all automatic, no configuration needed:
-
-* [UnicodePlots.jl](https://github.com/JuliaPlots/UnicodePlots.jl) draws
- straight into the code output, in color, sized to fit the slide.
-* [GR.jl](https://github.com/jheinen/GR.jl) / [Plots.jl](https://docs.juliaplots.org)
- with the GR backend never tries to open a window — `GKSwstype` is set
- for you.
-* [CairoMakie](https://docs.makie.org/stable/) (or anything else that
- just `save()`s a PNG) works out of the box. GLMakie and other
- GPU/window-backed backends aren't supported — there's no display to
- hand them.
-
-### Progressive reveal
-
-Split a slide into steps, revealed one at a time, with an HTML comment on
-its own line:
-
-```
-- always visible
-<!-- pause -->
-- appears on the next keypress
-```
-
-The same keys that page forward/back (space, `j`/`k`, arrows, ...) reveal
-or retract one step first, before moving to the next slide. Jumping
-(`3j`, `5G`, `gg`) always lands on the target slide fully revealed.
-
-### Pre-processing
-
-You can add a code block with three tildes (`~`) and write a command to run
-*before* displaying the slides, the text inside the code block will be passed
-as `stdin` to the command and the code block will be replaced with the `stdout`
-of the command. Wrap the pre-processed block in three backticks to keep
-proper formatting and new lines.
-
-````
-```
-~~~graph-easy --as=boxart
-[ A ] - to -> [ B ]
-~~~
-```
-````
-
-The above will be pre-processed to look like:
-
-```
-┌───┐ to ┌───┐
-│ A │ ────> │ B │
-└───┘ └───┘
-```
-
-For security reasons, you must pass a file that has execution permissions
-for the slides to be pre-processed. You can use `chmod` to add these permissions.
-
-```bash
-chmod +x file.md
-```
-
-### LaTeX math
-
-Write ordinary LaTeX math in your markdown:
-
-```
-Inline: $\alpha^2 + \beta \leq \gamma$, rendered as Unicode text.
-
-Block:
-$$\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}$$
-```
-
-Inline math (`$...$`) is approximated as Unicode text so it flows with
-the surrounding paragraph. Block math (`$$...$$`) is compiled with
-tectonic and rasterized with Ghostscript into a real image, shown the
-same way as a regular image. If graphics aren't supported by your
-terminal, block math falls back to the same Unicode approximation as
-inline math.
-
-### Images
-
-```
-
-```
-
-Shown as a real image via the Kitty Graphics Protocol (with the caption
-rendered below it) on terminals that support it; falls back to plain alt
-text everywhere else. A `.gif` with more than one frame plays back for
-real, looping, entirely on the terminal's side.
-
-### Bibliography & citations
-
-Point `bibliography` (see [Configuration](#configuration)) at a `.bib`
-file, then cite entries anywhere in your slides:
-
-```
-This result matches prior work [@smith2020].
-```
-
-Citations are numbered by order of first appearance across the whole
-presentation; the same key cited again reuses its number. A `References`
-slide listing every cited entry (IEEE-ish numeric style) is appended
-automatically. Keys not found in the `.bib` file are left as literal
-`[@key]` text.
-
-### Configuration
-
-`slides` allows you to customize your presentation's look and feel with metadata at the top of your `slides.md`.
-
-> This section is entirely optional, `slides` will use sensible defaults if this section or any field in the section is omitted.
-
-```yaml
----
-theme: ./path/to/theme.json
-author: Gopher
-date: MMMM dd, YYYY
-paging: Slide %d / %d
-bibliography: ./path/to/refs.bib
----
-```
-
-* `theme`: Path to `json` file containing a [glamour
- theme](https://github.com/charmbracelet/glamour/tree/master/styles), can also
- be a link to a remote `json` file which slides will fetch before presenting.
-* `author`: A `string` to display on the bottom-left corner of the presentation
- view. Defaults to the OS current user's full name. Can be empty to hide the author.
-* `date`: A `string` that is used to format today's date in the `YYYY-MM-DD` format. If the date is not a valid
- format, the string will be displayed. Defaults to `YYYY-MM-DD`.
-* `paging`: A `string` that contains 0 or more `%d` directives. The first `%d`
- will be replaced with the current slide number and the second `%d` will be
- replaced with the total slides count. Defaults to `Slide %d / %d`.
- You will need to surround the paging value with quotes if it starts with `%`.
-* `bibliography`: Path to a `.bib` file, relative to the slides file. Enables
- `[@key]` citations and an auto-generated References slide. Omit to leave
- the feature off entirely.
-
-#### Date format
-
-Given the date _January 02, 2006_:
-
-| Value | Translates to |
-|--------|---------------|
-| `YYYY` | 2006 |
-| `YY` | 06 |
-| `MMMM` | January |
-| `MMM` | Jan |
-| `MM` | 01 |
-| `mm` | 1 |
-| `DD` | 02 |
-| `dd` | 2 |
-
-### SSH
-
-Slides is accessible over `ssh` if hosted on a machine through the `slides
-serve [file]` command.
-
-On a machine, run:
-
-```
-slides serve [file]
-```
-
-Then, on another machine (or same machine), `ssh` into the port specified by
-the `slides serve [file]` command:
-```
-ssh 127.0.0.1 -p 53531
-```
-
-You will be able to access the presentation hosted over SSH! You can use this
-to present with `slides` from a computer that doesn't have `slides` installed,
-but does have `ssh`. Or, let your viewers have access to the slides on their
-own computer without needing to download `slides` and the presentation file.
-
### Credits
This is a personal fork of [maaslalani/slides](https://github.com/maaslalani/slides),
