representative

README

representative -- Static slideshow generator for Go slides

representative takes a Go Present-style *.slide (or *.article) file and creates a static HTML page.

Install

$ go get eagain.net/go/representative/cmd/representative

Usage

Read foo.slide, write foo.html, write assets into directory named static (which will be created if needed) and assume the HTML can refer to them as static/...:

$ representative -assets=static foo.slide

What files are created as assets is not guaranteed. We recommend not trying to have other content in the same directory.

Pass any number of *.slide and *.article files.

There are two flags you can give it:

• -assets=DIR: Write assets to this directory.

  If not given, assets are not created at this time, and must be available to the HTML by some other means.

  This can be used with no files to just write assets.

• -url-to-assets=URL: Refers to assets from HTML with this base URL.

  If -assets=DIR was given, defaults to DIR, otherwise static.

Some more ways you can call it:

# Multiple slides at once
$ representative -assets=static *.slide

# Just write out the assets
$ representative -assets=static

# Just convert slides to HTML (assets assumed to be available as
# `static/...`)
$ representative foo.slide

# Write assets into custom directory name
$ representative -assets=my-asset-dir foo.slide

# Asset fetched from a subdir (default `static`), no trailing slash.
$ representative -url-to-assets=my-asset-dir foo.slide

# Assets fetched relative to arbitrary URL.
$ representative -url-to-assets=https://cdn.example.com/slide-assets/ foo.slide

History

representative was inspired by https://github.com/cmars/represent but is an independent implementation with completely different command-line interface.

Notable differences:

• representative has new slideshow features added to present after represent was last updated
• representative does not need its source tree available to access assets
• representative does not copy everything in the source directory into the publish directory; it just writes HTML

Documentation

Overview

Package representative creates static HTML for Go "represent" format slides and articles.

For more information, see https://pkg.go.dev/golang.org/x/tools/present

The HTML and assets are co-dependent and should be created with the same version of representative.

Index

• func Convert(w io.Writer, src string, urlToAssets *url.URL) error
• func WriteAssets(dir string) error

Functions

func Convert

func Convert(w io.Writer, src string, urlToAssets *url.URL) error

Convert writes the HTML for the slides or article at file path src to w.

For assets that are included in the HTML (such as code examples), it reads assets from files relative to src. The final HTML uses urlToAssets as a base URL to load assets.

func WriteAssets

func WriteAssets(dir string) error

WriteAssets writes the asset files into dir. The directory will be created if needed. The exact set of files created should not be relied on, and this directory should not be used for other purposes.