Skip to content

Markup

Jump to bottom
Ralf Stuckert edited this page Jun 26, 2017 · 15 revisions

Markup

Often you want use just some basic text styling: use a bold font here, some words emphasized with italic there, and that's it. Let's say we want to use different font types for the following sentence:

"Markup supports bold, italic, and even mixed markup."

If you want to do that using the standard API, it would look like this:

Paragraph paragraph = new Paragraph();
paragraph.addText("Markup supports ", 11, PDType1Font.HELVETICA);
paragraph.addText("bold", 11, PDType1Font.HELVETICA_BOLD);
paragraph.addText(", ", 11, PDType1Font.HELVETICA);
paragraph.addText("italic", 11, PDType1Font.HELVETICA_OBLIQUE);
paragraph.addText(", and ", 11, PDType1Font.HELVETICA);
paragraph.addText("even ", 11, PDType1Font.HELVETICA_BOLD);
paragraph.addText("mixed", 11, PDType1Font.HELVETICA_BOLD_OBLIQUE);
paragraph.addText(" markup", 11, PDType1Font.HELVETICA_OBLIQUE);
paragraph.addText(".\n", 11, PDType1Font.HELVETICA);
document.add(paragraph);

That's annoying, isn't it? That's what the markup API is intended for. Use * to mark bold content, and _ for italic. Let's do the same example with markup:

Paragraph paragraph = new Paragraph();
paragraph.addMarkup(
        "Markup supports *bold*, _italic_, and *even _mixed* markup_.\n", 11, 
        PDType1Font.HELVETICA, 
        PDType1Font.HELVETICA_BOLD,
        PDType1Font.HELVETICA_OBLIQUE,
        PDType1Font.HELVETICA_BOLD_OBLIQUE);
document.add(paragraph);

To make things even more easy, you may specify only the font family instead:

paragraph = new Paragraph();
paragraph.addMarkup(
        "Markup supports *bold*, _italic_, and *even _mixed* markup_.\n",
        11, BaseFont.Helvetica);

The low level Text API class TextFlow has the same both methods addText() and addMarkup(), so you can do the same markup with that API too.

If you want to use the asterisk and underscore in markup, you have to escape them with \. Since backlash has a special meaning as the escape character, you have to escape that too. So in order to write the sentence...

"Escape * with \* and _ with \_ in markup."

... you have to use the following markup (backslashes are doubled, since they have to be escaped themselves in java Strings):

paragraph.addMarkup(
    "Escape \\* with \\\\\\* and \\_ with \\\\\\_ in markup.\n",
    11, BaseFont.Times);

markup example

As of version 0.4.0 also color markup is supported:

markup example

Use the markup {color:#ff0000} for changing the font color where #ff0000 is the hex RGB code of the color, so pure red in this case.

paragraph.addMarkup(
    "And now also {color:#ff0000}c{color:#00ff00}o{color:#0000ff}l{color:#00cccc}o{color:#cc00cc}r{color:#000000}",
    11, BaseFont.Times);

With the markup {_} you may create subscript, and superscript with {^}:

paragraph.addMarkup(" , {_}subscript{_} and {^}superscript{^}.\n\n",
	11, BaseFont.Times);

Underline is supported by using the markup __. You can alter the position, which is a scale factor multiplied with the font size and used as an offset to the baseline, the default is -0.15. An optional thickness scale factor is multiplied with the default:

markup example

paragraph
	.addMarkup(
		"You can alternate the position and thickness of an __underline__, "
			+ "so you may also use this to __{0.25:}strike through__ or blacken __{0.25:20}things__ out\n\n",
		11, BaseFont.Times);

Have a look at the complete example in Markup.java and the resulting PDF markup.pdf.

Indentation and Lists in Markup

Indentations are described in detail in IndentationAndLists. This section describes how to deal with indentation in markup. You will find all examples in Indentation.java. We're gonna start with some simple indentation. You start the indentation with -- at the beginning of a new line:

"--At vero eos et accusam\n"

Indents run until the end of a paragraph, or until another indentation starts. But you can you can explicitly end the indentation with !-:

"-!And end the indentation.:\n"

The default indent is 4 characters, but you can customize this by specifying the desired indentation in pt or em, so the markup --{50pt} will give you an indent of 50pt. Be aware that this size is per indent level, so if you prefix a space, you will get 100pt in this case.

To create lists with bullets, use the -+ markup:

    + "-+This is a list item\n"
    + "-+Another list item\n"

You can specify different levels of indentation just be prefixing the indent markup with one or multiple spaces:

    + " -+A sub list item\n"

You can customize the indent size and the bullet character (after all, this is the indentation label). Let's do an indent of 8 characters and use >> as the bullet: -+{>>:8em}

Enumerated lists are supported also, just use the -# markup:

    + "-#This is a list item\n"
    + "-#Another list item\n"

Again, you can customize the indent size and also the enumeration type. The default type is arabic numbers, but let's use the roman enumerator: -#{I:6em}. The following enumerator types are built in:

  • 1 arabic
  • I roman, upper case
  • i roman, lower case
  • A alphabetic, upper case
  • a alphabetic, lower case

But you may also write your own enumerator and use it in markup, see class EnumeratorFactory for more details on that.

Hyperlinks

Hyperlinks are described in detail in Hyperlinks. This section describes how to deal with hyperlinks in markup. You will find all examples in Links.java. Let's start with an external link to http://www.pdfbox.org:

paragraph.addMarkup(
   "This is a link to {link[http://www.pdfbox.org]}PDFBox{link}",
   11, BaseFont.Helvetica);

By default the link is rendered with an underline. You can alter this style, currently only ul (underline) and none is supported. As always, you can use other markup additionally, e.g. to get a hyperlink that is colored without an underline, you can write

"Now the same link with color instead of underline {color:#ff5000}{link:none[https://github.com/ralfstuckert/pdfbox-layout]}PDFBox-Layout{link}{color:#000000}"

Here are some examples from the Links.java:

links.pdf

You can also create links into the document itself. You just need to set up a named anchor, and use this' anchors name in the link:

paragraph0.addMarkup(
   "And here comes a link to an internal anchor name {color:#ff5000}{link[#hello]}hello{link}{color:#000000}.\n\n", 
   11, BaseFont.Times);

...
paragraph4.addMarkup(
   "\n\n{anchor:hello}Here{anchor} comes the internal anchor named *hello*\n\n", 
   15, BaseFont.Courier);

So we define an anchor {anchor:hello}Here{anchor} somewhere in the document with the logical name hello. This anchor name is used in the link prefixed with a hash to indicate an internal link {link[#hello]}hello{link}.

Content

Clone this wiki locally