├── .github └── workflows │ └── marp-to-pages.yml ├── .gitignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── docs └── example.md └── img ├── click-actions.png └── use-template.png /.github/workflows/marp-to-pages.yml: -------------------------------------------------------------------------------- 1 | name: marp-to-pages 2 | concurrency: marp-to-pages 3 | 4 | on: 5 | push: 6 | branches: [ main ] 7 | pull_request: 8 | types: 9 | - opened 10 | - reopened 11 | - synchronize 12 | - closed 13 | jobs: 14 | build: 15 | runs-on: ubuntu-latest 16 | permissions: 17 | contents: write 18 | pull-requests: write 19 | steps: 20 | 21 | - name: Checkout code 22 | uses: actions/checkout@v3 23 | 24 | - name: Ensure build dir exists 25 | run: mkdir -p build 26 | 27 | - name: Copy images directory (if exists) 28 | run: if [[ -d img ]]; then cp -R img build/img; fi 29 | 30 | - name: Marp Build (README) 31 | uses: docker://marpteam/marp-cli:v3.0.2 32 | with: 33 | args: README.md -o build/index.html 34 | env: 35 | MARP_USER: root:root 36 | 37 | - name: Marp Build (README.pdf) 38 | uses: docker://marpteam/marp-cli:v3.0.2 39 | with: 40 | args: README.md --allow-local-files -o build/README.pdf 41 | env: 42 | MARP_USER: root:root 43 | 44 | - name: Marp Build (README.pptx) 45 | uses: docker://marpteam/marp-cli:v3.0.2 46 | with: 47 | args: README.md --allow-local-files -o build/README.pptx 48 | env: 49 | MARP_USER: root:root 50 | 51 | - name: Check if docs folder exists 52 | id: docs-folder-exists 53 | run: bash -c "[[ -d docs ]] ; echo \"has_docs=\$?\" >> \"$GITHUB_OUTPUT\"" 54 | 55 | - name: Marp Build (docs folder, if exists) 56 | if: steps.docs-folder-exists.outputs.has_docs == '0' 57 | uses: docker://marpteam/marp-cli:v3.0.2 58 | with: 59 | args: -I docs/ -o build/docs/ 60 | env: 61 | MARP_USER: root:root 62 | 63 | - name: Deploy preview 64 | if: ${{ github.event_name == 'pull_request' }} 65 | uses: rossjrw/pr-preview-action@v1 66 | with: 67 | source-dir: ./build/ 68 | preview-branch: gh-pages 69 | umbrella-dir: pr-preview 70 | 71 | - name: Deploy production 72 | if: ${{ github.event_name == 'push' }} 73 | uses: JamesIves/github-pages-deploy-action@v4 74 | with: 75 | branch: gh-pages 76 | folder: ./build/ 77 | clean-exclude: pr-preview/ 78 | 79 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | act 2 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## June 2023 4 | 5 | Fixed: 6 | * [#12](https://github.com/ralexander-phi/marp-to-pages/issues/12): Request write permission to content to avoid needing extra repo settings 7 | * [#13](https://github.com/ralexander-phi/marp-to-pages/issues/13): Ignore missing `img` and `docs` directories 8 | 9 | Updated: 10 | * marp-cli version to [3.0.2](https://github.com/marp-team/marp-cli/releases/tag/v3.0.2) (consider changing this to latest, if you'd like) 11 | * [actions/checkout](https://github.com/actions/checkout) version to v3 12 | 13 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 Robert Alexander 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 8 | 9 | 14 | 15 | # Deploy Marp to GitHub Pages 16 | 17 | Presentations to Webpages: Instantly! 18 | 19 | ## What? 20 | 21 | [Marp](https://marp.app/) lets you create HTML slides from markdown (like this!). 22 | 23 | This presentation is both a [website](https://alexsci.com/marp-to-pages) and a [README.md](https://github.com/ralexander-phi/marp-to-pages/blob/main/README.md). 24 | 25 | ## Why? 26 | 27 | Treat your presentation the same way you treat code. 28 | 29 | - Use git to track changes 30 | - Pull requests to collaborate 31 | - Deploy automatically 32 | - See a problem? Open an issue! 33 | 34 | ## Setup 35 | 36 | Want to create your own? 37 | 38 | First, create a new repo [from the template repo](https://github.com/ralexander-phi/marp-to-pages). 39 | 40 | ![](img/use-template.png) 41 | 42 | ## Configure GitHub Pages 43 | 44 | Open your new repo and [setup publishing](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source). 45 | 46 | You'll typically use `gh-pages` as the deploy branch. 47 | 48 | ## Review Build 49 | 50 | Click on Actions tab and see if the build succeeded (it may take some time). 51 | 52 | ![](img/click-actions.png) 53 | 54 | You should now see the generated files in the `gh-pages` branch. 55 | 56 | ## View webpage 57 | 58 | Open your deployed webpage to see the content. 59 | 60 | Out of the box you should see `README.md` as `/index.html` and `/README.pdf`. Slides under `docs/` are also converted. 61 | 62 | ## Running locally 63 | 64 | Locally you'll run commands like: 65 | 66 | ``` 67 | $ marp README.md -o build/README.pdf 68 | ``` 69 | 70 | or 71 | 72 | ``` 73 | $ npx @marp-team/marp-cli@latest README.md -o build/README.pdf 74 | ``` 75 | 76 | ## As a workflow step 77 | 78 | The workflow runs an equivalent step: 79 | 80 | ``` 81 | - name: Marp Build (README.pdf) 82 | uses: docker://marpteam/marp-cli:v1.7.0 83 | with: 84 | args: README.md -o build/README.pdf 85 | env: 86 | MARP_USER: root:root 87 | ``` 88 | 89 | Note the `args` match the previous slide. 90 | 91 | ## Customizing the build 92 | 93 | Anything in the `build/` folder will be deployed to GitHub Pages. 94 | 95 | You can copy extra files or run further processing steps using other tools. 96 | 97 | ## Learn more about Marp 98 | 99 | This is a good time to learn more about Marp. Here's some resources: 100 | 101 | - [CommonMark](https://commonmark.org/) 102 | - [Cheat Sheet](https://commonmark.org/help/) 103 | - [Themes](https://github.com/marp-team/marp-core/tree/master/themes) 104 | - [CSS Themes](https://marpit.marp.app/theme-css) 105 | - [Directives](https://marpit.marp.app/directives) 106 | - [VS Code plugin](https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode) 107 | 108 | ## Example Sites 109 | 110 | Known sites using this action are: 111 | 112 | - [University of Illinois at Urbana-Champaign's CS 199 Even More Practice](https://cs199emp.netlify.app/) [(code)](https://github.com/harsh183/emp-125) 113 | - [Exploring agent based models](https://roiarthurb.github.io/Talk-UMMISCO_06-07-2020/) [(code)](https://github.com/RoiArthurB/Talk-UMMISCO_06-07-2020) 114 | 115 | Send a [pull request](https://github.com/ralexander-phi/marp-to-pages) to get your site added. 116 | 117 | ## Publish your slides 118 | 119 | When you are ready to share your presentation, commit or merge to `main` and your content on GitHub Pages will automatically update. 120 | 121 | # 🎉 122 | 127 | ### Hooray! 128 | 129 | 130 | -------------------------------------------------------------------------------- /docs/example.md: -------------------------------------------------------------------------------- 1 | Title 2 | ===== 3 | 4 | --- 5 | 6 | ## Slide One 7 | 8 | * Apple 9 | * Banana 10 | * Carrot 11 | 12 | --- 13 | 14 | ## Slide Two 15 | 16 | - Dog 17 | - Cat 18 | - Frog 19 | 20 | -------------------------------------------------------------------------------- /img/click-actions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/robalexdev/marp-to-pages/97ea61e12db9b90622680cd8d7a64dcfb9a1a2d7/img/click-actions.png -------------------------------------------------------------------------------- /img/use-template.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/robalexdev/marp-to-pages/97ea61e12db9b90622680cd8d7a64dcfb9a1a2d7/img/use-template.png --------------------------------------------------------------------------------