Skip to content

Support external CSS #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dfop02 wants to merge 6 commits into
base: release/1.1.4
Choose a base branch
from
Open

Support external CSS #57

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0463508
Support external CSS
dfop02 Dec 27, 2025
031f5a0
update small css test
dfop02 Dec 28, 2025
1083171
small updates, still failing
dfop02 Dec 28, 2025
7671d1c
Attempt to solve priority order issues
dfop02 Jan 11, 2026
29a317d
Small test
dfop02 Jan 11, 2026
59a6d49
small test 2
dfop02 Jan 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .vscode/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"python.testing.pytestArgs": [
"."
],
"python.testing.unittestEnabled": false,
"python.testing.pytestEnabled": true
}
81 changes: 71 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ parser.table_style = 'Table Grid'

All table styles we support can be found [here](https://python-docx.readthedocs.io/en/latest/user/styles-understanding.html#table-styles-in-default-template).

#### Options
## Options

There is 5 options that you can use to personalize your execution:
- Disable Images: Ignore all images.
Expand Down Expand Up @@ -189,7 +189,9 @@ parser = HtmlToDocx(default_paragraph_style='Body')
parser = HtmlToDocx(default_paragraph_style=None)
```

### Inline CSS Styles
## CSS

#### Inline CSS Styles

Full support for inline CSS styles on any element:

Expand All @@ -198,7 +200,47 @@ Full support for inline CSS styles on any element:
<span style="font-weight: bold; color: blue">Bold blue text</span>
```

Supported CSS properties:
#### External CSS Styles

Limited support for external CSS styles (local or url):

**HTML**

```html
<head>
<title>My page</title>
<!-- Must contain rel="stylesheet" otherwise will be ignored -->
<link rel="stylesheet" href="https://my-external-css.domain.com/style.css">
<!-- OR -->
<link rel="stylesheet" href="../my_local/css/style.css">
</head>
<body>
<div class="classFromExternalCss">
<p>This should be Red and <span class="blueSpan">Blue</span>.<p>
<p id="specialParagraph" style="font-weight: normal">A very special paragraph.</p>
</div>
</body>
```

**CSS**

```css
#specialParagraph {
text-decoration: underline solid red;
color: gray
}

.blueSpan {
color: blue;
}

p {
color: red;
font-weight: bold;
}
```

### Supported CSS properties:

- color
- font-size
Expand All @@ -221,7 +263,7 @@ Proper CSS precedence with !important:
</span>
```

The !important flag ensures highest priority.
The `!important` flag ensures highest priority.

### Style Precedence Order

Expand All @@ -230,10 +272,11 @@ Styles are applied in this order (lowest to highest priority):
1. Base HTML tag styles (`<b>`, `<em>`, `<code>`)
2. Parent span styles
3. CSS class-based styles (from `style_map`)
4. Inline CSS styles (from `style` attribute)
5. !important inline CSS styles (highest priority)
4. External CSS Styles (from `style` tag or external files)
5. Inline CSS styles (from `style` attribute)
6. `!important` inline CSS styles (highest priority)

#### Metadata
## Metadata

You're able to read or set docx metadata:

Expand Down Expand Up @@ -299,21 +342,39 @@ My goal in forking and fixing/updating this package was to complete my current t
- Support for common CSS properties for text | [Lynuxen](https://github.com/Lynuxen)
- Support for CSS classes to Word Styles | [raithedavion](https://github.com/raithedavion)
- Support for HTML tag style overrides | [raithedavion](https://github.com/raithedavion)
- Support style tag and external CSS styles | [Dfop02](https://github.com/dfop02)

## To-Do

These are the ideas I'm planning to work on in the future to make this project even better:

- Add support for the `<style>` tag, including all classes, and ensure they are correctly applied throughout the file.
- Add support for the `<link>` tag to load external CSS and apply it properly across the file.
- No ideas for now.

## Known Issues
## Known Limitations

### Lists
- **Maximum Nesting Depth:** Ordered lists support up to 3 nested levels. Any additional depth beyond level 3 will be treated as level 3.
- **Counter Reset Behavior:**
- At level 1, starting a new ordered list will reset the counter.
- At levels 2 and 3, the counter will continue from the previous item unless explicitly reset.

### CSS
1. **Complex Selectors:**
- Do not support complex selector like `div > p`, `h1 + h2`.
- Complex selectors are simplified to root tag.

2. **Pseudo-classes:**
- Do not support `:hover`, `:first-child`, etc.
- They're all removed during CSS Parsing

3. **Media Queries:**
- Do not support `@media` queries.
- Would be necessary a responsive CSS, that's not applied to Docx.

4. **@import:**
- Do not support `@import` em CSS.
- We can try implement it in future if necessary.

## Project Guidelines

This project is primarily designed for compatibility with Microsoft Word, but it currently works well with LibreOffice and Google Docs, based on our testing. The goal is to maintain this cross-platform harmony while continuing to implement fixes and updates.
Expand Down
Loading
Loading