Reveal.js Template

This project is a boilerplate for creating Reveal.js presentations. It supports deployment to both GitLab Pages and GitHub Pages, and uses Bun for development.

Features

• Bun Integration: Faster dependency management and execution.
• RevealJS Microservice: Integrated with a lightweight Go-based microservice for serving presentations.
• CI/CD: Automatic deployment to GitLab Pages or GitHub Pages (supporting versioned docs and MR previews).
• Setup Scripts: Automates GitLab or GitHub Pages configuration via their respective APIs.

Local Development

1. Prerequisites

• Bun installed locally.
• A GitLab or GitHub account.

2. Installation

If you've cloned this repository manually, install the dependencies:

# Install dependencies
bun install

Alternatively, use bun create

You can bootstrap a new project directly from the remote Git repository:

bun create cmcrobotics/reveal-template my-presentation
cd my-presentation

Using a local copy as a template

If you have a local clone of this template and want to use it to create a new project:

bun create ./path/to/reveal-template my-presentation

Making the template globally available

To make this template available as a global shorthand (e.g., bun create reveal-template my-presentation), you can symlink it into Bun's template directory:

mkdir -p ~/.bun-create
ln -s $(pwd) ~/.bun-create/reveal-template

Now you can create a new presentation from anywhere using:

bun create reveal-template my-presentation

3. (optional) Setup the RevealJS Microservice

This project can use the revealjs-microservice to serve and manage the presentation assets. Run the initialization script to download the binary:

chmod +x init.sh
./init.sh

The init.sh script downloads the static binary from the GitHub repository (bcopy/revealjs-microservice). This microservice simplifies the way Reveal.js assets are served and is designed for static environments like GitLab Pages.

4. Running Locally

To start the development server:

bun start

This will:

• Build the project (copy Reveal.js assets to the resources directory).
• Start a local server (using live-server) to serve the resources folder.

Deployment to Pages

This template supports deployment to both GitLab Pages and GitHub Pages.

GitLab Pages Setup

To correctly configure GitLab Pages settings, you can use the provided bin/setup-gitlab-pages.js script.

Using the setup script

1. Generate a Personal Access Token in GitLab with the api scope.

2. (Optional) Create a .env file in the project root:

   GITLAB_TOKEN=your_token_here

3. (Optional) Set your Project ID in package.json under the gitlab_project_id field and your Gitlab Pages domain under the domain field.

4. Run the script:

   bun bin/setup-gitlab-pages.js

   Note: If you don't provide the token or Project ID in advance, the script will prompt you for them.

5. Follow the prompts to:

   • Enable "Use Unique Domain".
   • (Optional) Add a custom domain.

This script ensures that your pages are served from a unique subdomain and that no primary domain is strictly enforced, making it easier to manage multiple environments (Production, Develop, MR previews).

GitLab CI/CD

The template includes a .gitlab-ci.yml that handles deployments:

• Main/Master branch: Deploys to the root of your GitLab Pages URL.
• Tags: Deploys to a versioned path (e.g., /v1.0.0/).
• Develop branch: Deploys to /develop/.
• Merge Requests: Can be manually deployed to /mr-<id>/ for previewing changes.

All deployments use the oven/bun Docker image for the build process.

GitHub Pages Setup

To correctly configure GitHub Pages settings, you can use the provided bin/setup-github-pages.js script.

Using the setup script

1. Generate a Personal Access Token in GitHub with the repo scope. Save it as an environment variable (e.g., GITHUB_TOKEN) or be ready to enter it when prompted.

2. (Optional) Set your GitHub repository owner (github_repo_owner) and repository name (github_repo_name) in package.json.

3. Run the script:

   bun bin/setup-github-pages.js

   Note: If you don't provide the token or repository information in advance, the script will attempt to infer them or prompt you for them.

4. Follow the prompts to:

   • (Optional) Add a custom domain.

This script helps configure your GitHub Pages repository settings, including the custom domain.

GitHub Actions CI/CD

The template includes a .github/workflows/pages.yml that handles deployments:

• Main/Master branch: Deploys to the root of your GitHub Pages URL (e.g., yourusername.github.io/yourrepo/ or yourusername.github.io/).
• Tags: Deploys to a versioned path (e.g., /tags/v1.0.0/).
• Develop branch: Deploys to /develop/.
• Pull Requests: Deploys to /pull-requests/<id>/ for previewing changes.

All deployments use ubuntu-latest and oven-sh/setup-bun@v1 for the build process.

Customizing Your Presentation

The template includes a .gitlab-ci.yml that handles deployments:

• Main/Master branch: Deploys to the root of your GitLab Pages URL.
• Tags: Deploys to a versioned path (e.g., /v1.0.0/).
• Develop branch: Deploys to /develop/.
• Merge Requests: Can be manually deployed to /mr-<id>/ for previewing changes.

All deployments use the oven/bun Docker image for the build process.

Customizing Your Presentation

• Edit your slides in the resources directory.
• Update package.json with your project name and details.
• Modify the build script in package.json if you change your asset structure.

Setting this project as a GitLab Group Template (Optional)

If you are using GitLab, you can allow your colleagues to use this project as a template when creating new projects in your GitLab group:

1. Push this project to a repository in your GitLab group.
2. Go to your Group Settings -> General.
3. Expand the Templates section.
4. Select this project in the Templates project dropdown.
5. Click Save changes.

Now, when any member of the group creates a new project, they can choose Create from template and select your project from the Group tab.