https://github.com/microprofile/microprofile-tutorial-ui
The UI for MicroProfile Tutorial
https://github.com/microprofile/microprofile-tutorial-ui
Last synced: 6 months ago
JSON representation
The UI for MicroProfile Tutorial
- Host: GitHub
- URL: https://github.com/microprofile/microprofile-tutorial-ui
- Owner: microprofile
- License: apache-2.0
- Created: 2025-04-08T19:05:22.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-17T21:19:54.000Z (about 1 year ago)
- Last Synced: 2025-06-17T22:27:25.694Z (about 1 year ago)
- Language: CSS
- Size: 440 KB
- Stars: 0
- Watchers: 26
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= MicroProfile Documentation UI
// External URLs:
:url-antora-ui-default: https://gitlab.com/antora/antora-ui-default
:url-git: https://git-scm.com
:url-git-dl: {url-git}/downloads
:url-gulp: http://gulpjs.com
:url-opendevise: https://opendevise.com
:url-nodejs: https://nodejs.org
:url-nvm: https://github.com/nvm-sh/nvm
:url-nvm-install: {url-nvm}#installing-and-updating
:url-microprofile-tutorial-ui: https://github.com/microprofile/microprofile-tutorial-ui
:url-microprofile-tutorial-ui-actions: {url-microprofile-tutorial-ui}/actions
:url-microprofile-tutorial-ui-release: {url-microprofile-tutorial-ui}/releases/tag/latest
:url-microprofile-tutorial: https://github.com/microprofile/microprofile-tutorial
:url-microprofile-tutorial-live: https://microprofile.github.io/microprofile-tutorial/
This project is forked from {url-antora-ui-default}[Antora Default UI] as per their instructions.
== Prerequisites
To build this project and preview it locally, you need the following software on your computer:
* {url-git}[git] (command: `git`)
* {url-nodejs}[Node.js] (commands: `node` and `npm`)
* {url-gulp}[Gulp CLI] (command: `gulp`)
=== git
First, make sure you have Git installed.
$ git --version
If not, {url-git-dl}[download and install] the Git package for your system.
=== Node.js
Next, make sure that you have Node.js installed (which also provides `npm`).
$ node --version
If this command fails with an error, you don't have Node.js installed.
While you can install Node.js from the official packages, we strongly recommend that you use {url-nvm}[nvm] (Node Version Manager) to manage your Node.js installation(s).
Follow the {url-nvm-install}[nvm installation instructions] to set up nvm on your machine.
Once you've installed nvm, open a new terminal and `cd` into the project folder and install Node.js using the following command:
$ nvm install
This will basically install the Node.js version defined in the `.nvmrc` file of this project.
=== Gulp CLI
You'll need the Gulp command-line interface (CLI) to run the build.
The Gulp CLI package provides the `gulp` command.
You can install the Gulp CLI globally using the following command:
$ npm install -g gulp-cli
Verify the Gulp CLI is installed by running:
$ gulp --version
Now that you have the prerequisites installed, you can build the project.
== Build the project
Use `npm` to install the project's dependencies inside the project.
In your terminal, `cd` into the project folder and execute the following command:
$ npm install
This command installs the dependencies listed in [.path]_package.json_ into the [.path]_node_modules/_ folder inside the project.
This folder does not get included in the UI bundle and should _not_ be committed to the source control repository.
== Preview the UI
The files in the [.path]_preview-src/_ folder provide the sample content that allow you to see the UI in action.
In this folder, you'll primarily find pages written in AsciiDoc.
These pages provide a representative sample and kitchen sink of content from the real site.
To build the UI and preview it in a local web server, run the `preview` command:
$ gulp preview
You'll see a URL listed in the output of this command:
....
[12:00:00] Starting server...
[12:00:00] Server started http://localhost:5252
[12:00:00] Running server
....
Navigate to this URL to preview the site locally.
While this command is running, any changes you make to the source files will be instantly reflected in the browser.
This works by monitoring the project for changes, running the `preview:build` task if a change is detected, and sending the updates to the browser.
Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
== Package the UI
If you need to package the UI so you can use it to generate the documentation site locally, run the following command:
$ gulp bundle
If any errors are reported by lint, you'll need to fix them.
When the command completes successfully, the UI bundle will be available at [.path]_build/ui-bundle.zip_.
You can if necessary point Antora at this bundle using the `--ui-bundle-url` command-line option.
Or in `local-antora-playbook.yml` for Antora Author Mode, set the `ui.bundle.url` property to `../microprofile-tutorial-ui/build/ui-bundle.zip`.
== Deploy the project
This is already done automatically by {url-microprofile-tutorial-ui-actions}[Github Actions].
It will generate an UI bundle tagged `latest` which is available as {url-microprofile-tutorial-ui-release}[Latest UI bundle].
This bundle is in turn already referenced as `ui.bundle.url` property in `antora-playbook.yml` configuration file of {url-microprofile-tutorial}[MicroProfile Tutorial Playbook].
The live site can be found at {url-microprofile-tutorial-live}[{url-microprofile-tutorial-live}].
== GitHub Pages Deployment
This project can also be built and deployed directly to GitHub Pages, which allows you to host the UI documentation directly from this repository.
=== Building for GitHub Pages
To build the UI for GitHub Pages locally, run:
$ gulp github-pages
This will generate the complete site in the `public` directory, ready for GitHub Pages deployment.
=== Automatic Deployment
The project includes a GitHub Actions workflow that automatically builds and deploys the site to GitHub Pages whenever changes are pushed to the main branch. The workflow:
1. Checks out the repository
2. Sets up Node.js
3. Installs dependencies
4. Builds the site using the `github-pages` task
5. Deploys the built site to GitHub Pages
To enable GitHub Pages for your fork of this repository:
1. Go to your repository's Settings tab
2. Navigate to Pages in the left sidebar
3. Under "Source", select "GitHub Actions"
Once deployed, your site will be available at `https://[username].github.io/microprofile-tutorial-ui/` or at a custom domain if you configure one in the GitHub Pages settings.
This approach allows you to maintain both the UI bundle for Antora and a standalone documentation site from the same repository.
== Development with Dev Containers / GitHub Codespaces
This project includes Dev Container configuration, making it easy to develop using Visual Studio Code Dev Containers or GitHub Codespaces. The development environment comes pre-configured with:
* Node.js LTS
* Gulp CLI for build automation
* GitHub Actions extension for workflow management
* AsciiDoctor extension for documentation editing
=== Using GitHub Codespaces
To start developing using GitHub Codespaces:
1. Go to your repository on GitHub
2. Click the green "Code" button
3. Select the "Codespaces" tab
4. Click "Create codespace on main"
This will create a cloud-based development environment with all dependencies pre-installed.