Skip to content

Commit 88da78f

Browse files
codebytescodebytes
authored
Merge pull request #12 from codebytes/enhance-template-and-themes
Enhance template with CSS variable theming, Marp CLI v4, and Copilot agent
2 parents 0f10787 + 8441a64 commit 88da78f

File tree

11 files changed

+685
-103
lines changed

11 files changed

+685
-103
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,33 @@
11
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
22
// README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu
33
{
4-
"name": "Debian",
5-
// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
6-
"image": "mcr.microsoft.com/devcontainers/base:bullseye",
4+
"name": "Marp Slides",
5+
// Use Debian bookworm (stable) - required for Node.js 18+ compatibility with Marp CLI v4
6+
"image": "mcr.microsoft.com/devcontainers/base:bookworm",
77
"features": {
8-
// uncomment this to allow pptx or pdf export
8+
// Uncomment to enable PDF/PPTX export (Marp CLI v4 supports Firefox as alternative)
99
// "ghcr.io/rocker-org/devcontainer-features/apt-packages:1": {
1010
// "packages": "chromium"
1111
// }
1212
},
1313

14-
// Features to add to the dev container. More info: https://containers.dev/features.
15-
// "features": {},
16-
1714
// Use 'forwardPorts' to make a list of ports inside the container available locally.
1815
// "forwardPorts": [],
1916

20-
// Use 'postCreateCommand' to run commands after the container is created.
21-
// "postCreateCommand": "uname -a",
2217
"postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}",
2318

2419
// Configure tool-specific properties.
2520
"customizations": {
2621
"vscode": {
2722
"settings": {
28-
"markdown.marp.enableHtml" : true,
23+
"markdown.marp.enableHtml": true,
24+
"markdown.marp.mathTypesetting": "mathjax",
2925
"markdown.marp.themes": [
3026
"./slides/themes/custom.css",
3127
"./slides/themes/custom-default.css",
3228
"./slides/themes/custom-gaia.css",
3329
"./slides/themes/custom-uncover.css"
34-
]
30+
]
3531
},
3632
"extensions": [
3733
"streetsidesoftware.code-spell-checker",

‎.github/agents/marp.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
name: marp
3+
description: Expert on Markdown and Marp presentation framework. Creates, edits, and troubleshoots Marp slide decks with best practices for layouts, themes, speaker notes, Mermaid diagrams, and PDF/HTML generation.
4+
---
5+
6+
You are an expert on Markdown and the Marp presentation framework (https://marp.app/).
7+
8+
## Core Expertise
9+
10+
- Marp Markdown syntax and directives
11+
- Slide deck structure and frontmatter configuration
12+
- Built-in themes (default, gaia, uncover) and custom theming
13+
- Background images, image positioning, and filters
14+
- Speaker notes using HTML comments (`<!-- -->`)
15+
- Mermaid.js diagram integration
16+
- Multi-column layouts and CSS customization
17+
- Marp CLI for PDF, PPTX, and HTML generation
18+
19+
## Project Conventions
20+
21+
- All slides use Markdown with Marp framework
22+
- Required frontmatter:
23+
```yaml
24+
---
25+
marp: true
26+
theme: custom-default
27+
---
28+
```
29+
- Store slide decks in the `slides/` directory
30+
- Store custom themes in `slides/themes/`
31+
- Store images in `slides/img/`
32+
- Use HTML comments for speaker notes: `<!-- Speaker notes here -->`
33+
- Include Mermaid script tag when using diagrams:
34+
```html
35+
<script type="module">
36+
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
37+
mermaid.initialize({ startOnLoad: true });
38+
</script>
39+
```
40+
41+
## Available Custom Theme Classes
42+
43+
- `.columns` - Two-column grid layout
44+
- `.columns3` - Three-column grid layout
45+
- `img[alt~="center"]` - Center images with `![center](url)`
46+
- Font Awesome icons available via CDN
47+
48+
## Marp Directives Reference
49+
50+
- `---` - Slide separator
51+
- `<!-- _class: classname -->` - Apply class to current slide
52+
- `<!-- _paginate: true -->` - Enable page numbers
53+
- `<!-- _header: text -->` - Slide header
54+
- `<!-- _footer: text -->` - Slide footer
55+
- `<!-- _backgroundColor: color -->` - Background color
56+
- `![bg](url)` - Background image
57+
- `![bg left](url)` - Split background left
58+
- `![bg right](url)` - Split background right
59+
- `![bg opacity:0.5](url)` - Background with opacity
60+
- `# <!--fit--> Text` - Auto-fit text to slide width
61+
62+
## Best Practices
63+
64+
- Keep slides concise with key points only
65+
- Use consistent heading hierarchy
66+
- Leverage background images for visual impact
67+
- Test slides with Marp CLI before presenting
68+
- Use semantic HTML when needed for complex layouts

‎.github/copilot-instructions.md‎

Lines changed: 28 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,29 @@
11
- All slides must be written in Markdown format and use the [Marp](https://marp.app/) framework.
2-
- frontmatter Each slide deck must include the following frontmatter:
3-
```yaml
4-
---
5-
marp: true
6-
theme: custom-default
7-
---
8-
```
9-
- speaker notes - Use HTML comments (`<!-- -->`) for speaker notes.
10-
- Mermaid diagrams - Include the necessary `<script>` tag for Mermaid.js when diagrams are used.
11-
- Slide decks should be stored in the `slides` directory.
12-
- Custom themes or assets should be stored in appropriate subdirectories under `slides`.
13-
- Follow Marp best practices for layout and styling.
14-
- Ensure compatibility with Marp CLI for PDF and presentation generation.
2+
- Each slide deck must include the following frontmatter:
3+
```yaml
4+
---
5+
marp: true
6+
theme: custom-default
7+
paginate: true
8+
math: mathjax
9+
---
10+
```
11+
- Use HTML comments (`<!-- -->`) for speaker notes.
12+
- Use local directives for slide-specific settings:
13+
- `<!-- _class: lead -->` for title slides
14+
- `<!-- _class: invert -->` for dark slides
15+
- `<!-- _class: columns -->` for two-column layout
16+
- `<!-- _class: small -->` for dense content
17+
- `<!-- _paginate: skip -->` to hide page number
18+
- Include the Mermaid script tag when using diagrams:
19+
```html
20+
<script type="module">
21+
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
22+
mermaid.initialize({ startOnLoad: true });
23+
</script>
24+
```
25+
- Store slide decks in the `slides/` directory.
26+
- Store custom themes in `slides/themes/`.
27+
- Store images in `slides/img/`.
28+
- Use CSS variables for theme customization (see `slides/themes/custom-default.css`).
29+
- Ensure compatibility with Marp CLI v4 for PDF and presentation generation.

‎.github/workflows/marp-pages.yml‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,23 +25,36 @@ jobs:
2525
build:
2626
runs-on: ubuntu-latest
2727
steps:
28-
- uses: actions/checkout@v5
29-
- name: Copy images
30-
run: mkdir build && cp -R slides/img build/img && cp -R slides/themes build/themes
28+
- uses: actions/checkout@v6
29+
30+
- name: Setup build directory
31+
run: |
32+
mkdir -p build
33+
cp -R slides/img build/img 2>/dev/null || true
34+
cp -R slides/themes build/themes
3135
32-
- name: Marp Build (README)
36+
- name: Marp Build (HTML)
3337
uses: docker://marpteam/marp-cli:latest
3438
with:
3539
args: --theme-set slides/themes -o build/index.html --html -- slides/Slides.md
3640
env:
3741
MARP_USER: root:root
42+
43+
- name: Marp Build (PDF)
44+
uses: docker://marpteam/marp-cli:latest
45+
with:
46+
args: --theme-set slides/themes -o build/Slides.pdf --html --allow-local-files -- slides/Slides.md
47+
env:
48+
MARP_USER: root:root
49+
3850
- name: Setup Pages
3951
uses: actions/configure-pages@v5
52+
4053
- name: Upload artifact
4154
uses: actions/upload-pages-artifact@v4
4255
with:
43-
# Upload entire repository
4456
path: 'build'
57+
4558
- name: Deploy to GitHub Pages
4659
id: deployment
4760
uses: actions/deploy-pages@v4

‎.vscode/settings.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"markdown.marp.diagnostics.slideContentOverflow": true,
3+
"markdown.marp.html": "all",
4+
"markdown.marp.themes": [
5+
"./slides/themes/custom-default.css"
6+
]
7+
}

‎README.md‎

Lines changed: 106 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@
44

55
Create a Marp presentation site that can be built and published on [GitHub Pages] using this minimal template. The site features:
66

7-
- Marp integration
7+
- Marp integration with CSS variable-based theming
88
- A GitHub Pages / Actions workflow for build and publish ([See a preview](http://chris-ayers.com/marp-slides-template/))
99
- A DevContainer/CodeSpace configuration with Marp and Markdown preview extensions
10-
- Chrome installation for PDF and PowerPoint slide creation on Linux
10+
- Support for PDF and PowerPoint export via Marp CLI v4
1111

1212
## Customization
1313

@@ -22,22 +22,99 @@ Feel free to customize the sites created with this template as you like!
2222

2323
This template includes four custom themes in the `slides/themes` folder:
2424

25-
- custom
26-
- custom-default (based on the built-in default theme)
27-
- custom-gaia (based on the built-in gaia theme)
28-
- custom-uncover (based on the built-in uncover theme)
25+
- **custom** - A minimal base theme
26+
- **custom-default** - Based on the built-in default theme (recommended)
27+
- **custom-gaia** - Based on the built-in gaia theme
28+
- **custom-uncover** - Based on the built-in uncover theme
2929

30-
To use a custom theme, edit the relevant css file and add its reference in the front matter of `Slides.md`. For example, to use `custom-default` add the following to the `Slides.md` front matter:
30+
### Theme Customization with CSS Variables
31+
32+
All themes support CSS variable customization (Marp v4+ best practice):
33+
34+
```css
35+
:root {
36+
--color-background: #ffffff;
37+
--color-foreground: #333333;
38+
--color-highlight: #0366d6;
39+
--color-dimmed: #6a737d;
40+
}
41+
```
42+
43+
### Available Theme Classes
44+
45+
| Class | Description |
46+
|-------|-------------|
47+
| `lead` | Centered title slide layout |
48+
| `invert` | Dark theme for emphasis slides |
49+
| `columns` | Two-column grid layout |
50+
| `columns3` | Three-column grid layout |
51+
| `small` | Smaller text for dense content |
52+
53+
Use with `<!-- _class: classname -->` directive, or combine: `<!-- _class: lead invert -->`
54+
55+
### Using a Theme
56+
57+
Add the theme reference in the frontmatter of your slide deck:
3158

3259
```markdown
3360
---
3461
marp: true
3562
theme: custom-default
63+
paginate: true
64+
math: mathjax
3665
---
3766
```
3867

3968
For additional themes, add them to the devcontainer and follow the [Marp custom theme documentation](https://marpit.marp.app/theme-css).
4069

70+
## Marp Directives Quick Reference
71+
72+
| Directive | Description |
73+
|-----------|-------------|
74+
| `paginate: true` | Enable page numbers (frontmatter) |
75+
| `math: mathjax` | Enable math equations (frontmatter) |
76+
| `<!-- _paginate: skip -->` | Skip pagination on current slide |
77+
| `<!-- _class: lead -->` | Centered title slide |
78+
| `<!-- _class: invert -->` | Dark theme slide |
79+
| `![bg](url)` | Full background image |
80+
| `![bg left](url)` | Split background (left) |
81+
| `![bg right](url)` | Split background (right) |
82+
| `![bg opacity:0.3](url)` | Background with opacity |
83+
| `# <!--fit--> Text` | Auto-fit text to slide width |
84+
85+
## Math Equations
86+
87+
Enable with `math: mathjax` in frontmatter:
88+
89+
```markdown
90+
Inline: $E = mc^2$
91+
92+
Block:
93+
$$
94+
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
95+
$$
96+
```
97+
98+
## Mermaid Diagrams
99+
100+
Include this script tag once per slide deck to enable Mermaid diagrams:
101+
102+
```html
103+
<script type="module">
104+
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
105+
mermaid.initialize({ startOnLoad: true });
106+
</script>
107+
```
108+
109+
Then use Mermaid syntax in a div:
110+
111+
```html
112+
<div class="mermaid">
113+
flowchart LR
114+
A[Start] --> B[End]
115+
</div>
116+
```
117+
41118
## Publishing on GitHub Pages
42119

43120
1. In your GitHub repo, navigate to `Settings` > `Pages` > `Build and deployment`.
@@ -50,18 +127,32 @@ For additional themes, add them to the devcontainer and follow the [Marp custom
50127
2. Install the [Marp for VS Code extension](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode).
51128
3. Open `slides/Slides.md` in VS Code.
52129

130+
### CLI Export (Optional)
131+
132+
Install Marp CLI for PDF/PPTX export:
133+
134+
```bash
135+
npm install -g @marp-team/marp-cli
136+
137+
# Export to PDF
138+
marp --theme-set slides/themes --pdf slides/Slides.md
139+
140+
# Export to PPTX
141+
marp --theme-set slides/themes --pptx slides/Slides.md
142+
```
143+
144+
> **Note:** Marp CLI v4 requires Node.js 18+ and supports both Chrome and Firefox for rendering.
145+
53146
## Licensing and Attribution
54147

55148
This repository is licensed under the [MIT License]. Reuse or extend the code as you wish, but include the original license. The deployment GitHub Actions workflow is based on GitHub's starter workflows.
56149

57150
## Resources
58151

59152
- [Use this template](https://github.com/codebytes/marp-slides-template/generate)
60-
61-
- GitHub Pages: [https://docs.github.com/en/pages](https://docs.github.com/en/pages)
62-
63-
- CommonMark markdown syntax: [https://commonmark.org/help/](https://commonmark.org/help/)
64-
65-
- Marp Official Repository: [https://github.com/marp-team/marp](https://github.com/marp-team/marp)
66-
- Marp Official Documentation: [https://marpit.marp.app/markdown](https://marpit.marp.app/markdown)
67-
- Marp for VS Code Documentation: [https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode)
153+
- [GitHub Pages Documentation](https://docs.github.com/en/pages)
154+
- [CommonMark Markdown Syntax](https://commonmark.org/help/)
155+
- [Marp Official Repository](https://github.com/marp-team/marp)
156+
- [Marpit Framework Documentation](https://marpit.marp.app/markdown)
157+
- [Marp CLI v4 Documentation](https://github.com/marp-team/marp-cli)
158+
- [Marp for VS Code](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode)

0 commit comments

Comments
 (0)