readme.md 3.1 KB
Newer Older
Henrik Tramberend's avatar
Henrik Tramberend committed
1
2
3
4
5
6
7
8
9
10
11
# decker

A markdown based tool for slide deck creation.

## Usage

*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
12
-   `*-deck.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
13

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

    -   `*-deck.html` A reveal.js based slide show
    -   `*-handout.hmtl` A HTML document containing the speaker notes to the
        slide show.
    -   `*-deck.pdf` A PDF version of the slide show
    -   `*-handout.pdf` A PDF version of the handout

Henrik Tramberend's avatar
Henrik Tramberend committed
23
-   `*-page.md`
Henrik Tramberend's avatar
Henrik Tramberend committed
24

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

## *decker* targets

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

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

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

    Builds HTML versions of all available documents.

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

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

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.
Henrik Tramberend's avatar
Henrik Tramberend committed
50
51
52
    Each change to a watched document triggers a rebuild. Watching can be
    terminated with `^C`.

Henrik Tramberend's avatar
Henrik Tramberend committed
53
-   `decker server`
Henrik Tramberend's avatar
Henrik Tramberend committed
54
55

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

Henrik Tramberend's avatar
Henrik Tramberend committed
60
-   `decker example`
Henrik Tramberend's avatar
Henrik Tramberend committed
61

Henrik Tramberend's avatar
Henrik Tramberend committed
62
    Write a few example files to the current directory. To start exploring decker
Henrik Tramberend's avatar
Henrik Tramberend committed
63
64
65
66
67
68
69
70
71
72
    type

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

    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
73
-   `decker clean`
Henrik Tramberend's avatar
Henrik Tramberend committed
74
75

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

Henrik Tramberend's avatar
Henrik Tramberend committed
77
-   `decker check`
Henrik Tramberend's avatar
Henrik Tramberend committed
78

Henrik Tramberend's avatar
Henrik Tramberend committed
79
    Check for all required external depencies. If one of the programs is missing,
Henrik Tramberend's avatar
Henrik Tramberend committed
80
81
82
83
84
85
86
    an error is generated. Required programs include:

    -   `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
87
-   `decker plan`
Henrik Tramberend's avatar
Henrik Tramberend committed
88

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

Henrik Tramberend's avatar
Henrik Tramberend committed
91
-   `decker meta`
Henrik Tramberend's avatar
Henrik Tramberend committed
92
93

    Pretty prints all meta data that can be found in `*.yaml` files in the
Henrik Tramberend's avatar
Henrik Tramberend committed
94
95
96
    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
97
-   `decker publish`
Henrik Tramberend's avatar
Henrik Tramberend committed
98
99

    Publish the generated files to a remote location using `rsync` if the
Henrik Tramberend's avatar
Henrik Tramberend committed
100
101
102
    location is specified in the meta data. The keys `rsync-destination.host` and
    `rsync-destination.path` specify the publishing destination.