https://github.com/eclipse-ee4j/jakartaee-firstcup
First Cup of Jakarta EE Tutorial
https://github.com/eclipse-ee4j/jakartaee-firstcup
Last synced: 11 months ago
JSON representation
First Cup of Jakarta EE Tutorial
- Host: GitHub
- URL: https://github.com/eclipse-ee4j/jakartaee-firstcup
- Owner: eclipse-ee4j
- License: epl-2.0
- Created: 2019-01-28T10:22:57.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2021-07-01T16:24:32.000Z (about 5 years ago)
- Last Synced: 2024-05-09T16:46:10.246Z (about 2 years ago)
- Language: CSS
- Homepage: https://eclipse-ee4j.github.io/jakartaee-firstcup
- Size: 259 KB
- Stars: 12
- Watchers: 32
- Forks: 16
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# First Cup Tutorial
This repository contains the source files that are used to build the
_Jakarta Enterprise Edition Your First Cup: An Introduction to Jakarta EE_.
The source files
are authored in [AsciiDoc](http://asciidoc.org/). AsciiDoc is similar
to markdown but is particularly suited for user documentation. This
project also uses [JBake](http://jbake.org/). JBake is a static site
generator that is inspired from Jekyll and written in Java. JBake uses
templates for the structure of the page and the body of the page is
generated from AsciiDoc content.
Note that the First Cup Tutorial code examples are located in a
separate repository
[eclipse-ee4j/jakartaee-firstcup-examples](https://github.com/eclipse-ee4j/jakartaee-firstcup-examples).
## Contributing
The easiest way to contribute is by opening an issue in this project
that contains feedback and review comments.
The First Cup Tutorial project is also open for contributions and your
help is greatly appreciated. If you have an idea for the tutorial and
want to add a section or update an existing section, then review the
following links:
* [Contribute](CONTRIBUTING.md)
* [Pull Request Acceptance Workflow](src/main/jbake/assets/pr_doc_workflow.md)
* [License](LICENSE.md)
## Building the First Cup Tutorial
The following directions explain how to do local builds of the
tutorial. Note that any changes that are pushed to the master branch
automatically trigger a build of the site files and tutorial sources.
The results are automatically pushed to the gh-pages branch. You can
view the published site
[here](https://eclipse-ee4j.github.io/jakartaee-firstcup).
### Pre-Requisites
- Maven
- JDK8+
Note that manually deploying the site requires password-less
authentication. This is done by exporting your SSH public key into your
GitHub account.
### Build the Site Locally
The site is generated under `target/staging`. Open
`file:///PATH_TO_PROJECT_DIR/target/staging` in a browser to view the
output.
```
mvn generate-resources
```
You can also invoke the JBake plugin directly:
```
mvn jbake:build
```
#### Rebuild the Site on Changes
The following command builds the site and, if kept running, detects
changes to the sources and incrementally renders the site. This is
convenient when writing content.
```
mvn jbake:watch
```
#### Serve the Site locally
If a web server is required (for example, absolute paths are used), you
can use the following command to start a Jetty web server at
`http://localhost:8820`. The command also watches for changes and
rebuilds incrementally.
```
mvn jbake:serve
```
### Deploy the Site to Github Pages
If you want to manually push a build to the gh-pages branch, use:
```
mvn deploy -Ppublish-site
```
Never commit changes to the gh-pages branch directly.
### Produce a Zip File for Download
To produce a zip file containing the generated HTML files, use:
```
mvn package
```
When making a release on GitHub, this zip file should be added to the release.
## Links
- [JBake maven plugin documentation](https://github.com/Blazebit/jbake-maven-plugin)
- [JBake documentation](http://jbake.org/docs/2.5.1)
- [Freemarker documentation](http://freemarker.org/docs)
- [AsciiDoc User Guide](http://asciidoc.org/userguide.html)
- [Asciidoctor quick reference](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference)