https://github.com/melissavanbussel/theme-generator
A Quarto revealjs theme generator
https://github.com/melissavanbussel/theme-generator
Last synced: about 2 months ago
JSON representation
A Quarto revealjs theme generator
- Host: GitHub
- URL: https://github.com/melissavanbussel/theme-generator
- Owner: melissavanbussel
- Created: 2024-06-16T20:28:42.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-08-05T22:46:51.000Z (8 months ago)
- Last Synced: 2024-08-06T14:27:54.387Z (8 months ago)
- Language: R
- Size: 2.26 MB
- Stars: 3
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- jimsghstars - melissavanbussel/theme-generator - A Quarto revealjs theme generator (R)
README
# Generative AI Quarto revealjs theme generator
This Shiny app takes a user-inputted phrase (e.g., "Abstract purple minimal") and generates a Quarto revealjs theme.
## How it works
The app uses the user-inputted phrase and asks ChatGPT to choose a relevant colour scheme and font. There's also an option to generate slide background images, if the app is run locally.
The app then generates all necessary files:
* `slides.qmd`
* `custom.scss`
* All generated slide background images, if applicable
* `.gitignore`
* `_quarto.yml`
* A project `README.md` with usage and modification instructions
* A configuration file for GitHub Actions and GitHub Pages -- just follow the steps below, push the repo, and the slides will be hosted automatically on GitHub Pages and automatically updated any time a commit is made.
## How to use this app
**You can watch the video instructions here:** [https://youtu.be/WWbuV43cV9Q](https://youtu.be/WWbuV43cV9Q). If you prefer text-based instructions, please follow the steps below. :)
**Pre-requisites:** You will need R and RStudio installed (or if not RStudio, another means of creating `.Rproj` files). To be able to push to GitHub Pages, you will need Git installed, and you will need to have a GitHub account.
There are two ways to use the Shiny app to generate the files. Option A is to run it from shinyapps.io ([https://melissavanbussel.shinyapps.io/quarto_theme_generator/](https://melissavanbussel.shinyapps.io/quarto_theme_generator/)), and Option B is to run it locally.
**Note:** In order to generate images for the slide backgrounds, Option B must be selected (this is because generating the images takes several minutes, and the app will timeout in the browser mid-way through generating the images).
#### Option A: Running the app from shinyapps.io
* Navigate to [https://melissavanbussel.shinyapps.io/quarto_theme_generator/](https://melissavanbussel.shinyapps.io/quarto_theme_generator/).
#### Option B: Running the app locally
* Download [this](https://github.com/melissavanbussel/theme-generator) repository.
* Ensure all the packages listed at the top of the `ui.R` and `server.R` files are installed (use `install.packages` if not). Note that the project uses `renv`, so packages will be installed at the project-level.
* Run the Shiny app (e.g., open `server.R` in RStudio and click the "Run App" button).
### Step 1: Generating the files
* Enter a phrase for the theme you would like to generate (e.g., "Abstract purple minimal").
* Enter your OpenAI API key (see [this page](https://openai.com/index/openai-api/) to obtain one).
* If you would like to generate images for the slide backgrounds, ensure that the "Generate images in addition to CSS?" checkbox is checked. Otherwise, leave it unchecked. (Note: images can only be generated if running the app locally instead of on shinyapps.io).
* Click on the "Generate my theme" button.
* Notice that the purple text at the top right of the app will initially say "Theme has not yet been generated, so there are no files to download."
* Once the files have finished generating, the purple text will change to "Theme generated successfully! You may now use the download button.".
* You may now click the "Download all files" button and save the ZIP folder on your computer.
### Step 2: Pushing to GitHub Pages
* Unzip the zip folder that was created.
* In RStudio, use `New project > Existing directory` to create an R project. When asked to select a folder, select the folder that contains `slides.qmd` and the other generated files.
* Run `renv::init()`. This is necessary to create the `renv.lock` file that GitHub Pages will use to install the required R packages for the project.
* Push the folder to GitHub. There are many ways to do this, but the steps I usually take are: Create a new (public, not private) repository on GitHub and leave the default configuration options (i.e., do not create a `README.md` or `.gitignore`), then use Git Bash to push the folder to that repository on GitHub.
* On GitHub, add a `gh-pages` branch and ensure that `gh-pages` is selected under `Settings > Pages > Deploy from a branch`.
* A few minutes later, you should be able to view the slides by going to `Actions` and clicking on `pages build and deployment`, followed by clicking on the link that is shown under the `deploy` workflow run.
### Step 3: Modifying the slide content
* Edit the `slides.qmd` file to add your content.
* Customize the `custom.scss` file to change style elements in the theme.
* If any new R packages are used in the project, they must be tracked using `renv` (otherwise the slides will not work properly on GitHub Pages). If you have added new packages to the project, run `renv::snapshot()` to update the `renv.lock` file. To check if the `renv.lock` file is currently up-to-date and has all of the necessary information, you can run `renv::status()`.
**Please note:** The filename of `slides.qmd` must **not** be changed, unless the `.github/workflows/publish.yml` file is also changed accordingly. I recommend leaving the file named as `slides.qmd` unless you have a lot of experience with GitHub Actions and feel comfortable troubleshooting.
### Step 4 (optional): Rendering the slides locally
Please note that the slides never need to be rendered locally in order for them to work properly on GitHub Pages. If you would like to render them locally, though, the following step is necessary:
* When rendering locally, make a copy of all images in the `images` folder and put them into `slides_files/libs/revealjs/dist/theme`.
## Credits
This app was developed by Melissa Van Bussel, with assistance from OpenAI's GPT-4o model.
Knowledge on how to modify `custom.scss` files was gained through reading [Emil Hvitfeldt's Slidecraft 101 blog series](https://emilhvitfeldt.com/blog.html#category=slidecraft%20101).
## Troubleshooting common errors
* This app *probably* doesn't work with the free trial version of the OpenAI API.
* If the `_quarto.yml` file gets corrupted, try either running the app again OR just delete the corrupted `_quarto.yml` and create a new `_quarto.yml` file with the contents below:
```
project:
title: Put Whatever Title You Want
```
Unfortunately, I'm not sure why that file occasionally gets corrupted (can't figure out how to reproduce the problem consistently 😢), or why it's only that file, or why it's only some of the time. If you figure that out, please let me know!