attributes = new HashMap<>();
attributes.put("src", src);
return attributes;
});
```
where `streamToBase64` is a function that reads an input stream and encodes it as a Base64 string.
## Writing style maps
A style map is made up of a number of style mappings separated by new lines.
Blank lines and lines starting with `#` are ignored.
A style mapping has two parts:
* On the left, before the arrow, is the document element matcher.
* On the right, after the arrow, is the HTML path.
When converting each paragraph,
Mammoth finds the first style mapping where the document element matcher matches the current paragraph.
Mammoth then ensures the HTML path is satisfied.
### Freshness
When writing style mappings, it's helpful to understand Mammoth's notion of freshness.
When generating, Mammoth will only close an HTML element when necessary.
Otherwise, elements are reused.
For instance, suppose one of the specified style mappings is `p[style-name='Heading 1'] => h1`.
If Mammoth encounters a .docx paragraph with the style name `Heading 1`,
the .docx paragraph is converted to a `h1` element with the same text.
If the next .docx paragraph also has the style name `Heading 1`,
then the text of that paragraph will be appended to the *existing* `h1` element,
rather than creating a new `h1` element.
In most cases, you'll probably want to generate a new `h1` element instead.
You can specify this by using the `:fresh` modifier:
`p[style-name='Heading 1'] => h1:fresh`
The two consecutive `Heading 1` .docx paragraphs will then be converted to two separate `h1` elements.
Reusing elements is useful in generating more complicated HTML structures.
For instance, suppose your .docx contains asides.
Each aside might have a heading and some body text,
which should be contained within a single `div.aside` element.
In this case, style mappings similar to `p[style-name='Aside Heading'] => div.aside > h2:fresh` and
`p[style-name='Aside Text'] => div.aside > p:fresh` might be helpful.
### Document element matchers
#### Paragraphs, runs and tables
Match any paragraph:
```
p
```
Match any run:
```
r
```
Match any table:
```
table
```
To match a paragraph, run or table with a specific style,
you can reference the style by name.
This is the style name that is displayed in Microsoft Word or LibreOffice.
For instance, to match a paragraph with the style name `Heading 1`:
```
p[style-name='Heading 1']
```
You can also match a style name by prefix.
For instance, to match a paragraph where the style name starts with `Heading`:
```
p[style-name^='Heading']
```
Styles can also be referenced by style ID.
This is the ID used internally in the .docx file.
To match a paragraph or run with a specific style ID,
append a dot followed by the style ID.
For instance, to match a paragraph with the style ID `Heading1`:
```
p.Heading1
```
#### Bold
Match explicitly bold text:
```
b
```
Note that this matches text that has had bold explicitly applied to it.
It will not match any text that is bold because of its paragraph or run style.
#### Italic
Match explicitly italic text:
```
i
```
Note that this matches text that has had italic explicitly applied to it.
It will not match any text that is italic because of its paragraph or run style.
#### Underline
Match explicitly underlined text:
```
u
```
Note that this matches text that has had underline explicitly applied to it.
It will not match any text that is underlined because of its paragraph or run style.
#### Strikethough
Match explicitly struckthrough text:
```
strike
```
Note that this matches text that has had strikethrough explicitly applied to it.
It will not match any text that is struckthrough because of its paragraph or run style.
#### All caps
Match explicitly all caps text:
```
all-caps
```
Note that this matches text that has had all caps explicitly applied to it.
It will not match any text that is all caps because of its paragraph or run style.
#### Small caps
Match explicitly small caps text:
```
small-caps
```
Note that this matches text that has had small caps explicitly applied to it.
It will not match any text that is small caps because of its paragraph or run style.
#### Ignoring document elements
Use `!` to ignore a document element.
For instance, to ignore any paragraph with the style `Comment`:
```
p[style-name='Comment'] => !
```
### HTML paths
#### Single elements
The simplest HTML path is to specify a single element.
For instance, to specify an `h1` element:
```
h1
```
To give an element a CSS class,
append a dot followed by the name of the class:
```
h1.section-title
```
To require that an element is fresh, use `:fresh`:
```
h1:fresh
```
Modifiers must be used in the correct order:
```
h1.section-title:fresh
```
#### Separators
To specify a separator to place between the contents of paragraphs that are collapsed together,
use `:separator('SEPARATOR STRING')`.
For instance, suppose a document contains a block of code where each line of code is a paragraph with the style `Code Block`.
We can write a style mapping to map such paragraphs to `` elements:
```
p[style-name='Code Block'] => pre
```
Since `pre` isn't marked as `:fresh`,
consecutive `pre` elements will be collapsed together.
However, this results in the code all being on one line.
We can use `:separator` to insert a newline between each line of code:
```
p[style-name='Code Block'] => pre:separator('\n')
```
#### Nested elements
Use `>` to specify nested elements.
For instance, to specify `h2` within `div.aside`:
```
div.aside > h2
```
You can nest elements to any depth.
## Missing features
Compared to the JavaScript and Python implementations, the following features
are currently missing:
* CLI
* Writing embedded style maps
* Markdown support
* Document transforms
## Donations
If you'd like to say thanks, feel free to [make a donation through Ko-fi](https://ko-fi.com/S6S01MG20).
If you use Mammoth as part of your business,
please consider supporting the ongoing maintenance of Mammoth by [making a weekly donation through Liberapay](https://liberapay.com/mwilliamson/donate).