The content for the PDFBox website is kept in a Git repository which is also mirrored to GitHub. The site is split into two parts: the static content and the Javadoc for the PDFBox API. Both parts are build independently as further described below.
If you would like to enhance the website content you can submit a patch. To do so please open a ticket at our Issue Tracker, use
Documentation for the
Component and add your patch to the ticket.
Tools used to generate the website:
Before you can edit the site, you need to check it out from the Git repository:
git clone https://gitbox.apache.org/repos/asf/pdfbox-docs
To build the website go to the project root directory and run:
$ npm install # needed only once, or if dependencies change $ npm run build # to perform the build
While changing the content the website generation can be done in Preview mode. This will fire up a little webserver and update the browser window when there are changes so these are reflected immediately.
$ npm install # needed only once, or if dependencies change $ npm run preview # to start the preview mode
To validate the generated website document go to the project root directory and run:
$ npm run checks
In order to reuse code from the examples project in the documentation the shortcode
codesnippet can be used.
The shortcode expects two variables
In addition - in order to be able to only put parts of the code into the documentation the following comments can be added to the java code
//DOC-START ... //DOC-END
The DOC-START/DOC-END pair can be placed multiple times into the Java code. Everything between these special comment lines will be added the other content will be omitted. This will allow to skip license header, import statements etc. to concentrate on the important bits.
After you have done the local changes follow these steps to publish the content:
Add the following server configuration in your ~/.m2/settings.xml file
<username>** USERNAME **</username>
<password>** PASSWORD **</password>
pdfbox-site is referenced from the PDFBox pom.xml file.
The password should be encrypted following Maven Password Encryption
Ensure that the new website content can build locally
npm run build
This will read the sources and generate the new content in the
When you are happy with the new content update the source repository
git commit -m "..." git push origin master
Upload the new content to the production site
This will checkout the current content into the
./targetdirectory, apply the changes from
./staging and publish
the changes to the PDFBox production website.
The Javadoc for PDFBox is hosted on javadoc.io which uses the
pdfbox-<version>-javadoc.jar built at release time as a source. javadoc.io also makes older versions of the Javadoc available.
In order to update the documentation to match a latest release of a branch
releasevariable in the matching subdirectories
The project provides a simple way to build the website sources locally using the build tool Maven.
The Maven build automatically downloads the tool binaries such as
npm for you. You do not need to install
those tools on your host then. The binaries are added to the local project sources only and generate the website content.
As the Maven build uses pinned versions of
npm that are tested to build the website you most likely avoid
build errors due to incompatible versions of
node.js tooling installed on your machine.
Make sure that you have Maven installed.
$ mvn --version
If this command fails with an error, you do not have Maven installed.
When building everything from scratch the build executes following steps:
npmbinaries to the local project
You can do all of this with one single command:
$ mvn package
The whole process takes up to five minutes (time to grab some coffee!)
When the build is finished you should see the generated website in the
When rebuilding the website the process uses some cached content.
If you want to start from scratch for some reason you can simply add the
clean operation to the build which removes
all generated sources in the project first.
$ mvn clean package