Updating the PDFBox Website

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.

Project Info

The site is based on Jekyll. So you have to be familiar with the Markdown template language and have Jekyll (ver. 2+) installed to contribute to the project.

Contribute

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.

Development

Install Jekyll

Follow the instructions available on the Jekyll website.

Checkout from the Git Repository

Before you can edit the site, you need to check it out from the Git repository:

git clone https://git-wip-us.apache.org/repos/asf/pdfbox-docs

Local Changes

You can now do the changes and additions to the sources of the PDFBox website. To test these locally use

jekyll serve

which will compile the changes and run a local webserver at

http://localhost:4000

Publish the Website (For Comitters Only)

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

<server>
  <id>pdfbox-site</id>
  <username>** USERNAME **</username>
  <password>** PASSWORD **</password>
</server>

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

jekyll build

This will read the sources and generate the new content in the ./staging directory.

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

mvn scm-publish:publish-scm

This will checkout the current content into the ./targetdirectory, apply the changes from ./staging and publish the changes to the PDFBox production website.

Update the JavaDocs for PDFBox 2.x

To publish the javadocs follow these steps:

Run

$ mvn clean javadoc:aggregate scm-publish:publish-scm

from the <SVN_ROOT>/../pdfbox directory.

It uses the same pdfbox-site settings from above to connect to the repository.

As mvn clean will delete the javadoc files download from the Apache CMS it's advised to configure ${svn.scmJavadocCheckoutDirectory} to a local directory not below ./target.