Skip to content

Latest commit

 

History

History
96 lines (61 loc) · 6.48 KB

README.md

File metadata and controls

96 lines (61 loc) · 6.48 KB
Raw

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. 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/), 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

Option B: Running the app locally

  • Download this 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 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.

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!