From f8daaf293ebe8944afb94fde339aecfe91491088 Mon Sep 17 00:00:00 2001 From: Peter Kurfer Date: Thu, 23 Dec 2021 12:20:10 +0100 Subject: [PATCH] Add container image and document usage --- .goreleaser.yml | 13 +++++ README.md | 97 ++++++++++++++++++++++++++-------- build/docker/goveal.dockerfile | 9 ++++ cmd/goveal/root.go | 1 - cmd/goveal/serve.go | 2 +- 5 files changed, 97 insertions(+), 25 deletions(-) create mode 100644 build/docker/goveal.dockerfile diff --git a/.goreleaser.yml b/.goreleaser.yml index 2feed1c..7ff7cf7 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -20,6 +20,19 @@ builds: - goos: linux goarch: arm goarm: '7' + +dockers: + - id: goveal + goos: linux + goarch: amd64 + goarm: '' + ids: + - goveal + image_templates: + - ghcr.io/baez90/goveal:{{ .Tag }} + - ghcr.io/baez90/goveal:{{ .Major }} + dockerfile: ./build/docker/goveal.dockerfile + archives: - replacements: darwin: Darwin diff --git a/README.md b/README.md index 58795c3..9d80596 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,23 @@ [![Actions Status](https://github.com/baez90/goveal/workflows/Go/badge.svg)](https://github.com/baez90/goveal/actions) -Goveal is very small and very simple tool that reads Markdown from a given file, renders it into a HTML template and -serves it as local HTTP server. Right now Goveal uses Reveal.js 4.1.2 to create presentations and therefore also -includes all features of Reveal.js 4.1.2. +Goveal is very small and very simple tool that reads Markdown from a given file, renders it into an HTML template and serves it as local HTTP server. +Right now Goveal uses Reveal.js 4.2.1 to create presentations and therefore also includes all features of Reveal.js 4.2.1. + +In contrary to Reveal.js `goveal` ships with its own Markdown parser and renderer which is why some features are working slightly different from Reveal.js. +See [Markdown](#markdown) for further details. + +Besides all features from Reveal.js `goveal` comes with first class support for [mermaid-js](https://mermaid-js.github.io/). +Just inline your diagrams as code and enjoy! ## Install The easiest and fastest way to install Goveal is to use a pre-built binary from the [releases](https://github.com/baez90/goveal/releases/latest). +There's also a pre-built container image available you can use if you don't want to download the binary. + +### Build from source + If you have Go in the latest version installed you can also build your own version of Goveal: ```shell @@ -21,46 +30,88 @@ Requirements: - [task](https://taskfile.dev/) - _Optional:_ [goreleaser](https://goreleaser.com/) (for `task snapshot-release` to build all binaries) -_Note: All script tasks in the [Taskfile.yml](Taskfile.yml) are meant to be executed with Linux/MacOS. Binaries for Windows are provided but not tested!_ +_Note: All script tasks in the [Taskfile.yml](Taskfile.yml) are meant to be executed with Linux/MacOS. Binaries for +Windows are provided but not tested!_ ## Usage +### Local installation + ```bash goveal serve ./slides.md ``` -| Param | Description | Default value | -| ------------------------ | ---------------------------------------------------------------------------- | ----------------------- | -| `--host` | Hostname the binary is listening on | `localhost` | -| `--port` | Port the binary is listening on | `2233` | -| `--code-theme` | highlight.js theme to use | `monokai` | -| `--transition` | Transition effect to show between slides | `none` | -| `--navigationMode` | Navigation mode to use when using the cursor keys to navigate through slides | `default` | -| `--config` | Path to the config file see [config](#config) | `$HOME/goveal:./goveal` | -| `--horizontal-separator` | horizontal separator to split slides | `===` | -| `--vertical-separator` | vertical separator to split slides | `---` | -| `--theme` | reveal.js theme to use | `white` | -| `-h` / `--help` | shows help | | +| Param | Description | Default value | +| ---------------- | --------------------------------------------- | ----------------------- | +| `--host` | Hostname the binary is listening on | `127.0.0.1` | +| `--port` | Port the binary is listening on | `2233` | +| `--config` | Path to the config file see [config](#config) | `$HOME/goveal:./goveal` | +| `--open-browser` | Open a browser after starting the web server | `true` | +| `-h` / `--help` | shows help | | + +### Container + +Assuming your slides are in a file called `slides.md` in the current directory, you can start the presentation like +this: + +```shell +podman/docker run --rm -ti -v `pwd`:/work -w /work -p 2233:2233 ghcr.io/baez90/goveal:0 serve --host 0.0.0.0 slides.md +``` + +By default `goveal` only listens on `127.0.0.1`. To allow traffic from outside of the container you've to change the +binding to `0.0.0.0`. ## Config Goveal supports multiple configuration mechanisms. It tries to load a configuration file from `$HOME` or from `.` i.e. `$HOME/goveal.yaml` or `$HOME/goveal.yml` or `./goveal.yaml` and so on. -Most options that can be set via commandline flags can also be set via configuration file (actually all but -the `--config` switch does not make sense in the configuration file, does it? :wink:). It is more a convenience feature -to be able to set a theme and so on and so forth for the presentation without having to pass it every time as parameter. +The config allows setting a lot of options exposed by Reveal.js. +There are still a few missing, and I won't guarantee to support all options in the future. -Furthermore goveal supports configuration hot reloading i.e. you can play around with different themes and the rendered +Furthermore, `goveal` supports configuration hot reloading i.e. you can play around with different themes and the rendered theme will be changed whenever you hit the save button! See also an example at [`./examples/goveal.yaml`](./examples/goveal.yaml). +I try to keep the example up to date to cover **all** supported config options as kind of documentation. -### Custom CSS +## Markdown + +A good point to start is the [slides.md](examples/slides.md) in the `examples` directory. +I try to showcase everyting possible with `goveal` in this presentation. + +The most remarkable difference between `goveal` and the `marked` driven Reveal.js markdown is how line numbers in listings are working: + +Reveal.js: + +
```cs [1-2|3|4]
+var i = 10;
+for (var j = 0; j < i; j++) {
+    Console.WriteLine($"{j}");
+}
+```
+ +`goveal`: + +

+{line-numbers="1-2|3|4"}
+```cs
+var i = 10;
+for (var j = 0; j < i; j++) {
+    Console.WriteLine($"{j}");
+}
+```
+ +This is because the Markdown parser used in `goveal` currently does not support additional attributes for code blocks. + +## Custom CSS To add custom CSS as theme overrides use a config file and add the `stylesheets` property. It takes a list of relative ( mandatory!) paths to CSS files that are included automatacally after the page was loaded so that they really overload everything added by Reveal and plugins. -the sample configuration file [`./examples/goveal.yaml`](./examples/goveal.yaml) also contains a sample how to add -custom CSS. +Changes in the custom CSS files are monitored and propagated via SSE to the presentation immediately. +No page reload necessary! + +The sample configuration file [`./examples/goveal.yaml`](./examples/goveal.yaml) also contains a sample how to add +custom CSS. \ No newline at end of file diff --git a/build/docker/goveal.dockerfile b/build/docker/goveal.dockerfile new file mode 100644 index 0000000..15324f3 --- /dev/null +++ b/build/docker/goveal.dockerfile @@ -0,0 +1,9 @@ +FROM gcr.io/distroless/static:nonroot + +USER nonroot:nonroot + +COPY --chown=nonroot:nonroot goveal /app/goveal + +EXPOSE 2233 + +ENTRYPOINT ["/app/goveal"] \ No newline at end of file diff --git a/cmd/goveal/root.go b/cmd/goveal/root.go index 6ff78b2..dcad82e 100644 --- a/cmd/goveal/root.go +++ b/cmd/goveal/root.go @@ -49,5 +49,4 @@ It is not required to restart the server when you edit the markdown - a simple r func init() { rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.go-reveal-slides.yaml)") - rootCmd.PersistentFlags().StringVar(&workingDir, "working-dir", workingDir, "working directory to use") } diff --git a/cmd/goveal/serve.go b/cmd/goveal/serve.go index 3d94658..75ac618 100644 --- a/cmd/goveal/serve.go +++ b/cmd/goveal/serve.go @@ -24,7 +24,7 @@ import ( ) const ( - defaultListeningPort uint16 = 3000 + defaultListeningPort uint16 = 2233 defaultHost = "127.0.0.1" )