geomd 0.1.0__tar.gz

geomd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergei Papulin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geomd-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: geomd
+Version: 0.1.0
+Summary: GeoMarkdown is a Markdown dialect for geodata. This package provides parsers and renderers that convert between GeoMarkdown and GeoJSON
+Author: Sergei
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: geojson>=3.3.0
+Requires-Dist: mistune>=3.3.4
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/spapulin/geomd
+Project-URL: Repository, https://github.com/spapulin/geomd
+Project-URL: Issues, https://github.com/spapulin/fetta/geomd
+Description-Content-Type: text/markdown
+
+# geomd
+
+GeoMarkdown is a Markdown dialect for geodata. This package provides parsers and renderers that convert between GeoMarkdown and GeoJSON
+
+## Install
+
+With uv (recommended):
+
+    uv add "geomd @ git+https://github.com/spapulin/geomd.git"
+
+With pip:
+
+    pip install "geomd @ git+https://github.com/spapulin/geomd.git"
+
+## License
+
+[MIT](LICENSE)

geomd-0.1.0/README.md

@@ -0,0 +1,17 @@
+# geomd
+
+GeoMarkdown is a Markdown dialect for geodata. This package provides parsers and renderers that convert between GeoMarkdown and GeoJSON
+
+## Install
+
+With uv (recommended):
+
+    uv add "geomd @ git+https://github.com/spapulin/geomd.git"
+
+With pip:
+
+    pip install "geomd @ git+https://github.com/spapulin/geomd.git"
+
+## License
+
+[MIT](LICENSE)

geomd-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "geomd"
+version = "0.1.0"
+description = "GeoMarkdown is a Markdown dialect for geodata. This package provides parsers and renderers that convert between GeoMarkdown and GeoJSON"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "geojson>=3.3.0",
+    "mistune>=3.3.4",
+]
+
+[[project.authors]]
+name = "Sergei"
+
+[project.scripts]
+geomd = "geomd:main"
+
+[project.urls]
+Homepage = "https://github.com/spapulin/geomd"
+Repository = "https://github.com/spapulin/geomd"
+Issues = "https://github.com/spapulin/fetta/geomd"
+
+[build-system]
+requires = ["uv_build>=0.12.17,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.3.0",
+    "jupyterlab>=4.6.4",
+    "pytest>=8",
+    "ruff>=0.6",
+]

geomd-0.1.0/pyproject.toml.orig

@@ -0,0 +1,40 @@
+[project]
+name = "geomd"
+version = "0.1.0"
+description = "GeoMarkdown is a Markdown dialect for geodata. This package provides parsers and renderers that convert between GeoMarkdown and GeoJSON"
+readme = "README.md"
+authors = [
+    { name = "Sergei" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "geojson>=3.3.0",
+    "mistune>=3.3.4",
+]
+
+[project.scripts]
+geomd = "geomd:main"
+
+[project.urls]
+Homepage = "https://github.com/spapulin/geomd"
+Repository = "https://github.com/spapulin/geomd"
+Issues = "https://github.com/spapulin/fetta/geomd"
+
+[build-system]
+requires = ["uv_build>=0.12.17,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.3.0",
+    "jupyterlab>=4.6.4",
+    "pytest>=8",
+    "ruff>=0.6",
+]

geomd-0.1.0/src/geomd/__init__.py

@@ -0,0 +1,16 @@
+from .models import (
+    Node, Heading, Paragraph, List, ListItem,
+    Text, CodeBlock, Link, Image, HtmlBlock, GeometryBlock,
+)
+from .registry import convert, parse, render
+
+__all__ = [
+    "Node", "Heading", "Paragraph", "List", "ListItem",
+    "Text", "CodeBlock", "Link", "Image", "HtmlBlock",
+    "GeometryBlock",
+    "convert", "render", "parse"
+]
+
+
+
+

geomd-0.1.0/src/geomd/constants.py

@@ -0,0 +1,4 @@
+
+_METADATA_KEY = "_metadata"
+_EXTRA_FIELDS = "extra_fields"
+_FIELD_MAPPING = "field_mapping"

geomd-0.1.0/src/geomd/helpers.py

@@ -0,0 +1,39 @@
+from .constants import _EXTRA_FIELDS, _FIELD_MAPPING
+
+
+def parse_metadata_from_html_comment(comment: str) -> dict:
+    extra_fields, field_mapping = {}, {}
+    section = None
+    for raw_line in comment.splitlines():
+
+        line = raw_line.strip()
+        if not line:
+            continue
+
+        if line == f"{_EXTRA_FIELDS}:":
+            section = extra_fields
+            continue
+
+        if line == f"{_FIELD_MAPPING}:":
+            section = field_mapping
+            continue
+
+        if line.startswith("- ") and section is not None:
+            key, _, value = line[2:].partition(":")
+            section[key.strip()] = value.strip()
+
+    return {
+        _EXTRA_FIELDS: extra_fields,
+        _FIELD_MAPPING: field_mapping
+    }
+
+
+def render_metadata_as_html_comment(metadata: dict) -> str:
+    comment_list = []
+    for key in [_EXTRA_FIELDS, _FIELD_MAPPING]:
+        if key in metadata and metadata[key]:
+            comment_list.append(f"{key}:")
+            for attr, value in metadata[key].items():
+                comment_list.append(f"\t- {attr}: {value}")
+    comments_body = "\n".join(comment_list)
+    return f"<!--\n{comments_body}\n-->"

geomd-0.1.0/src/geomd/models.py

@@ -0,0 +1,101 @@
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+import geojson
+
+
+@dataclass
+class Node:
+
+    children: list["Node"] = field(default_factory=list)
+
+    NODE_TYPE: ClassVar[str] = ""
+
+    def to_dict(self) -> dict:
+        result = {"type": self.NODE_TYPE}
+        for attr, val in self.__dict__.items():
+            if attr == "children":
+                if val:
+                    result["children"] = [node.to_dict() for node in val]
+            elif val not in (None, ""):
+                result[attr] = val
+        return result
+
+
+@dataclass
+class Heading(Node):
+    NODE_TYPE = "heading"
+    level: int = 1
+
+
+@dataclass
+class Paragraph(Node):
+    NODE_TYPE = "paragraph"
+
+
+@dataclass
+class Text(Node):
+    NODE_TYPE = "text"
+    raw: str = ""
+
+
+@dataclass
+class Link(Node):
+    NODE_TYPE = "link"
+    url: str = ""
+    title: str = ""
+
+
+@dataclass
+class Image(Node):
+    NODE_TYPE = "image"
+    url: str = ""
+    alt: str = ""
+    title: str = ""
+
+
+@dataclass
+class CodeBlock(Node):
+    NODE_TYPE = "code_block"
+    raw: str = ""
+    language: str = ""
+
+
+@dataclass
+class List(Node):
+    NODE_TYPE = "list"
+    ordered: bool = False
+    start: int = 1
+
+
+@dataclass
+class ListItem(Node):
+    NODE_TYPE = "list_item"
+
+
+@dataclass
+class HtmlBlock(Node):
+    NODE_TYPE = "html_block"
+    raw: str = ""
+
+
+@dataclass
+class GeometryBlock(Node):
+    NODE_TYPE = "geometry_block"
+    geometry: geojson.GeoJSON | None = None
+
+
+# def from_dict(d: dict) -> Node:
+#
+#     node_type: str = d["type"]
+#     children = [from_dict(c) for c in d.get("children", [])]
+#     attrs = {attr: v for attr, v in d.items() if attr not in ("type", "children")}
+#
+#     if node_type == Heading.NODE_TYPE:
+#         return Heading(children=children, **attrs)
+#     elif node_type == Paragraph.NODE_TYPE:
+#         return Paragraph(children=children)
+#     elif node_type == Text.NODE_TYPE:
+#         return Text(children=children, **attrs)
+#     else:
+#         raise ValueError(f"unknown node type: {node_type}")

geomd-0.1.0/src/geomd/parsers/geojson_parser.py

@@ -0,0 +1,82 @@
+import logging
+
+import geojson
+
+from ..parsers.json_parser import JsonParser
+from ..helpers import render_metadata_as_html_comment
+from ..models import Node, Heading, Text, Paragraph, GeometryBlock, HtmlBlock
+from ..constants import _METADATA_KEY, _EXTRA_FIELDS, _FIELD_MAPPING
+
+logger = logging.getLogger(__name__)
+
+
+class GeoJsonParser(JsonParser):
+    """
+    Parse GeoJSON text into a flat list of document nodes.
+    """
+
+    def parse(self, text: str) -> list[Node]:
+
+        geojson_dict = geojson.loads(text)
+        geojson_dict.pop("type", None)
+
+        root_title = geojson_dict.pop("title", None) or ""
+        features = geojson_dict.pop("features", [])
+
+        content: dict = dict(geojson_dict)
+
+        for feature in features:
+            title = feature["title"] or ""
+            entry = {}
+
+            metadata = feature.get(_METADATA_KEY)
+            if metadata:
+                entry[_METADATA_KEY] = metadata
+
+            entry.update(feature.get("properties") or {})
+            entry["geometry"] = feature["geometry"]
+            content[title] = entry
+
+        return self._to_nodes({root_title: content})
+
+    def _to_nodes(self, data: dict, level: int = 1) -> list[Node]:
+
+        nodes: list[Node] = []
+
+        metadata = data.get(_METADATA_KEY) or {}
+        field_mapping = metadata.get(_FIELD_MAPPING) or {}
+        extra_fields = {name: None for name in metadata.get(_EXTRA_FIELDS) or []}
+
+        for key, value in data.items():
+            if key == _METADATA_KEY:
+                continue
+
+            if key in extra_fields:
+                extra_fields[key] = value
+                continue
+
+            nodes.append(Heading(
+                level=level,
+                children=[Text(raw=field_mapping.get(key, key))],
+            ))
+
+            if isinstance(value, dict):
+                if key == "geometry":
+                    nodes.append(GeometryBlock(geometry=value))
+                else:
+                    nodes.extend(self._to_nodes(value, level + 1))
+            elif isinstance(value, list):
+                nodes.append(self._to_list_node(value))
+            else:
+                nodes.append(Paragraph(children=[Text(raw=str(value))]))
+
+        if metadata:
+            nodes.insert(0, HtmlBlock(
+                raw=render_metadata_as_html_comment({
+                    _EXTRA_FIELDS: extra_fields,
+                    _FIELD_MAPPING: {v: k for k, v in field_mapping.items()}
+                })
+            ))
+
+        return nodes
+

geomd-0.1.0/src/geomd/parsers/geomarkdown_parser.py

@@ -0,0 +1,36 @@
+import logging
+from json import JSONDecodeError
+
+import geojson
+
+from .markdown_parser import MarkdownParser
+from .. import CodeBlock
+from ..models import Node, GeometryBlock
+
+
+logger = logging.getLogger(__name__)
+
+
+_GEOMETRY_LANGUAGE = "geometry"
+
+
+class GeoMarkdownParser(MarkdownParser):
+    """
+    Markdown parser that upgrades ```geometry blocks into GeometryBlock nodes.
+    """
+
+    def parse(self, text: str) -> list[Node]:
+        nodes = super().parse(text)
+        return self._apply_geometry_block(nodes)
+
+    def _apply_geometry_block(self, nodes: list[Node]) -> list[Node]:
+        for i, node in enumerate(nodes):
+            if isinstance(node, CodeBlock) and node.language == _GEOMETRY_LANGUAGE:
+                try:
+                    geometry = geojson.loads(node.raw)
+                except JSONDecodeError as e:
+                    logger.warning("Failed to parse geometry block: %s; raw=%r", e, node.raw)
+                    geometry = None
+                # Replace CodeBlock with GeometryBlock
+                nodes[i] = GeometryBlock(geometry=geometry)
+        return nodes

geomd-0.1.0/src/geomd/parsers/json_parser.py

@@ -0,0 +1,56 @@
+import json
+import logging
+
+from geomd.models import Node, Heading, Text, Paragraph, Image, Link, ListItem, List
+
+
+logger = logging.getLogger(__name__)
+
+
+class JsonParser:
+    """Convert a JSON document into a flat list of document nodes."""
+
+    def parse(self, text: str) -> list[Node]:
+        data = json.loads(text)
+        return self._to_nodes(data)
+
+    def _to_nodes(self, data: dict, level: int = 1) -> list[Node]:
+        nodes: list[Node] = []
+        for key, value in data.items():
+
+            nodes.append(Heading(level=level, children=[Text(raw=key)]))
+
+            if isinstance(value, dict):
+                nodes.extend(self._to_nodes(value, level + 1))
+
+            elif isinstance(value, list):
+                nodes.append(self._to_list_node(value))
+            else:
+                nodes.append(Paragraph(children=[Text(raw=str(value))]))
+
+        return nodes
+
+    def _to_list_node(self, items: list) -> Node:
+        list_nodes: list[ListItem] = []
+        for item in items:
+            node = self._to_resource_node(item)
+            if node is not None:
+                list_nodes.append(ListItem(children=[node]))
+        return List(children=list_nodes)
+
+    def _to_resource_node(self, item: str | dict) -> Node | None:
+        if not isinstance(item, dict):
+            return Text(raw=str(item))
+
+        url = item.get("url")
+        title = item.get("title")
+
+        if not url and not title:
+            return None
+
+        if "alt" in item:
+            alt = item["alt"]
+            return Image(url=url, title=title, alt=alt)
+
+        return Link(url=url, title=title)
+

geomd-0.1.0/src/geomd/parsers/markdown_parser.py

@@ -0,0 +1,83 @@
+import logging
+
+import mistune
+
+from geomd.models import Node, Heading, Paragraph, Text, CodeBlock, Link, Image, List, ListItem, HtmlBlock
+
+logger = logging.getLogger(__name__)
+
+_md = mistune.create_markdown(renderer=None)
+
+
+class MarkdownParser:
+    """Convert a Markdown document into a flat list of document nodes."""
+
+    def parse(self, text: str) -> list[Node]:
+        ast, _ = _md.parse(text)
+        nodes = []
+        for node in ast:
+            node = self._to_nodes(node)
+            if node is not None:
+                nodes.append(node)
+        return nodes
+
+    def _to_nodes(self, node: dict) -> Node | None:
+        node_type = node["type"]
+        match node_type:
+            case "heading":
+                return Heading(
+                    level=node["attrs"]["level"],
+                    children=self._get_children(node)
+                )
+            case "paragraph" | "block_text":
+                return Paragraph(
+                    children=self._get_children(node)
+                )
+            case "text":
+                return Text(raw=node["raw"])
+            case "block_code":
+                return CodeBlock(
+                    language=node.get("attrs", {}).get("info", ""),
+                    raw=node["raw"]
+                )
+            case "link":
+                title = ""
+                children = node.get("children")
+                if children:
+                    title = children[0].get("raw")
+                return Link(
+                    url=node["attrs"]["url"],
+                    title=title,
+                )
+            case "image":
+                title = ""
+                children = node.get("children")
+                if children:
+                    title = children[0].get("raw")
+                return Image(
+                    url=node["attrs"]["url"],
+                    alt=node["attrs"].get("title") or "",
+                    title=title
+                )
+            case "list":
+                return List(
+                    ordered=node["bullet"] != "-",
+                    children=self._get_children(node)
+                )
+            case "list_item":
+                return ListItem(
+                    children=self._get_children(node)
+                )
+            case "block_html":
+                return HtmlBlock(raw=node.get("raw"))
+            case "blank_line":
+                return None
+            case _:
+                raise ValueError(f"unhandled token: {node_type}")
+
+    def _get_children(self, node: dict) -> list[Node]:
+        return [
+            node := self._to_nodes(child)
+            for child in node.get("children") or []
+            if node is not None
+        ]

geomd-0.1.0/src/geomd/protocol.py

@@ -0,0 +1,12 @@
+from typing import Protocol
+
+from geomd.models import Node
+
+
+class Parser(Protocol):
+    def parse(self, text: str) -> list[Node]: ...
+
+class Renderer(Protocol):
+    def render(self, nodes: list[Node]) -> str: ...
+
+

geomd-0.1.0/src/geomd/registry.py

@@ -0,0 +1,42 @@
+from .models import Node
+from .parsers.json_parser import JsonParser
+from .parsers.markdown_parser import MarkdownParser
+from .parsers.geojson_parser import GeoJsonParser
+from .parsers.geomarkdown_parser import GeoMarkdownParser
+from .protocol import Parser, Renderer
+from .renderers.geomarkdown_renderer import GeoMarkdownRenderer
+from .renderers.json_renderer import JsonRenderer
+from .renderers.markdown_renderer import MarkdownRenderer
+from .renderers.geojson_renderer import GeoJsonRenderer
+
+
+__all__ = [
+    "convert", "parse", "render"
+]
+
+PARSERS: dict[str, Parser]  = {
+    "json": JsonParser(),
+    "md": MarkdownParser(),
+    "geomd": GeoMarkdownParser(),
+    "geojson": GeoJsonParser()
+}
+
+
+RENDERERS: dict[str, Renderer] = {
+    "json": JsonRenderer(),
+    "md": MarkdownRenderer(),
+    "geojson": GeoJsonRenderer(),
+    "geomd": GeoMarkdownRenderer()
+}
+
+
+def convert(text: str, src: str, dst: str) -> str:
+    return render(parse(text, src), dst)
+
+
+def parse(text: str, fmt: str) -> list[Node]:
+    return PARSERS[fmt].parse(text)
+
+
+def render(nodes: list[Node], fmt: str) -> str:
+    return RENDERERS[fmt].render(nodes)

geomd-0.1.0/src/geomd/renderers/geojson_renderer.py

@@ -0,0 +1,70 @@
+import geojson
+
+from .json_renderer import JsonRenderer
+from ..models import Node, List, Paragraph, GeometryBlock, HtmlBlock
+
+
+class GeoJsonRenderer(JsonRenderer):
+    """Render document nodes to a GeoJSON FeatureCollection string."""
+
+    def render(self, nodes: list[Node]) -> str:
+        json_dict = super()._render_json(nodes)
+        formatted_dict = self._map_fields_and_add_extra_fields(json_dict)
+        features, extra = self._build_features(formatted_dict, )
+        feature_collection = geojson.FeatureCollection(features=features, **extra)
+        return geojson.dumps(feature_collection)
+
+    def _build_features(
+            self,
+            data: dict,
+            title: str | None = None
+    ) -> tuple[list[geojson.Feature], dict]:
+        """Recursively split data into Features (dicts with geometry) and extra properties."""
+
+        # A dict containing "geometry" becomes one Feature,
+        # everything else bubbles up
+        if "geometry" in data:
+            geometry = data.pop("geometry")
+            return [geojson.Feature(
+                geometry=geometry,
+                properties=data,
+                title=title
+            )], {}
+
+        extra: dict = {}
+        features: list[geojson.Feature] = list()
+
+        for key, value in data.items():
+            if isinstance(value, dict):
+                feats, ext = self._build_features(
+                    data=value,
+                    title=key
+                )
+                features.extend(feats)
+                extra.update(ext)
+            else:
+                extra[key] = value
+
+        return features, extra
+
+    def _render_section(self, nodes: list[Node]) -> list | dict | str:
+        """Render a section of nodes."""
+
+        # Fast path: a single List / GeometryBlock / HtmlBlock maps to a non-paragraph value
+        if len(nodes) == 1:
+            node = nodes[0]
+            if isinstance(node, List):
+                return self._render_list_block(nodes[0].children)
+            elif isinstance(node, GeometryBlock):
+                return node.geometry
+            elif isinstance(node, HtmlBlock):
+                return node.raw
+
+        # General path: render each supported node to a string, join with blank lines
+        result: list[str] = list()
+        for node in nodes:
+            if isinstance(node, List):
+                result.append(self._render_inline_list(node.children, ordered=node.ordered))
+            elif isinstance(node, Paragraph):
+                result.append(self._render_paragraph(node.children))
+        return "\n\n".join(result)

geomd-0.1.0/src/geomd/renderers/geomarkdown_renderer.py

@@ -0,0 +1,33 @@
+import geojson
+
+from .markdown_renderer import MarkdownRenderer
+from ..models import Node, Heading, Paragraph, List, CodeBlock, GeometryBlock, HtmlBlock
+
+
+class GeoMarkdownRenderer(MarkdownRenderer):
+    """Render document nodes back to Markdown text."""
+
+    def render(self, nodes: list[Node]) -> str:
+        return self._to_markdown(nodes)
+
+    def _to_markdown(self, nodes: list[Node]) -> str:
+        """Convert each block node to its Markdown form, joined by blank lines."""
+
+        blocks: list[str] = []
+        for node in nodes:
+            if isinstance(node, Heading):
+                blocks.append("#" * node.level + " " + self._render_inline(node.children))
+            elif isinstance(node, Paragraph):
+                blocks.append(self._render_inline(node.children))
+            elif isinstance(node, List):
+                blocks.append(self._render_list(node.children, ordered=node.ordered))
+            elif isinstance(node, CodeBlock):
+                language = node.language or ""
+                blocks.append(f"```{language}\n{node.raw}\n```")
+            elif isinstance(node, HtmlBlock):
+                blocks.append(f"{node.raw}")
+            elif isinstance(node, GeometryBlock):
+                blocks.append(f"```geometry\n{geojson.dumps(node.geometry)}\n```")
+            else:
+                raise ValueError(f"No such block node: {node.NODE_TYPE}")
+        return "\n\n".join(blocks) + "\n"

geomd-0.1.0/src/geomd/renderers/json_renderer.py

@@ -0,0 +1,190 @@
+import json
+
+from ..helpers import parse_metadata_from_html_comment
+from ..models import Node, Heading, Paragraph, Text, List, Link, Image, ListItem, HtmlBlock
+from ..constants import _METADATA_KEY, _FIELD_MAPPING, _EXTRA_FIELDS
+
+
+class JsonRenderer:
+    """Render document nodes to a JSON string."""
+
+    def render(self, nodes: list[Node]) -> str:
+        return self._to_json(nodes)
+
+    def _to_json(self, nodes: list[Node]) -> str:
+        """
+        Render nodes, then apply field mapping and
+        extra fields from metadata.
+        """
+        json_dict = self._render_json(nodes)
+        formatted_json_dict = self._map_fields_and_add_extra_fields(json_dict)
+        return json.dumps(formatted_json_dict)
+
+    def _map_fields_and_add_extra_fields(self, data: dict) -> dict:
+        if not isinstance(data, dict):
+            return data
+
+        # Extract metadata up front so mapping applies to *all* sibling
+        # keys, regardless of where "_metadata" sits in the dict
+        metadata = data.get(_METADATA_KEY) or {}
+        extra_fields = metadata.get(_EXTRA_FIELDS) or {}
+        field_mapping = metadata.get(_FIELD_MAPPING) or {}
+
+        result: dict = {}
+
+        # Merge extras first so they go before real (mapped) content
+        result.update(extra_fields)
+
+        for key, value in data.items():
+            if key == _METADATA_KEY:
+                continue
+            result[field_mapping.get(key, key)] = self._map_fields_and_add_extra_fields(value)
+
+        return result
+
+    def _render_json(self, nodes: list[Node]) -> dict:
+        """Convert a node list to a nested dict keyed by heading text.
+
+        Example input:
+
+            # Header 3
+            Some text
+            ## Header 4
+            Content under header 1
+
+        Note: Some text will be lost in the current implementation
+        """
+
+        result: dict = {}
+        i = 0
+
+        while i < len(nodes):
+            node = nodes[i]
+            if not isinstance(node, Heading):
+                i += 1
+                continue
+
+            # Key is a property name
+            key = self._render_paragraph(node.children)
+
+            # Collect everything until the next heading of same/down level
+            j = i + 1
+            while j < len(nodes):
+                next_node = nodes[j]
+                if isinstance(next_node, Heading) and next_node.level <= node.level:
+                    # Found next same/up level
+                    break
+                j += 1
+
+            # Current level section content
+            section = nodes[i + 1:j]
+            section_value: dict = {}
+
+            # Pull a metadata HTML comment from the section head, if present
+            # (only when it's not the entire section. Otherwise, it's the content)
+            if len(section) > 1:
+                first_section_node = section[0]
+                if isinstance(first_section_node, HtmlBlock):
+                    section_value[_METADATA_KEY] = parse_metadata_from_html_comment(first_section_node.raw)
+                    section = section[1:]
+
+            if any(isinstance(_node, Heading) for _node in section):
+                # Go deeper if there is Heading
+                # Note: We assume that next node is Header, otherwise
+                # we lose data
+                section_value.update(self._render_json(section))
+                result[key] = section_value
+            else:
+                values = self._render_section(section)
+                if not values:
+                    result[key] = ""
+                elif len(values) == 1:
+                    result[key] = values[0]
+                else:
+                    result[key] = values
+
+            i = j
+        return result
+
+    def _render_section(self, nodes: list[Node]) -> list | str:
+        """Render a section's content."""
+        if len(nodes) == 1:
+            node = nodes[0]
+            if isinstance(node, List):
+                return self._render_list_block(node.children)
+            elif isinstance(node, HtmlBlock):
+                return node.raw
+
+        # General case: paragraphs and inline lists joined by blank lines
+        result: list[str] = []
+        for node in nodes:
+            if isinstance(node, List):
+                result.append(self._render_inline_list(node.children, ordered=node.ordered))
+            elif isinstance(node, Paragraph):
+                result.append(self._render_paragraph(node.children))
+        return "\n\n".join(result)
+
+    def _render_list_block(self, nodes: list[Node]) -> list:
+        """Convert list items to resource dicts or plain strings."""
+        result: list = []
+        for node in nodes:
+            if not node.children:
+                continue
+            result.append(self._render_resource(node.children[0]))
+        return result
+
+    def _render_resource(self, node: Node) -> dict | str | None:
+        """Convert a Link/Image/Text/Paragraph node"""
+        if isinstance(node, Link):
+            return {
+                "url": node.url,
+                "title": node.title
+            }
+        elif isinstance(node, Image):
+            return {
+                "url": node.url,
+                "title": node.title,
+                "alt": node.alt
+            }
+        elif isinstance(node, Text):
+            return node.raw
+        elif isinstance(node, Paragraph):
+            return self._render_resource(node.children[0])
+
+        return None
+
+    def _render_inline_list(
+            self,
+            nodes: list[ListItem],
+            ordered: bool = False,
+            indent: int = 0
+    ) -> str:
+        """Render list items as Markdown bullets / numbered lines."""
+        result: list[str] = []
+        for i, node in enumerate(nodes):
+            marker = f"{i + 1}. " if ordered else "- "
+            pad = " " * indent
+            for child in node.children:
+                content = []
+                if isinstance(child, Paragraph):
+                    content.append(self._render_paragraph(child.children))
+                result.append(pad + marker + "\n".join(content))
+        return "\n".join(result)
+
+
+    def _render_paragraph(self, nodes: list[Node]) -> str:
+        """Flatten inline nodes to plain text (keeps links/images, drops other formatting)."""
+        result: list[str] = []
+        for node in nodes:
+            if isinstance(node, Text):
+                result.append(node.raw)
+            if isinstance(node, Link):
+                title = f'"{node.title}"' if node.title else ""
+                result.append(f"[{title}]({node.url})")
+            elif isinstance(node, Image):
+                # Standard Markdown: ![alt](url "title")
+                title = f' "{node.title}"' if node.title else ""
+                result.append(f"![{node.alt}]({node.url}{title})")
+            else:
+                result.append(self._render_paragraph(getattr(node, "children", [])))
+        return "".join(result)

geomd-0.1.0/src/geomd/renderers/markdown_renderer.py

@@ -0,0 +1,68 @@
+from geomd.models import Node, Heading, Paragraph, CodeBlock, Text, Link, Image, List, ListItem
+
+
+class MarkdownRenderer:
+    """Render document nodes back to Markdown text."""
+
+    def render(self, nodes: list[Node]) -> str:
+        return self._to_markdown(nodes)
+
+    def _to_markdown(self, nodes: list[Node]) -> str:
+        """Convert each block node to its Markdown form, joined by blank lines."""
+
+        blocks: list[str] = []
+        for node in nodes:
+            if isinstance(node, Heading):
+                blocks.append("#" * node.level + " " + self._render_inline(node.children))
+            elif isinstance(node, Paragraph):
+                blocks.append(self._render_inline(node.children))
+            elif isinstance(node, List):
+                blocks.append(self._render_list(node.children, ordered=node.ordered))
+            elif isinstance(node, CodeBlock):
+                language = node.language or ""
+                blocks.append(f"```{language}\n{node.raw}\n```")
+            else:
+                raise ValueError(f"No such block node: {node.NODE_TYPE}")
+        return "\n\n".join(blocks) + "\n"
+
+    def _render_list(
+            self, nodes:
+            list[Node],
+            ordered: bool = False,
+            indent: int = 0
+    ) -> str:
+        """Render list items as Markdown bullets or numbered entries."""
+        lines: list[str] = []
+        pad = " " * indent
+
+        for i, item in enumerate(nodes):
+            marker = f"{i + 1}. " if ordered else "- "
+            body = self._render_inline(item.children).strip()
+            body_lines = body.splitlines() or [""]
+
+            # First line carries the marker; continuation lines are indented
+            # to line up with the item's text
+            lines.append(pad + marker + body_lines[0])
+            continuation = " " * len(marker)
+            for line in body_lines[1:]:
+                lines.append(pad + continuation + line)
+
+        return "\n".join(lines)
+
+    def _render_inline(self, nodes: list[Node]) -> str:
+        """Flatten inline nodes (Text/Link/Image) to a single string."""
+
+        result: list[str] = []
+        for node in nodes:
+            if isinstance(node, Text):
+                result.append(node.raw)
+            elif isinstance(node, Link):
+                title = f'"{node.title}"' if node.title else ""
+                result.append(f"[{title}]({node.url})")
+            elif isinstance(node, Image):
+                # Standard Markdown: ![alt](url "title")
+                title = f' "{node.title}"' if node.title else ""
+                result.append(f"![{node.alt}]({node.url}{title})")
+            else:
+                raise ValueError(f"No such inline node: {node.NODE_TYPE}")
+        return "".join(result)