-
Notifications
You must be signed in to change notification settings - Fork 25
/
user-guide.mdp
3642 lines (2327 loc) · 145 KB
/
user-guide.mdp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=def TOC Table Of Contents
=def md Markdown
=def pp Powerpoint
# &md; To &pp; User Guide
This document describes the md2pptx &md; preprocessor, which turns &md; text into a &pp; presentation (whether .pptx or [.pptm](#invoking-a-vba-macro)).
In this document we'll refer to it as "md2pptx", pronounced "em dee to pee pee tee ex".
As you can see in the [change log](#change-log), md2pptx is frequently updated - both for bug fixes and enhancements.
=toc 2 * &TOC;
## Why md2pptx?
There are advantages in creating presentations using a flat file format. \
Some of these are:
* You can use any text editor on any platform to create the file.
* Other tools can generate the file.
For example, the author uses iThoughtsX on Mac, with its counterpart (iThoughts) on iOS, to generate presentations from outlines.
* Text editing tools are far quicker and more flexible that the &pp; presentation editor.
* Versioning and collaboration tools - such as git - are much easier to use with a text file than a &pp; presentation file.
* Other flat file formats can be embedded.
With md2pptx you can use a simple Task Management format called [Taskpaper](https://support.omnigroup.com/omnifocus-taskpaper-reference/) to embed tasks. md2pptx will extract such tasks and generated a "Tasks" slide at the end of the presentation.
The flat file format that md2pptx uses is &md;. \
Using &md; has further advantages:
* The same text could be used to start, or even complete, a document of a different kind. Perhaps a long-form document.
* You can render the material in a web browser. \
Builds of this very documentation are checked that way.
* Markdown is easy to write.
* Markdown is compact; The files are tiny.
* Markdown is used in popular sites, such as [Github](https://github.com).
Every piece of text you use to create a &pp; presentation with md2pptx is valid &md; - [with very few exceptions](#deviations-from-standard-markdown). \
While it might not render exactly the same way put through another &md; processor, it is generally equivalent. \
This is one of the key aims of md2pptx.
One final advantage of the md2pptx approach is you can generate presentations without using PowerPoint itself. \
Indeed you can create presentations on machines where PowerPoint won't even run. \
All you need is to be able to run Python 3 and install python-pptx.
### A Real World Use Case
The author developed a presentation over 10 years in &pp; and OpenOffice and LibreOffice. \
It became very inconsistent in formatting - fonts, colours, indentations, bullets, etc.. \
It was a horrible mess.
He took the trouble to convert it to &md; and regenerated it with a very early version of md2pptx. \
The presentation looks nice again, with consistent formatting.
It was relatively little trouble to convert to &md;. \
In fact it took about an hour to convert the 40 slide presentation. \
The consistency gain was automatic.
### Using md2pptx With mdpre
The author also developed [mdpre](https://github.com/MartinPacker/mdpre) - and actively maintains it.
mdpre is a preprocessor to create Markdown. \
It has a number of features that might be of use in creating Markdown, with an especial focus on preparing Markdown for md2pptx. \
These features include:
* Including files.
* Setting (and querying) variables.
* Conditional processing.
* Conversion of CSV files to Markdown tables.
* Creating Table Of Contents slides.
* Generating a slide with annotated "month view" calendars.
The author has made running mdpre and md2pptx together easier by creating a [make](https://en.wikipedia.org/wiki/Make_(software)) file. \
Here is an example (only tested on Mac OS).
Of\ Names\ And\ Numbers.pptx: Of\ Names\ And\ Numbers.md
md2pptx Of\ Names\ And\ Numbers.pptx < Of\ Names\ And\ Numbers.md >> Of\ Names\ And\ Numbers.log
cat Of\ Names\ And\ Numbers.log
Of\ Names\ And\ Numbers.md: Of\ Names\ And\ Numbers.mdp
mdpre -v < Of\ Names\ And\ Numbers.mdp > Of\ Names\ And\ Numbers.md 2> Of\ Names\ And\ Numbers.log
## How Do You Use md2pptx?
You write Markdown in exactly the same way as normal, with some understanding of how Markdown is converted to slides (using the information in [Creating Slides](#creating-slides)).
To use md2pptx you need to download it and install the prerequisites.
### Installation
To install md2pptx and its prerequisites
1. Have Python 3.8 or higher installed.
1. Install python-pptx using the command `pip3 install python-pptx`. (You might have to install pip firsst.)
1. Optionally install CairoSVG - using the command `pip3 install cairosvg`. (This is for SVG graphics support.)
1. Install md2pptx by copying a version and unzipping it or using `git clone`. md2pptx can be found [here](https://github.com/MartinPacker/md2pptx).
### Use
The following instructions are for Unix-like systems. (It's developed and used by the developer on Mac OS but should also have identical syntax on Linux.) Windows users will need a slightly different form, but the principle is the same.
Here is a sample invocation:
md2pptx powerpoint-filename < markdown-filename
An alternative is to have the Markdown be in-stream. md2pptx reads from stdin. \
You can, of course, use stdin in a pipeline. Indeed the developer uses this to pipe from another program. \
Alternatively, you can specify both an input file and an output file:
md2pptx markdown-filename powerpoint-filename
If the input file doesn't exist md2pptx will terminate with a message. If the input file is empty the same thing will happen.
If you don't specify an input filename and don't redirect stdin md2pptx will await terminal input. \
This works but is probably only useful when experimenting with syntax with md2pptx.
Messages are written to stderr.
## python-pptx license
While [python-pptx](http://python-pptx.readthedocs.io/en/latest/) is not included in md2pptx it is used by it.
To quote from the python-pptx license statement:
The MIT License (MIT)
Copyright (c) 2013 Steve Canny, https://github.com/scanny
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
## Change Log
=colalign l r l
=csv
Level,Date,What
4.3.3,20 January 2024,Cards can now have audio where a graphic might be. Also media can have a "poster" image for when the media isn't playing. See [Card Graphics, Video, & Audio](#card-graphics-video-audio).
4.3.2,17 January 2024,Cards can now have a video where a graphic might be. See [Card Graphics, Video, & Audio](#card-graphics-video-audio).
4.3.1,13 January 2024,Card graphics are now clickable and can have tooltips. They can also use `data:` URL's.
4.3,3 January 2024,Added [card graphics](#card-graphics-video-audio) support and [`CardGraphicPosition`](#card-graphic-positioning-cardgraphicposition), [`CardGraphicSize`](#card-graphic-size-cardgraphicsize), and [`CardGraphicPadding`](#card-graphic-padding-cardgraphicpadding).
4.2.1,28 December 2023,Made [`backgroundImage`](#specifying-slide-background-images-with-backgroundimage) create **real** slide backgrounds.
4.2,27 December 2023,Added background image support using [`backgroundImage`](#specifying-slide-background-images-with-backgroundimage).
4.1.2,11 July 2023,Fixed two bugs: Using `<sub>` & `<sup>` causes a crash. Also [Card Slides](#card-slides) cause a crash.
4.1.1,10 July 2023,Added [`numbersFontSize`](#specifying-slide-number-font-size-with-numbersfontsize) and [`footerFontSize`](#specifying-footer-font-size-with-footerfontsize).
4.1,28 April 2023,Added [`funnelLabelsPosition`](#funnel-labels-position-funnellabelsposition) and [`funnelWidest`](#funnel-orientation-funnelwidest). Added [`cardTitleBackground`](#card-title-background-colours-cardtitlebackground). Added quotation mark related [HTML entity references](#html-entity-references).
4.0,7 April 2023,Added [Funnel](#funnels) support. [`CardColour`](#card-background-colour-cardcolour) can now be pluralised: `CardColors` or `CardColours`.
3.7,26 March 2023,Added [`cardDividerColour`](#card-divider-colour-carddividercolour). Most colours now RGB or Theme Colour (documented in [Specifying Colours](#specifying-colours)).
3.6,18 March 2023,Added [`cardTitleColour`](#card-title-colour-cardtitlecolour) & `line` for [`cardshape`](#card-shape-cardshape). Allow multiple colours for [`cardColour`](#card-background-colour-cardcolour).
3.5.2,14 March 2023,Added [`pageTitleAlign`](#page-title-alignment-pagetitlealign) - for content page title alignment.
3.5.1,3 March 2023,[`pageSubtitleSize`](#page-subtitle-size-pagesubtitlesize) supports `same` meaning "same font size as first line".
3.5.1,25 February 2023,Added support for separately scaling second and subsequent slide title lines - with [`pageSubtitleSize`](#page-subtitle-size-pagesubtitlesize).
3.5,18 February 2023,Added support for GraphViz .dot file rendering within triple backticks
3.4.1,23 October 2022,Added support for a few more [slide transitions](#slide-transitions-transition): `wipe`, `vortex`, `fracture`, `split`, and `push`.
3.4,16 October 2022,Added support for a small number of [slide transitions](#slide-transitions-transition).
3.3.3,8 October 2022,Fixed bug where coding a MultiMarkdown style heading ID deleted the text to the right. Noted outbound links from headings are a [deviation from standard Markdown](#deviations-from-standard-markdown).
3.3.2,6 September 2022,Fixed bug where expanding sections crashed md2pptx. Clarified supported section name characters. See [sectionsExpand](#make-expandable-sections-sectionsexpand).
3.3.1,3 September 2022,[Processing Summary](#processing-summary) slide can have up to 5 column pairs. `<span class=>` matching lower cased.
3.3,9 August 2022,Added [sectionsExpand](#make-expandable-sections-sectionsexpand) to enable sections to expand and contract.
3.2.2,10 June 2022,Enhanced [custom footer text](#footer-flexibility) with presentation title and subtitle. Added specifying individual lines from these and section titles. Handle `<br/>`.
3.2.1,8 June 2022,Added [presTitleSize](#presentation-title-size-prestitlesize) and [presSubtitleSize](#presentation-subtitle-size-pressubtitlesize).
3.2,22 May 2022,Clearing the Processing Summary slide no longer removes Action Button objects. [Pseudo-footers can be created](#specifying-footer-text).
3.1,27 April 2022,Added support for [VBA macro invocation](#invoking-a-vba-macro) via `ppaction://macro?name=` syntax
3.0.1,15 April 2022,Improved error handling for embedding graphics, video, and audio from the web. Documented [here](#graphics-video-and-audio-slides).
3.0,11 April 2022,Added `<video>` and `<audio>` element support, described [here](#video-and-audio-slides). Added some links to the Change Log.
2.6.1,19 March 2022,Added [tableHeadingSize](#adjusting-table-heading-font-size-with-tableheadingsize) and fixed bug with cell spanning more than 2 columns.
2.6,18 March 2022,Support [multi-column table cells](#multicolumn-table-cells) - complying with the MultiMarkdown spec. Added [`deleteFirstSlide`](#deleting-the-first-(processing-summary)-slide-with-deletefirstslide).
2.5.5,5 March 2022,Make [`tableMargin`](#tablemargin-dynamic), [`marginBase`](#marginbase-dynamic), and [`numbersHeight`](#numbersheight-dynamic) dynamically settable.
2.5.4,3 March 2022,Where possible use `Content-Type` HTTP header to determine graphics file type when fetched from the web.
2.5.3,1 March 2022,Added exception handling when creating temporary file. Also when retrieving files from a URL.
2.5.2,27 February 2022,Added [`tempDir`](#specifying-where-temporary-files-are-stored-with-tempdir) to specify where temporary files are stored.
2.5.1,12 February 2022,Fixed bug 110 - crash on bad metadata line
2.5,14 November 2021,Added support for ` `. [`exportGraphics: yes`](#exporting-converted-svg-and-png-files-exportGraphics) exports PNG for SVG & EPS files. Added support for EPS graphics.
2.4.3,24 October 2021,Added support for indirect links, complementing reference links.
2.4.2,18 October 2021,Added [`hideMetadata: style`](#hidemetadata) - to suppress `style.` items in the Processing Summary slide. Also flag overridden values in same.
2.4.1,2 October 2021,Fixed bug where code appeared in a slide's Notes slide
2.4,19 September 2021,Some simple style information added to span support. fgcolor & bgcolor hex RGB metadata values are checked for validity.
2.3.4,7 September 2021,Added [`SectionArrows`](#section-navigation-buttons-sectionarrows) which enables navigation buttons between Section slides. [`SectionArrowsColour`](#section-navigation-buttons-colour-sectionarrowscolour) sets the buttons' background colour.
2.3.3,27 August 2021,Added [`TOCStyle: plain`](#plain-style-table-of-contents) Table Of Contents layout. Also can enable internal links in TOC and Section slides. Fixed `addTableLines` bug.
2.3.2,23 August 2021,Added [`TOCStyle: circle`](#circle-style-table-of-contents) Table Of Contents layout. Also metadata to control Table Of Contents layout.
2.3.1,21 August 2021,Forgot to mention [`prev` / `pop`](#dynamic-metadata) in documentation for 2.3.
2.3,21 August 2021,Fixed "slide title as heading reference bug". Added Python release to runtime output. Refactored metadata handling.
2.2.5,5 August 2021,You can turn on lines after table rows and columns with `addTableRowLines` and `addTableColumnLines`. You can also do `addTableLines` on a slide-by-slide basis. Also `addTableLineColour`, `addTableLineWidth`, and `addTableLineCount`.
2.2.4,30 July 2021,You can turn on a border round a table or all cells with `addTableLines`. Fixed bug where slide notes appeared containing code fragments and subtitles.
2.2.3,25 July 2021,Code etc blocks can include numeric character and entity references
2.2.2,22 July 2021,Fixed bug where code blocks not initialised to none on starting a new slide
2.2.1,19 July 2021,Added `AdjustTitles` - to control whether md2pptx adjusts slide title positions and sizes. Made slide notes work again.
2.2,20 June 2021,Added `IndentSpaces` - to control, including dynamically, how many spaces represent a single level of list indentation.
2.1,21 May 2021,Added `λ`, `μ`, `ν`, `&pi`, `&rho`. Allow more than one table or code block on a slide.
2.0.2,3 May 2021,A single code block can share a slide with a list block or a table / graphics block
2.0.1,1 May 2021,Added `×`, `%`, `÷`, `∀`, `∃`. Fixed 'three up graphic' layout bug.
2.0,11 April 2021,Two slide content elements on a slide, involving a major restructuring of the slide layout engine.
1.9.5,28 March 2021,Added `…`. Allow specification of gaps between cards. Allow specification of heading level for title slide.
1.9.4,21 March 2021,Added controls code slide foreground and background colour RGB values.
1.9.3,21 March 2021,Added controls on how many columns wide code is and fixed pitch height to width ratio.
1.9.2,16 March 2021,Added `<pre>`, `<code>`, triple backtick - with `<span>` colouring for `<pre>`. Added ways to make a no-title slide.
1.9.1,6 March 2021,Added `✓` entity reference. Reworked internals with more consistent layout and `getContentRec` and title formatting improvements. Prereq Python 3.8.
1.9,17 February 2021,Add support to specify which slide in master. Also numbersMargin
1.8.1,10 February 2021,Card options: Rounded versus square corners. Titles above or in cards
1.8,31 January 2021,SVG support for file and web graphics
1.7.2,24 January 2021,Make vertical bars optional around image references
1.7.1,11 January 2021,Fixed bug where hyperlinks in slide titles didn't work
1.7,9 January 2021,Added support for numbered list items
1.6.3,2 January 2021,Added support for vertical cards. Also new `CardTitleAlign` and `CardLayout` metadata, plus `basetextsize` and `basetextdecrement` Dynamic Metadata items.
1.6.2,1 January 2021,Added 3 slide-level Dynamic Metadata capabilities and `cardpercent` metadata value.
1.6.1,29 December 2020,Added `<a id=` as an alternative hyperlink anchor.
1.6,22 December 2020,Added [Card Slide](#card-slides) support. Metadata keys are now case-insensitive.
1.5,7 December 2020,Pictures now can have a tooltip. You can define inter-slide links on both pictures and runs of text. You can omit the final `|` of a table line.
1.4,23 November 2020,Task slides' slide numbers are hyperlinked to the relevant slide
1.3,20 November 2020,Glossary terms now have tooltips and hyperlinks to the relevant Glossary slide. Footnotes have hyperlinks to the relevant Footnotes slide.
1.2,3 November 2020,Support URLs for graphics. Reworked Processing Summary slide to use a flowed table.
1.1,25 October 2020,Introduce Template as a better replacement for Master - which still works. Add German characters. Better template file searching. Escape underscore. Better handling of continuation onto second and subsequent lines.
1.0,13 October 2020,Python 3, Support input filename as first command line parameter.
0.9,4 September 2020,Footnote slide support
0.8,14 June 2020,`bgcolor` is now `style.bgcolor`. Added `style.fgcolor` and `style.emphasis`.
0.7.3,24 May 2020,Allow background colouring via `span` elements
0.7.2,14 April 2020, Support three graphics on a slide. Added `=` entity reference. Added `tableMargin`.
0.7.1,14 November 2019, Make slide titles longer. Fixed formatting issue with one-graphic-above-another table slide.
0.7,3 November 2019,Support `abbr` element as a glossary item. Each distinct term leads to a glossary slide entry at the back of the presentation.
0.6,8 October 2019,Support vertical pair of graphics in a table<br/>Fixed some issues with Markdown-syntax hyperlinks<br/>Support escaped square brackets `\[` and `\]`,`[` and `]` being newly-supported alternatives
0.5,12 May 2019,CriticMarkup support
0.4.5,5 May 2019,Some numeric character references
0.4.4,6 March 2019,Processing summary slide shows build date and time
0.4.3,20 January 2019,Support a few HTML entity references - punctuation and arrows.<br/>Support split task slide sets - completed and incomplete.<br/>Task tags are sorted.
0.4.2,13 January 2019,Tasks slide set controllable with metadata `taskSlides` and `tasksPerSlide`
0.4.1,9 January 2019,Enhanced Taskpaper support with `@due`, `@tags`, and `@done`, and reworked as a series of table slides.
0.4,7 January 2019,Support shrinking of table cell font and margins.<br/>Added two-to-by-two grid of graphics on a slide.
0.3.2,3 January 2019,"Support `\#` as a literal octothorpe/hash/pound.<br/>Tidied up reporting.<br/>Added superscript, subscript, strikethrough, and underline text effects."
0.3.1,3 November 2018,Fixed support for `<br/>` so it won't create a bullet on the new line.
0.3,22 October 2018,Added customisation for bold and italic text
0.2,3 September 2018,Added ways of controlling bullet sizes
0.1,1 April 2018,Initial Prototype
=endcsv
## Creating Slides
<a id="creating-slides"></a>
Let's start with a simple example. \
Consider the following text.
template: Martin Template.pptx
pageTitleSize: 24
sectionTitleSize: 30
# This Is the Presentation Title Page
## This Is A Section
### This Is A Bullet Slide
* Bullet One
* Sub-bullet A
* Sub-bullet B
* Bullet Two
* Bullet Three
You can try it if you like. Just cut it and paste it into a file. \
Call it something like Example.markdown.
It will render something like this:
The first slide is special, and an almost inevitable feature of using the python-pptx library. \
You will probably want to remove it before publishing.
If there is at least one slide in the presentation template md2pptx uses the first one to create a processing summary. \
The processing summary slide shows processing options, the time and date the presentation was created by md2pptx, and metadata.
Metadata is specified in the first three lines of this sample. \
In general metadata is the set of lines before the first blank line. \
It consists of key/value pairs, with the key separated from the value by a colon.
In this case the metadata specifies a number of things:
1. The &pp; file the presentation is based on is "hipodz.pptx".
1. Each slide with a title has a title font 22 points high.
1. Each presentation section slide has a title font 30 points high.
1. A number of other styling-related specifications.
All of the above are optional but you will almost certainly want to specify a template. \
Feel free to copy Martin Template.pptx - which is included with md2pptx - and make stylistic changes.
For more on metadata see [Controlling The Presentation With Metadata](#controlling-the-presentation-with-metadata).
As you can see the format of each slide is fairly straightforward. \
How to code slides is described in the following sections.
### Presentation Title Slides
<a id="presentation-title-slides"></a>
You code a presentation title slide with a &md; Heading Level 1:
# This Is the Presentation Title Slide
If you type anything in subsequent lines - before a blank line - the text will appear as extra lines in the presentation title. \
You might use this, for example, to add the presentation authors' details.
(You can adjust the Markdown heading level for this type of slide with [`TopHeadingLevel`](#slide-heading-levels-topheadinglevel).)
### Presentation Section Slides
You code a presentation section slide with a &md; Heading Level 2:
## This Is A Section
You can code multiple lines, as with [Presentation Title slides](#presentation-title-slides).
**Notes:**
1. You can adjust the Markdown heading level for this type of slide with [`TopHeadingLevel`](#slide-heading-levels-topheadinglevel)
2. You can make the section slides be the start of expandable and contractable sections with [`sectionsExpand`](#make-expandable-sections-sectionsexpand).
### Bullet Slides
<a id="bullet-slides"></a>
Bullet slides use &md; bulleted lists, which can be nested. \
This example shows two levels of nesting.
### This Is A Bullet Slide
* Bullet One
* Sub-bullet A
* Sub-bullet B
* Bullet Two
* Bullet Three
The title of the slide is defined by coding a &md; Heading Level 3 (`###`).
**Note:** \
You can allow the title to spill onto a second line but it is better to break titles up using `<br/>`. \
Doing so enables md2pptx to layout slide contents below the title better. \
It also allows you to specify a different (probably) smaller font size for the second and subsequent lines of the title.
Bulleted list items are introduced by an asterisk.
**Note:** \
Some dialects of &md; allow other bullet markers but md2pptx doesn't. \
You can be sure by coding `*` you have valid &md; that md2pptx can also process correctly. \
For an explanation of why you have to stick to `*` see [here](#task-list-slides).
To nest bullets use a tab character or 2 spaces to indent the sub-bullets. \
md2pptx doesn't have a limit on the level of nesting but &pp; probably does.
Terminate the bulleted list slide with a blank line.
**Note:** \
You can alter the number of spaces that represent each level of indenting. See [Specifying How Many Spaces Represent An Indentation Level With `IndentSpaces`](#specifying-how-many-spaces-represent-an-indentation-level-with-indentspaces). \
If you use tabs they will be converted to the the appropriate number of spaces internally.
#### Numbered List Items
<a id="numbered-items"></a>
Within a bullet slide you can have numbered items. \
Here is an example of a slide with mixed numbers and bullets:
### This Is A Mixed Numbers And Bullets Slide
* Bullet One
1. Numbered sub-bullet A
1. Numbered sub-bullet B
* Bullet Two
* Bullet Three
Numbered list items are introduced with an integer, followed by a full stop.
Markdown takes care of the numbering. \
In the above example there are two numbered items. \
While the first will indeed be numbered "1" the second will be numbered "2", despite the `1.` coding.
Numbering with `1.` is actually a useful practice - as it makes it easier to reorder a numbered list (by moving the lines around).
**Note:** \
You can mix numbered and bulleted items in a list.
### Graphics, Video And Audio slides
<a id="graphics-video-and-audio-slides"></a>
You can embed three kinds of media in slides:
* [Graphics](#graphics-slides)
* [Videos](#video-slides)
* [Audio files](#audio-slides)
These media items can be from your file system, or over the web.
If a local file is found a simple "missing" file message is printed.
In the case of over the web, two kinds of errors can be detected and reported:
* The domain is unreachable, reported as a socket error.
* The domain is reachable, but an error occurred in retrieving the file. \
In this case the HTTP code is reported, helping you debug whether the filename is wrong (404) or some other issue.
#### Graphics Slides
<a id="graphics-slides"></a>
As with [bullet slides](#bullet-slides), code the slide title as a Markdown Heading Level 3. \
Specify the graphic to embed with the standard &md; image reference:
### A Graphic Slide
The graphic will be scaled to sensibly fill the slide area.
If you code a string inside the square brackets it will be used as a tooltip (or screentip, in Powerpoint parlance). \
In Presentation Mode, when you hover over the graphic the tooltip will be displayed. \
Here is an example:
**HINT:** If you want two graphics side by side use a single-row table, described [here](#special-case-two-graphics-side-by-side). \
If you want two graphics one above the other use a two-row, single-column table, described [here](#special-case-one-graphic-above-another).
##### Clickable Pictures
<a id="clickable-pictures"></a>
You can make a picture clickable, with an optional tooltip. \
This means you can click on a picture in slideshow mode to go to another slide. \
The tooltip is shown in slideshow mode when your mouse hovers over the picture.
Here's an example, showing both a tooltip and a clickable link.
[](#sonic-highways)
Here the image reference is embedded in the clickable link:
* The tooltip text is `Foo Fighters Sonic Highways`.
* The picture's source is `https://upload.wikimedia.org/wikipedia/en/6/67/Foo_Fighters_8LP_Sonic_Highways.jpg`
* The target slide has the heading reference `sonic-highways`.
To create a hyperlink to a slide with heading reference code something like this as the title of that slide:
### My Slide’s Title [sonic-highways]
See [Hyperlinks](#hyperlinks) for more on creating hyperlinks.
##### Graphics File References
<a id="graphics-file-references"></a>
md2pptx supports graphics references in three different formats:
* A local file reference - ``
* A HTTP(S) reference - ``
* A `data:` URI reference - ``
The `data:` URI example actually works! Try it.
For cases other than the local file, the reference - when displayed by md2pptx - is shortened to show the beginning and the end of the reference. This is to make it easy to recognise if you've accidentally repeated the reference. Here is an example:
```
Slides:
=======
1 Test Title --> data:image/png;base64,/9j.../Nka02WcDC6hCtKgQhCAP/9k=
```
For image graphics only PNG and JPEG have been tested. \
While the code doesn't explicitly prohibit other image file types they aren't currently supported.
Scalable Vector Graphics (SVG) format is only supported if you have installed the CairoSVG Python package - as PowerPoint doesn't support it (and nor does python-pptx). \
SVG files - whether from the web or a local file - are converted to a temporary PNG file first, before copying into the PowerPoint slide deck.
SVG support uses the [CairoSVG](https://cairosvg.org/) library - which requires Python to be at least at the 3.6 level. \
md2pptx's SVG support is limited by that available in CairoSVG and so not all SVG files are supported.
If CairoSVG is not installed and md2pptx encounters an SVG graphic reference it will write a message reminding you of the need for CairoSVG. \
md2pptx will then immediately terminate.
Encapsulated Postscript (EPS) format is only supported if you have installed the [Pillow Python package](https://python-pillow.org/) and [Ghostscript](https://www.ghostscript.com/) - as PowerPoint doesn't support it (and nor does python-pptx). \
EPS files - whether from the web or a local file - are converted to a temporary PNG file first, before copying into the PowerPoint slide deck. \
Pillow requires Python to be at least at the 3.7 level.
You can optionally have md2pptx export the temporary PNG files. See [Exporting Converted SVG And PNG Files - `exportGraphics`](#exporting-converted-svg-and-png-files-exportGraphics). \
The file name is the same as the SVG or EPS file's name, except the extension is PNG.
**Notes:**
1. You can specify which directory temporary files, such as temporary graphics, are stored in - using [`tempDir`](#specifying-where-temporary-files-are-stored-with-tempdir).
2. For graphics - whether image or vector - retrieved from the Internet md2pptx will attempt to acquire the MIME type (`Content-Type` HTTP header) to determine what type the graphic is:
* PNG - `image/png`
* JPEG - `image/jpeg` or `image/jpg` (though the latter is unofficial)
* SVG - `image/svg+xml` or `image/svg` (though the latter is unofficial)
* EPS - `application/postscript`
#### Video And Audio Slides
<a id="video-and-audio-slides"></a>
Videos and audio files are supported in a similar way to [graphics slides](#graphics-slides). \
However, there is no Markdown support for embedding videos or audio files. \
Fortunately, Markdown processors support HTML.
You should be aware that, though you can legitimately embed a video or audio, Powerpoint might not be able to play it on all platforms.
##### Video Slides
<a id="video-slides"></a>
md2pptx supports embedding videos using the HTML `<video>` element.
Here is an example:
<video height=300 width=400 src="waterdrop.mp4"></video>
md2pptx uses the values of the `height` and `width` elements to compute the aspect ratio of the video. \
In this example the ratio of the width to height is 4 to 3.
Optionally, you can code a `poster` attribute. \
This defines a static graphic to be displayed when the video isn't playing. \
Here's an example:
<video width="400" height="300" src="waterdrop.mp4" poster="Battery W3M.png">
**Notes:**
1. Unlike with graphics specified according to [Graphics Slides](#graphics-slides), the poster graphic's dimensions are not used to scale the poster graphic or the video.
1. md2pptx supports only the simplest form of the `<video>` element.
##### Audio Slides
<a id="audio-slides"></a>
md2pptx supports embedding audio files using the HTML `<audio>` element.
Here is an example:
<audio src="audiotest.mp4"></audio>
Optionally, you can code a `poster` attribute. \
This defines a static graphic to be displayed when the audio file isn't playing. \
Here's an example:
<audio src="audiotest.mp4" poster="my-album-cover.png"></audio>
**Notes:**
1. The HTML `<audio>` element does not support `width` or `height` attributes. \
md2pptx scales the audio file on the slide to be square.
1. Unlike with graphics specified according to [Graphics Slides](#graphics-slides), the poster graphic's dimensions are not used to scale the poster graphic or the audio file.
1. md2pptx supports only the simplest form of the `<audio>` element.
### Table Slides
<a id="table-slides"></a>
You can create a table slide using &md;'s table format.
Code a title with a Markdown Heading Level 3. \
Then code a table. \
Here is a simple example of a table:
|Left Heading|Centre Heading|Right Heading|
|:----|:-:|--:|
|Alpha|Bravo|1|
|Charlie|Delta|2|
In this example there are three columns and three rows. \
The first row is the heading row. \
The third and fourth rows are data rows.
The second row controls the alignment of each column and their width:
* In the first column the leading colon denotes the text is to be left-justified.
* In the second column the colons either end denotes the text is to be centred.
* In the third column the trailing colon denotes the text is to be right-justified.
* According to the number of dashes the columns have widths in the ratio of 4 to 1 to 2.
In other &md; processors the widths of the columns can't be specified in this way; \
The relative width specifications will be ignored.
Each cell can consist of text, which will wrap as necessary. \
You can't embed images in a table slide. \
But see [here](#special-case-two-graphics-side-by-side) and [here](#special-case-two-by-two-grid-of-graphics).
As a convenience, you can omit the final `|` on a line. \
While this isn't strictly Markdown compliant this might be helpful.
#### Special Case: Two Graphics Side By Side
<a id="special-case-two-graphics-side-by-side"></a>
The best &md; fit for two graphics side by side is a single row table with two cells. \
md2pptx will "special case" such a table.
If you code something like this the two graphics will be placed next to each other:
|||
A table won't be created in this case.
Don't code any headings or more than one row.
For the types of graphics supported see [Graphics File References](#graphics-file-references).
For how to make such graphics clickable or have a tooltip see [Clickable Pictures](#clickable-pictures).
**Note:** \
Regular Markdown processors don't support pictures in tables; They render the `|` characters literally. \
For this reason the vertical bars are optional.
#### Special Case: Two By Two Grid Of Graphics
<a id="special-case-two-by-two-grid-of-graphics"></a>
The best &md; fit for four graphics on a slide is a two row table with two pairs of cells. \
md2pptx will "special case" such a table.
If you code something like this the four graphics will be placed in two rows of two:
|||
|||
A table won't be created in this case.
Don't code any headings or more than two rows.
To achieve the best result some margins around the graphics are reduced.
For the types of graphics supported see [Graphics File References](#graphics-file-references).
For how to make such graphics clickable or have a tooltip see [Clickable Pictures](#clickable-pictures).
**Note:** \
Regular Markdown processors don't support pictures in tables; They render the `|` characters literally. \
For this reason the vertical bars are optional.
#### Special Case: Three Graphics On A Slide
<a id="special-case-three-graphics-on-a-slide"></a>
The best &md; fit for three graphics on a slide is a two row table:
* The first row has two graphics.
* The second row has one graphic, centred in the row.
md2pptx will "special case" such a table.
If you code something like this the three graphics will be placed appropriately:
|||
||
Here the layout will be a "T".
A table won't be created in this case.
Don't code any headings or more than two rows.
To achieve the best result some margins around the graphics are reduced.
There are some variants on the above scheme. For example, if you code:
||
|||
Here the layout will be an inverted "T".
You can also force left alignment or right alignment of the sole graphic in a row. For example:
|||
|||
will align the sole top-row graphic to the left.
For the types of graphics supported see [Graphics File References](#graphics-file-references).
For how to make such graphics clickable or have a tooltip see [Clickable Pictures](#clickable-pictures).
**Note:** \
Regular Markdown processors don't support pictures in tables; They render the `|` characters literally. \
For this reason the vertical bars are optional.
#### Special Case: One Graphic Above Another
<a id="special-case-one-graphic-above-another"></a>
The best &md; fit for two graphics, on above the other, on a slide is a two row table with a single cell in each row. \
md2pptx will "special case" such a table.
If you code something like this the two graphics will be placed in two rows of one:
||
||
A table won't be created in this case.
Don't code any headings or more than two rows.
For the types of graphics supported see [Graphics File References](#graphics-file-references).
For how to make such graphics clickable or have a tooltip see [Clickable Pictures](#clickable-pictures).
**Note:** \
Regular Markdown processors don't support pictures in tables; They render the `|` characters literally. \
For this reason the vertical bars are optional.
#### Multi-Column Table Cells
<a id="multicolumn-table-cells"></a>
Markdown supports cells that span more than one contiguous column. \
Here's an example:
|A||C|
|:-:|:-:|:-|
|Two cells?||One?|
|1|2|3|
||A|B|
In this example
1. The empty cell in the heading line causes the "A" cell to occupy the first two columns.
1. The empty cell after "Two Cells?" causes "Two Cells?" to occupy the first two columns.
1. The empty cell at the beginning of the final row leads to an empty first cell. "A" is in the second column.
### Card Slides
<a id="card-slides"></a>
A card slide contains multiple panels - or cards. \
They come in two flavours:
* Horizontal - where the cards are next to each other
* Vertical - where the cards are one above the other
For the rest of this section the assumption is that cards are horizontally arranged. \
(Vertically-arranged cards are very similar.)
Each card has a title and, below that, the contents are defined using the same syntax as in [Bullet Slides](#bullet-slides). \
In fact this slide type is derivative of the Bullet Slide type.
A horizontally-arranged card slide can look something like this:
The key features of this slide are:
* A title, coded with Markdown Heading Level 3 syntax (`###`).
* An optional panel above the cards, coded using [Bullet Slides](#bullet-slides) syntax.
* A sequence of cards, coded one after the other but displayed side by side:
* The title is coded using Markdown Heading Level 4 syntax (`####`).
* The body of the card is coded using [Bullet Slides](#bullet-slides) syntax.
The width of each card is calculated depending on the number of cards. \
In this example the horizontal space is divided equally between the 4 cards.
In the above example there has been a small amount of tweaking of the format, using metadata. \
You can control the exact format using many tweaks:
* [Card Background Colours](#card-background-colour-cardcolour)
* [Card Border Colour](#card-border-colour-cardbordercolour)
* [Card Border Width](#card-border-width-cardborderwidth)
* [Card Title Font Size](#card-title-size-cardtitlesize)
* [Card Title Colour](#card-title-colour-cardtitlecolour)
* [Card Title Background Colours](#card-title-background-colours-cardtitlebackground).
* [Card Divider Colour](#card-divider-colour-carddividercolour)
* [Card Shadow](#card-shadow-cardshadow)
* [Card Size](#card-size-cardpercent)
* [Card Layout Direction](#card-layout-direction-cardlayout)
* [Card Title Alignment](#title-alignment-cardtitlealign)
* [Card Title Position](#card-title-position-cardtitleposition)
* [Card Shape](#card-shape-cardshape)
* [Card Horizontal Gap](#card-horizontal-gap-cardhorizontalgap)
* [Card Vertical Gap](#card-vertical-gap-cardverticalgap)
* [Card Graphic Position](#card-graphic-positioning-cardgraphicposition)
* [Card Graphic Size](#card-graphic-size-cardgraphicsize)
* [Card Graphic Padding](#card-graphic-padding-cardgraphicpadding)
One example of using a different style is this:
Here the card background is invisible but the cards are separated by lines. \
You achieve this by coding:
CardShape: line
(See [Card Shape](#card-shape-cardshape) for more information.)
#### Card Titles
In the above examples the card titles are above the cards. \
You can specify that the card titles are inside the cards, at the top. \
To do this code:
CardTitlePosition: inside
(See [Card Title Position](#card-title-position-cardtitleposition) for more information.)
You can suppress a title by coding its text value to ` `. \
If you do this for all the titles on a card slide the space reserved for card titles will be zero. \
If there are some titles not treated this way the ` `-titled cards will have a gap where the title would have been.
<a id="#card-graphics-video-audio"></a>
#### Card Graphics, Video, & Audio
You can add a single graphic, video, or audio file to each card. \
They can be placed in reserved areas before or after the card bulleted list contents.
Place any graphic, video, or audio declaration between the card's title and the card's contents. \
For example:
#### Card One
* Some content for Card One
* And some more content
As you can see, the image reference is just a standard Markdown one. \
A video reference might be of the form:
<video height=300 width=400 src="waterdrop.mp4"></video>
An audio reference might be of the form:
<audio src="audiotest.mp3" poster="Battery W2M.png"></audio>
In this case the `poster` attribute is coded. \
This enables a graphic to be shown when the audio player isn't activated. \
You can also code the `poster` attribute for a video.
**Notes:**
1. You must code a non-zero value for [`CardGraphicSize`](#card-graphic-size-cardgraphicsize) for graphics or videos to be shown. \
The default is 0.
2. If a card doesn't have a graphic or a video the bulleted list contents can fill the whole of the card (except for any title inside the card).
3. Card graphics can have tooltips and can be clickable. \
See [Graphics Slides](#graphics-slides) for how to code this. \
(audio and video can't.)
4. Media (audio or video) might not be playable on a specific platform, even though it has been legitimately embedded in a presentation.
<a id="code-slides"></a>
### Code Slides
You can create a slide where the body is in a monospace font, without bullets, in a number of different ways:
* Where what you type appears exactly as you typed it - using `<code>`, triple backticks, or by indentation.
* Where what you type can be coloured, using `<pre>` and `<span>` elements, together with `style.fgcolor` etc specifications.
When we say "code", what you're displaying could be something like a terminal screen shot, of course. \
What's important is that it will be rendered in a fixed-pitch font.
In each case, the heading for the slide is generally introduced with heading level 3 - `### `. \
However you can start a slide without a heading. \
See [Slides Without Titles](#slides-without-titles) for how to do this.
You can include [HTML entity references](#html-entity-references) and [numeric character references](#numeric-character-references). \
For example you might code `❶` to place ❶ next to a line of code. \
You could then code the same thing in a table below the code fragment, where each row explains a line of code.
**Note:** \
You can more precisely control how code slides are laid out and their colours with [Code Metadata](#code-metadata).
#### `<code>`
The HTML `<code>` element is supported. \
Surround the block of text by `<code>` and `</code`:
### This Is A Code Slide
<code>
for(i = 0; i < 10; i++){
alert(i)
}
</code>
**Note:** \
It, as in HTML, does not support `<span>` elements.
#### Triple Backticks (```)
Triple backticks are supported. \
Surround the block of text by them:
### This Is A Code Slide
```
for(i = 0; i < 10; i++){
alert(i)
}
```
**Note:** \
It does not support `<span>` elements.
<a id="special-processing-of-code-within-triple-backticks"></a>
##### Special Processing Of Code Within Triple Backticks
If you have GraphViz installed you can render GraphViz diagrams as graphics.
<a id="graphviz"></a>
###### GraphViz
On startup md2pptx will check whether the graphviz Python package is installed. \
It cannot check if the GraphViz application is installed - but you need that as well to process GraphViz .dot data.
If both the graphviz package and the GraphViz application are installed you can render .dot file format lines. \
Here is an example:
```dot
digraph G{
edge [dir=forward]
node [shape=plaintext]
0 [label="0 (None)"]
0 -> 5 [label="root" color = blue]
1 [label="1 (Hello)"]
2 [label="2 (how)"]
2 -> 1 [label="advmod"]
3 [label="3 (are)" fontcolor = green]
4 [label="4 (you)"]
5 [label="5 (doing)"]
5 -> 3 [label="aux"]
5 -> 2 [label="advanced mod"]
5 -> 4 [label="nsubj"]
}
```
This will be rendered as a graphic and inserted in the current slide. \
The graphic will be scaled as appropriate.
This is how the above code is rendered
#### Indented Text
Each line of the code fragment - to be displayed in a monospace font - is indented with 4 spaces:
### This Is A Code Slide
for i in range(10):
print(i)
**Note:** \
It does not support `<span>` elements.
#### `<pre>`
The HTML `<pre>` element is supported. \
Surround the block of text by `<pre>` and `</pre`:
### This Is A Code Slide
<pre>
for(i = 0; i < 10; i++){
alert(i)
}
</pre>
**Note:** \
It, as in HTML, **does** support `<span>` elements. \
This is the best way to provide syntax colouring. \
You can use `style.fgcolor`, `style.bgcolor`, and `style.emphasis` to style the text. \
To do this you use the `class` attribute:
<span class="keyword">for</span> (i = 0; i < 10; i ++)
### Funnels
<a id="funnels"></a>
Funnels depict a funnel, with the wide part to the left. \
Each successive stage in the funnel narrows the funnel. \
In a sense this is like a pipeline, with stages. \
Here each stage but the last narrows the pipe. \
md2pptx can create such slides from CSV data. \
A typical result looks like this:
In this example the funnel is rendered below some bullets. \
You can render funnels on the same slide as other items, which can be of any type.
The code to create this slide is:
### This Is A Funnel Slide