Bakery is a Gradle plugin designed to simplify the deployment of static websites generated by JBake directly to GitHub Pages. It uses the JGit library to handle Git operations, allowing for a seamless deployment process from your build environment.
The plugin bundles JBake and all necessary dependencies, eliminating the need for manual JBake installation.
A live demonstration of a static site deployed using this plugin is available here:
Before you begin, ensure you have the following installed:
-
A JDK (Java Development Kit), version 11 or higher.
-
Gradle (or use the Gradle wrapper included in the project).
|
Note
|
You no longer need to install JBake separately. The plugin handles all JBake dependencies automatically. |
If you are starting a new project, you can retrieve the site and maquette template directories from the GitHub repository (https://github.com/cheroliv/bakery-gradle-plugin) or by downloading the zipped version directly from this link: https://github.com/cheroliv/bakery-gradle-plugin/archive/refs/heads/main.zip.
Add these directories to the root directory where the Bakery plugin is used.
Alternatively, you can create your own JBake structure with the following directories:
- site/content/ - Your content files
- site/templates/ - Your template files
- site/assets/ - Static assets (CSS, JS, images)
- site/jbake.properties - JBake configuration
Your static content, templates, and assets will be placed in this site directory, which contains the jbake.properties file used by JBake.
To use the Bakery plugin, you need to configure it in your build.gradle.kts file. The configuration is straightforward and relies on a single YAML file to manage all deployment settings.
In your settings.gradle.kts file, specify that Gradle should search for plugins on the Gradle Plugin Portal.
rootProject.name = "your-project-name"
pluginManagement {
repositories {
gradlePluginPortal()
}
}In your gradle/libs.versions.toml file, add the Bakery plugin with a version and an alias.
Replace "bakery-version" with the current version: "0.0.8"
[versions]
bakery = "bakery-version"
[plugins]
bakery = { id = "com.cheroliv.bakery", version.ref = "bakery" }Now, apply the plugin in your build.gradle.kts using its alias and point it to your YAML configuration file.
plugins {
// Apply the plugin using its alias from the version catalog
alias(libs.plugins.bakery)
}
// Configure the path to your YAML settings file
bakery {
configPath = file("site.yml").absolutePath
}The plugin provides an interactive configuration helper to set up your site.yml file and GitHub credentials:
./gradlew configureSiteThis task will prompt you for: - GitHub username - GitHub Personal Access Token (PAT) - Repository URL - Configuration file path
The credentials will be saved in .github-config (which should be added to .gitignore), and the configuration path will be saved in gradle.properties.
Create a YAML file (e.g., site.yml) at the root of your project. This file centralizes all the necessary information for deployment.
# JBake settings
bake:
# Source directory for JBake content, assets, and templates
srcPath: "site"
# Destination directory for the generated site
destDirPath: "bake"
# (Optional) The domain for the CNAME file. If provided, a CNAME file will be created.
cname: "www.your-domain.com"
# Deployment settings for the main static site
pushPage:
# (Optional) Source directory for the push, relative to the build directory. Defaults to destDirPath.
from: "bake"
# (Optional) Target directory within the cloned repository. Defaults to the root.
to: "cvs"
# Git repository details
repo:
# A local identifier for the repository
name: "my-static-site"
# The URI of your GitHub repository
repository: "https://github.com/YourUsername/YourRepository.git"
# Credentials for authentication
credentials:
username: "YourUsername"
# IMPORTANT: Use an environment variable or secret for the token
password: "${GITHUB_TOKEN:-your_github_pat}"
# The branch to deploy the site to
branch: "gh-pages"
# The commit message for the deployment
message: "Deploying static site"
# Deployment settings for a secondary asset, like a wireframe/maquette
pushMaquette:
# Source directory for the maquette, relative to the project root
from: "maquette"
# (Optional) Target directory within the cloned repository. Defaults to the root.
to: "cvs"
repo:
name: "my-maquette"
repository: "https://github.com/YourUsername/MaquetteRepository.git"
credentials:
username: "YourUsername"
password: "${GITHUB_TOKEN:-your_github_pat}"
branch: "main"
message: "Deploying maquette"IMPORTANT: Do not hardcode your GitHub Personal Access Token (PAT) directly in your configuration file. It is highly recommended to use environment variables or GitHub Secrets to supply the token during the build process, as shown in the example above. This prevents your credentials from being exposed in your source code.
The plugin provides several tasks to manage your static site workflow.
Generate your static site from JBake templates:
./gradlew bakeThis task will process your JBake content and generate the static site in the build/bake directory (or the directory specified in your site.yml).
For local development, the plugin provides a built-in server task:
./gradlew serveThis task will:
1. Build your site
2. Start a local web server
3. Serve your site at http://localhost:8820
|
Note
|
The server will watch for changes and automatically rebuild your site. Press Ctrl+C to stop the server.
|
This is the primary task for deploying your static site generated by JBake. It uses the configuration under the pushPage key in your YAML file.
To execute it, run the following command:
./gradlew publishSiteThis task will:
1. Run JBake to build your static site into the build/bake directory.
2. Create a CNAME file if specified in the configuration.
3. Clone the specified branch from your GitHub repository.
4. Copy the generated site files into the cloned repository.
5. Commit and push the changes to GitHub Pages.
This task allows you to quickly publish a preliminary design or wireframe (a "maquette") before it has been sliced and integrated into JBake templates. It’s perfect for design previews and validation cycles. This task uses the configuration under the pushMaquette key in your YAML file.
A live example of a deployed maquette is available here: https://pages-content.github.io/cheroliv-maquette/
To execute it, run the following command:
./gradlew publishMaquetteThis task will copy the contents of the source directory (e.g., maquette/) and deploy them to the configured repository and branch.
The Bakery plugin provides the following tasks:
| Task | Description |
|---|---|
|
Interactive configuration helper to set up GitHub credentials and |
|
Generate the static site from JBake templates |
|
Build and serve the site locally at |
|
Build and deploy the main static site to GitHub Pages |
|
Deploy a maquette/wireframe to a GitHub repository |
This project includes a GitHub Actions workflow defined in .github/workflows/website.yml to automatically deploy the website whenever changes are pushed to the main branch.
To make this workflow operational, you must configure a repository secret.
The continuous integration process requires a GitHub Secret named BAKERY_DEMO_CONFIG. The content of this secret must be the same as your site.yml configuration file. The workflow uses this secret to generate the site.yml file needed by the publishSite task at runtime.
Follow these steps to create the secret:
-
Navigate to your GitHub repository.
-
Go to Settings > Secrets and variables > Actions.
-
Click on the New repository secret button.
-
For the Name, enter
BAKERY_DEMO_CONFIG. -
For the Secret, copy and paste the entire content of your local
site.ymlfile. -
Click Add secret.
Once the secret is configured, the CI will be able to authenticate and deploy your site automatically.
The plugin includes built-in support for AsciidoctorJ diagrams, including PlantUML. You can use diagram blocks directly in your AsciiDoc content:
[plantuml, diagram-example, png]
....
@startuml
Alice -> Bob: Hello
Bob -> Alice: Hi!
@enduml
....The generated diagrams will be automatically included in your static site.
You can customize JBake behavior by editing the jbake.properties file in your site directory. Common properties include:
-
site.host- Your site’s domain -
render.encoding- Character encoding (default: UTF-8) -
render.tags- Enable tag rendering -
render.sitemap- Generate sitemap.xml
Refer to the JBake documentation for a complete list of configuration options.
If Gradle cannot find the Bakery plugin, ensure that:
1. gradlePluginPortal() is included in your pluginManagement repositories
2. The plugin version in libs.versions.toml is correct
3. You’ve applied the plugin using alias(libs.plugins.bakery) in your build.gradle.kts
If the publishSite task fails:
1. Verify your GitHub credentials in site.yml
2. Ensure your GitHub token has the necessary permissions (repo, workflow)
3. Check that the target repository and branch exist
4. Review the Gradle output for specific error messages