Edit me

PMD’s documentation uses Jekyll with the I’d rather be writing Jekyll Theme.

Here are some quick tips.

Format

The pages are in general in Github Flavored Markdown.

Structure

All documentation is stored in the folder docs/. This is the folder, that github and the travis-ci scripts use to render the site.

New pages are stored in the different subfolders under pages. The folder structure resembles the sidebar structure. Since all pages use a simple permalink, in the rendered html pages, all pages are flattened in one directory. This makes it easy to view the documentation also offline.

Building

There are two ways, to execute jekyll:

  1. Using bundler. This will install all the needed ruby packages locally and execute jekyll:

    # this is required only once, to download and install the dependencies
    bundle install
    # this builds the documentation under _site
    bundle exec jekyll build
    # this runs a local webserver as http://localhost:4005
    bundle exec jekyll serve
    
  2. Using docker. This will create a local docker image, into which all needed ruby packages and jekyll is installed.

    # this is required only once to create a local docker image named "pmd-doc"
    docker build --no-cache -t pmd-doc .
    # this builds the documentation under _site
    docker run --rm=true -v "$PWD:/src" pmd-doc build -H 0.0.0.0
    # this runs a local webserver as http://localhost:4005
    docker run --rm=true -v "$PWD:/src" -p 4005:4005 pmd-doc serve -H 0.0.0.0
    

The built site is stored locally in the (git ignored) directory _site. You can point your browser to _site/index.html to see the pmd documentation.

Alternatively, you can start the local webserver, that will serve the documentation. Just go to http://localhost:4005. If a page is modified, the documentation will automatically be rendered again and all you need to do, is refreshing the page in your browser.

See also the script pmd-jekyll.sh. It starts the jekyll server in the background and doesn’t block the current shell.

The sidebar

The sidebar is stored as a YAML document under _data/sidebars/pmd_sidebar.yml.

Make sure to add an entry there, whenever you create a new page.

The frontmatter

Each page in jekyll begins with a YAML section at the beginning. This section is separated by 3 dashes (---). Example:

---
title: Writing Documentation
last_update: August 2017
permalink: pmd_devdocs_writing_documentation.html
---

Some Text

# Some header

There are a couple of possible fields. Most important and always required are title and permalink.

By default, a page toc (table of contents) is automatically generated. You can prevent this with “toc: false”.

You can add keywords, that will be used for the on-site search: “keywords: documentation, jekyll, markdown”

It’s useful to maintain a last_update field. This will be added at the bottom of the page.

A summary can also be provided. It will be added in a box before the content.

For a more exhaustive list, see Pages - Frontmatter.

Alerts and Callouts

See Alerts.

For example, a info-box can be created like this:

{% include note.html content="This is a note." %}

It renders as:

Other available types are:

  • note.html
  • tip.html
  • warning.html
  • important.html

A callout is created like this:

{% include callout.html content="This is a callout of type default.<br/><br/>There are the following types available: danger, default, primary, success, info, and warning." type="default" %}

It renders as:

This is a callout of type default.

There are the following types available: danger, default, primary, success, info, and warning.

Code samples with syntax highlighting

This is as easy as:

``` java
public class Foo {
    public void bar() { System.out.println("x"); }
}
```

This looks as follows:

public class Foo {
    public void bar() { System.out.println("x"); }
}