diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 26 |
1 files changed, 16 insertions, 10 deletions
@@ -49,7 +49,9 @@ Where `custom-style-map` looks something like: p.AsideHeading => div.aside > h2:fresh p.AsideText => div.aside > p:fresh -### API +### Library + +#### Basic conversion To convert an existing .docx file to HTML, pass a file-like object to `mammoth.convert_to_html`. @@ -65,12 +67,14 @@ with open("document.docx", "rb") as docx_file: messages = result.messages # Any messages, such as warnings during conversion ``` +### Custom style map + By default, Mammoth maps some common .docx styles to HTML elements. For instance, a paragraph with the style `Heading1` is converted to a `h1` element. -You can pass in custom styles using the `style_map` argument. -A description of the syntax for styles can be found in the section "Writing styles". +You can pass in a custom style map using the `style_map` argument. +A description of the syntax for style maps can be found in the section "Writing style maps". For instance, if paragraphs with the style `SectionTitle` should be converted to `h1` elements, and paragraphs with the style `SubSectionTitle` should be converted to `h2` elements: @@ -88,25 +92,27 @@ with open("document.docx", "rb") as docx_file: User-defined style mappings are used in preference to the default style mappings. -## Writing styles +## Writing style maps + +A style map is made up of a number of style mappings. -A style has two parts: +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 where the document element matcher matches the current 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 styles, it's helpful to understand Mammoth's notion of 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 styles is `p.Heading1 => h1`. -If Mammoth encounters a .docx paragraphs with the style `Heading1`, +For instance, suppose one of the specified style mappings is `p.Heading1 => h1`. +If Mammoth encounters a .docx paragraph with the style `Heading1`, the .docx paragraph is converted to a `h1` element with the same text. If the next .docx paragraph also has the style `Heading1`, then the text of that paragraph will be appended to the *existing* `h1` element, @@ -123,7 +129,7 @@ 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, styles similar to `p.AsideHeading => div.aside > h2:fresh` and +In this case, style mappings similar to `p.AsideHeading => div.aside > h2:fresh` and `p.AsideText => div.aside > p:fresh` might be helpful. ### Document element matchers |