feat: add text color and highlight marks

Adds textStyle and highlight ProseMirror marks (node builders in
substack/nodes.py), with Markdown round-trip via Pandoc-style span
attributes: [text]{style="color:#hex"} and
[text]{style="background-color:#hex"}, combinable in one span.

Verified against Substack's real editor schema by applying both marks
to a live draft and reading the rendered HTML back: textStyle becomes
a <span data-color> with inline color, highlight becomes a <mark
data-color> with inline background-color.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: und1sk0

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Text color and highlight marks (`textStyle` / `highlight`), settable via
+  `substack.nodes.text_style_mark()` / `highlight_mark()` for direct node
+  construction, and in Markdown via Pandoc-style span attributes
+  (`[text]{style="color:#hex"}` / `{style="background-color:#hex"}`), parsed
+  and exported round-trip. Verified against Substack's real editor schema
+  (confirmed by applying both to a live draft and reading the rendered HTML
+  back: `textStyle` becomes a `<span data-color>` with inline `color`,
+  `highlight` becomes a `<mark data-color>` with inline `background-color`).
+
 ## 0.10.0
 
 ### Added

README.md

@@ -201,9 +201,10 @@ For direct ProseMirror node construction, see the
 ## Markdown
 
 Supported Markdown includes headings, paragraphs, bold, italic, inline code,
-strikethrough, superscript, subscript, links, images, linked images, image
-captions, code blocks, blockquotes, ordered and unordered lists, horizontal
-rules, footnotes, LaTeX math, pull quotes, and callouts.
+strikethrough, superscript, subscript, text color, highlight, links, images,
+linked images, image captions, code blocks, blockquotes, ordered and
+unordered lists, horizontal rules, footnotes, LaTeX math, pull quotes, and
+callouts.
 
 ```python
 from substack.post import Post

docs/markdown.md

@@ -35,10 +35,26 @@ Pass `api=` when your Markdown references local images so they can be uploaded
 | `~subscript~`                 | subscript         |
 | `[text](https://example.com)` | link              |
 | `<https://example.com>`       | autolinked URL    |
+| `[text]{style="color:#hex"}`  | text color        |
+| `[text]{style="background-color:#hex"}` | highlight |
 
 Note that subscript uses a single tilde (`~x~`) and strikethrough uses a double
 tilde (`~~x~~`); both work in the same document.
 
+Text color and highlight use Pandoc-style span attributes: a `[span]` followed
+immediately by `{style="..."}`. Only the `color` and `background-color`
+declarations are recognized (others are ignored), and both may be combined in
+one span:
+
+```markdown
+[colorized text]{style="color:#ff00ff"}
+[highlighted text]{style="background-color:#ffff00"}
+[both]{style="color:#ffffff; background-color:#000000"}
+```
+
+A `{...}` block elsewhere (after an image, link, or inline code) is left as
+plain text; the syntax is only recognized immediately after a `[span]`.
+
 ## Headings
 
 Levels 1–6, using `#` through `######`. Headings may contain inline formatting

substack/mdexport.py

@@ -25,6 +25,8 @@
     "superscript",
     "subscript",
     "link",
+    "textStyle",
+    "highlight",
 }
 _IMAGE_ATTRS = {
     "src",
@@ -117,14 +119,18 @@ def _code_span(value):
     return f"{delimiter}{padding}{value}{padding}{delimiter}"
 
 
+_ATTR_MARKS = {"link", "textStyle", "highlight"}
+_STYLE_PROPERTY = {"textStyle": "color", "highlight": "background-color"}
+
+
 def _render_marked_text(value, marks, node, unsupported):
     if not isinstance(value, str) or not isinstance(marks, list):
         raise ValueError("Malformed draft body: text and marks have invalid types")
     for mark in marks:
         _require_dict(mark, "mark")
         if mark["type"] not in _MARK_TYPES:
             return _marker(node, unsupported)
-        allowed = {"type", "attrs"} if mark["type"] == "link" else {"type"}
+        allowed = {"type", "attrs"} if mark["type"] in _ATTR_MARKS else {"type"}
         if _has_unknown_keys(mark, allowed):
             return _marker(node, unsupported)
 
@@ -133,6 +139,7 @@ def _render_marked_text(value, marks, node, unsupported):
         if any(mark["type"] == "code" for mark in marks)
         else _escape_text(value)
     )
+    style_declarations = []
     for mark in marks:
         mark_type = mark["type"]
         if mark_type == "code":
@@ -154,6 +161,16 @@ def _render_marked_text(value, marks, node, unsupported):
             ):
                 return _marker(node, unsupported)
             rendered = f"[{rendered}]({_escape_destination(attrs['href'])})"
+        elif mark_type in _STYLE_PROPERTY:
+            attrs = _attrs(mark, f"{mark_type} mark")
+            if _has_unknown_keys(attrs, {"color"}) or not isinstance(
+                attrs.get("color"), str
+            ):
+                return _marker(node, unsupported)
+            style_declarations.append(f"{_STYLE_PROPERTY[mark_type]}:{attrs['color']}")
+    if style_declarations:
+        style_value = _escape_title("; ".join(style_declarations))
+        rendered = f'[{rendered}]{{style="{style_value}"}}'
     return rendered
 
 

substack/mdrender.py

@@ -27,6 +27,7 @@
 
 from markdown_it import MarkdownIt
 from markdown_it.tree import SyntaxTreeNode
+from mdit_py_plugins.attrs import attrs_plugin
 from mdit_py_plugins.container import container_plugin
 from mdit_py_plugins.dollarmath import dollarmath_plugin
 from mdit_py_plugins.footnote import footnote_plugin
@@ -141,6 +142,10 @@ def _make_parser() -> MarkdownIt:
         .use(superscript_plugin)
         .use(container_plugin, name="pullquote")
         .use(container_plugin, name="callout")
+        # Pandoc-style span attributes, `[text]{style="color:#hex"}`, for text
+        # color and highlight. Restricted to spans only (`after=()`) so a
+        # stray `{...}` after an image, link or inline code is left as text.
+        .use(attrs_plugin, after=(), spans=True)
         .enable("strikethrough")
     )
 
@@ -161,6 +166,28 @@ def _coalesce(out_nodes: List[Dict]) -> List[Dict]:
     return merged
 
 
+def _style_marks(attrs: Dict) -> List[Dict]:
+    """Map a span's `style` attribute to textStyle/highlight marks.
+
+    Only `color` and `background-color` declarations are recognized; any
+    other declaration is ignored rather than rejected, since `{...}` spans
+    are also used (via the attrs plugin) for plain CSS-style attributes in
+    general, not just color.
+    """
+    style = attrs.get("style", "")
+    marks: List[Dict] = []
+    for declaration in style.split(";"):
+        prop, _, value = declaration.partition(":")
+        prop, value = prop.strip().lower(), value.strip()
+        if not value:
+            continue
+        if prop == "color":
+            marks.append(nodes.text_style_mark(value))
+        elif prop == "background-color":
+            marks.append(nodes.highlight_mark(value))
+    return marks
+
+
 def _render_inline(node: SyntaxTreeNode, marks: List[Dict], ctx: Dict) -> List[Dict]:
     """Render an inline subtree into a flat list of text / anchor nodes."""
     out: List[Dict] = []
@@ -178,6 +205,8 @@ def _render_inline(node: SyntaxTreeNode, marks: List[Dict], ctx: Dict) -> List[D
         elif t == "link":
             href = child.attrs.get("href", "")
             out.extend(_render_inline(child, marks + [nodes.link_mark(href)], ctx))
+        elif t == "span":
+            out.extend(_render_inline(child, marks + _style_marks(child.attrs), ctx))
         elif t in ("softbreak", "hardbreak"):
             out.append(nodes.text(" ", marks))
         elif t == "footnote_ref":

substack/nodes.py

@@ -47,6 +47,8 @@ class MarkType:
     SUPERSCRIPT = "superscript"
     SUBSCRIPT = "subscript"
     LINK = "link"
+    TEXT_STYLE = "textStyle"
+    HIGHLIGHT = "highlight"
 
 
 def code_mark() -> Dict:
@@ -64,6 +66,14 @@ def link_mark(href: str) -> Dict:
     return {"type": MarkType.LINK, "attrs": {"href": href}}
 
 
+def text_style_mark(color: str) -> Dict:
+    return {"type": MarkType.TEXT_STYLE, "attrs": {"color": color}}
+
+
+def highlight_mark(color: str) -> Dict:
+    return {"type": MarkType.HIGHLIGHT, "attrs": {"color": color}}
+
+
 def paragraph(content: Optional[List[Dict]] = None) -> Dict:
     return {"type": NodeType.PARAGRAPH, "content": content or []}
 

tests/substack/test_from_markdown_features.py

@@ -60,6 +60,34 @@ def test_link(self):
             {"type": "link", "attrs": {"href": "https://e.com"}}
         ]
 
+    def test_text_color(self):
+        post = make_post()
+        post.from_markdown('x [c]{style="color:#ff00ff"} y')
+        assert marked(first_para_nodes(post), "c") == [
+            {"type": "textStyle", "attrs": {"color": "#ff00ff"}}
+        ]
+
+    def test_highlight(self):
+        post = make_post()
+        post.from_markdown('x [h]{style="background-color:#ffff00"} y')
+        assert marked(first_para_nodes(post), "h") == [
+            {"type": "highlight", "attrs": {"color": "#ffff00"}}
+        ]
+
+    def test_text_color_and_highlight_combined(self):
+        post = make_post()
+        post.from_markdown('x [both]{style="color:#fff; background-color:#000"} y')
+        marks = marked(first_para_nodes(post), "both")
+        assert {"type": "textStyle", "attrs": {"color": "#fff"}} in marks
+        assert {"type": "highlight", "attrs": {"color": "#000"}} in marks
+
+    def test_unrecognized_style_declaration_is_ignored(self):
+        post = make_post()
+        post.from_markdown('x [p]{style="font-weight:bold"} y')
+        # No recognized color/background-color, so the span adds no marks and
+        # merges back into plain surrounding text.
+        assert first_para_nodes(post) == [{"type": "text", "text": "x p y"}]
+
     def test_multiple_marks_in_one_paragraph(self):
         post = make_post()
         post.from_markdown("**b** and *i* and `c` and [l](https://e.com)")

tests/substack/test_markdown_export.py

@@ -23,6 +23,10 @@ def _paragraph(value):
     return {"type": "paragraph", "content": [_text(value)]}
 
 
+def _paragraph_with(*inline_nodes):
+    return {"type": "paragraph", "content": list(inline_nodes)}
+
+
 def test_document_to_markdown_golden_covers_supported_nodes():
     image = captioned_image(
         "https://example.com/image.png",
@@ -161,6 +165,86 @@ def test_document_to_markdown_golden_covers_supported_nodes():
     ]
 
 
+def test_document_to_markdown_renders_text_color():
+    document = {
+        "type": "doc",
+        "content": [
+            _paragraph_with(
+                _text("c", [{"type": "textStyle", "attrs": {"color": "#ff00ff"}}])
+            )
+        ],
+    }
+    markdown, unsupported = document_to_markdown(document)
+    assert unsupported == []
+    assert markdown == '[c]{style="color:#ff00ff"}\n'
+
+
+def test_document_to_markdown_renders_highlight():
+    document = {
+        "type": "doc",
+        "content": [
+            _paragraph_with(
+                _text("h", [{"type": "highlight", "attrs": {"color": "#ffff00"}}])
+            )
+        ],
+    }
+    markdown, unsupported = document_to_markdown(document)
+    assert unsupported == []
+    assert markdown == '[h]{style="background-color:#ffff00"}\n'
+
+
+def test_document_to_markdown_renders_combined_color_and_highlight():
+    document = {
+        "type": "doc",
+        "content": [
+            _paragraph_with(
+                _text(
+                    "both",
+                    [
+                        {"type": "textStyle", "attrs": {"color": "#fff"}},
+                        {"type": "highlight", "attrs": {"color": "#000"}},
+                    ],
+                )
+            )
+        ],
+    }
+    markdown, unsupported = document_to_markdown(document)
+    assert unsupported == []
+    assert markdown == '[both]{style="color:#fff; background-color:#000"}\n'
+
+
+@pytest.mark.parametrize(
+    "mark",
+    [
+        {"type": "textStyle", "attrs": {}},
+        {"type": "highlight", "attrs": {"color": 1}},
+        {"type": "textStyle", "attrs": {"color": "#fff", "extra": True}},
+    ],
+)
+def test_document_to_markdown_treats_malformed_style_mark_as_opaque(mark):
+    document = {
+        "type": "doc",
+        "content": [_paragraph_with(_text("c", [mark]))],
+    }
+    markdown, unsupported = document_to_markdown(document)
+    assert len(unsupported) == 1
+    assert markdown.startswith("<!-- python-substack-node:v1 ")
+
+
+def test_color_and_highlight_round_trip_through_markdown():
+    markdown = (
+        'A [colorized]{style="color:#ff00ff"} and '
+        '[highlighted]{style="background-color:#ffff00"} word'
+    )
+    post = Post("T", "", user_id=1)
+    post.from_markdown(markdown)
+
+    rendered, unsupported = document_to_markdown(post.draft_body)
+
+    assert unsupported == []
+    assert markdown_to_doc(rendered) == post.draft_body["content"]
+
+
 def test_full_feature_fixture_round_trips_exactly():
     fixture = Path(__file__).parent / "fixtures" / "full_features.md"
     post = Post("Feature complete", "", user_id=1)