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.
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.
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.
Follow the instructions available on the Jekyll website.
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
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
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 is build locally
jekyll build
This will read the sources and generate the new content in the ./staging directory.
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.
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.