readme.md 3.17 KB
Newer Older
Henrik Tramberend's avatar
Henrik Tramberend committed
1 2 3 4
# decker

A markdown based tool for slide deck creation.

5 6 7 8 9
## Installation

1.  Install [stack](https://docs.haskellstack.org/en/stable/README/).
2.  Clone this repo.
3.  `cd repo`
Henrik Tramberend's avatar
Henrik Tramberend committed
10
4.  `stack install`
11

Henrik Tramberend's avatar
Henrik Tramberend committed
12 13
## Usage

14
*decker* behaves very much like a build tool. It works recursively on the current directory and all subdirectories. Markdown files ending on `.md` in those directories are processed and converted to either a reveal.js slide show, a HTML document, or a PDF document, depending on the file name.
Henrik Tramberend's avatar
Henrik Tramberend committed
15

Henrik Tramberend's avatar
Henrik Tramberend committed
16
-   `*-deck.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
17

18
    Files with this ending are processed as silde decks. From one source file potentially four different targets can be generated:
Henrik Tramberend's avatar
Henrik Tramberend committed
19 20

    -   `*-deck.html` A reveal.js based slide show
21
    -   `*-handout.hmtl` A HTML document containing the speaker notes to the slide show.
Henrik Tramberend's avatar
Henrik Tramberend committed
22 23 24
    -   `*-deck.pdf` A PDF version of the slide show
    -   `*-handout.pdf` A PDF version of the handout

Henrik Tramberend's avatar
Henrik Tramberend committed
25
-   `*-page.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
26

27
    Markdown files ending on `*-page.md` are translated into corresponding HTML or PDF documents.
Henrik Tramberend's avatar
Henrik Tramberend committed
28 29 30

## *decker* targets

Henrik Tramberend's avatar
Henrik Tramberend committed
31
-   `decker help`
Henrik Tramberend's avatar
Henrik Tramberend committed
32

Henrik Tramberend's avatar
Henrik Tramberend committed
33
    Prints this document to stdout in Markdown format.
Henrik Tramberend's avatar
Henrik Tramberend committed
34

Henrik Tramberend's avatar
Henrik Tramberend committed
35 36 37 38 39
-   `decker html`

    Builds HTML versions of all available documents.

-   `decker pdf`
Henrik Tramberend's avatar
Henrik Tramberend committed
40

41
    Builds PDF versions of all documents that are generated from `*-deck.md` files.
Henrik Tramberend's avatar
Henrik Tramberend committed
42

Henrik Tramberend's avatar
Henrik Tramberend committed
43 44 45
-   `decker pdf-decks`

    Builds PDF versions of all slide decks (requires `decktape.sh`).
Henrik Tramberend's avatar
Henrik Tramberend committed
46

Henrik Tramberend's avatar
Henrik Tramberend committed
47
-   `decker watch`
Henrik Tramberend's avatar
Henrik Tramberend committed
48

49
    Builds HTML versions of all documents and then watches for document changes. Each change to a watched document triggers a rebuild. Watching can be terminated with `^C`.
Henrik Tramberend's avatar
Henrik Tramberend committed
50

Henrik Tramberend's avatar
Henrik Tramberend committed
51
-   `decker server`
Henrik Tramberend's avatar
Henrik Tramberend committed
52

53
    Like `decker watch`. Additionally a local web server is started that serves the generated HTML files. The `index.html` document is automatically openend in the browser. Changed files are automatically reloaded in the browser. (requires `livereloadx`)
Henrik Tramberend's avatar
Henrik Tramberend committed
54

Henrik Tramberend's avatar
Henrik Tramberend committed
55
-   `decker example`
Henrik Tramberend's avatar
Henrik Tramberend committed
56

57
    Write a few example files to the current directory. To start exploring decker type
Henrik Tramberend's avatar
Henrik Tramberend committed
58 59 60 61 62 63

    ``` {.bash}
    $ decker example
    $ decker server
    ```

64
    and make some changes to the Markdown files. `example-deck.md` contains the source code for a slide deck that explains most of the features supported.
Henrik Tramberend's avatar
Henrik Tramberend committed
65

Henrik Tramberend's avatar
Henrik Tramberend committed
66
-   `decker clean`
Henrik Tramberend's avatar
Henrik Tramberend committed
67 68

    Recursively removes all generated files from the current directory.
Henrik Tramberend's avatar
Henrik Tramberend committed
69

Henrik Tramberend's avatar
Henrik Tramberend committed
70
-   `decker check`
Henrik Tramberend's avatar
Henrik Tramberend committed
71

72
    Check for all required external depencies. If one of the programs is missing, an error is generated. Required programs include:
Henrik Tramberend's avatar
Henrik Tramberend committed
73 74 75 76 77 78

    -   `pdflatex` as part of a complete LaTeX installation
    -   `decktape.sh` for the generation of PDF versions of slide decks
    -   `livereloadx` as live-reloading local webserver
    -   `rsync` to publish the documents to a remote location

Henrik Tramberend's avatar
Henrik Tramberend committed
79
-   `decker plan`
Henrik Tramberend's avatar
Henrik Tramberend committed
80

Henrik Tramberend's avatar
Henrik Tramberend committed
81 82
    Prints a list of all source files found below the current directory.

Henrik Tramberend's avatar
Henrik Tramberend committed
83
-   `decker meta`
Henrik Tramberend's avatar
Henrik Tramberend committed
84

85
    Pretty prints all meta data that can be found in `*.yaml` files in the current directory and below. Meta data is mainly used to perform substitutions in Markdown documents using the Mustache templating system.
Henrik Tramberend's avatar
Henrik Tramberend committed
86

Henrik Tramberend's avatar
Henrik Tramberend committed
87
-   `decker publish`
Henrik Tramberend's avatar
Henrik Tramberend committed
88

89
    Publish the generated files to a remote location using `rsync` if the location is specified in the meta data. The keys `rsync-destination.host` and `rsync-destination.path` specify the publishing destination.