mdstyledocx 0.1.0__tar.gz

mdstyledocx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YANG Zijie (杨子杰)
+
+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.

mdstyledocx-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: mdstyledocx
+Version: 0.1.0
+Summary: Convert convention-based Markdown into standardized DOCX with reusable style presets.
+Author: YANG Zijie
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-docx>=1.2.0
+Dynamic: license-file
+
+# mdstyledocx
+
+一个按约定编写 Markdown、再一键导出标准化 Word (`.docx`) 的小工具。
+
+当前设计重点不是“完整支持所有 Markdown 语法”，而是“稳定地把结构化 Markdown 落成统一版式的 Word 文档”。它适合做：
+
+- 政府公文预设
+- 单位通知 / 简报 / 汇报材料
+- 团队内部统一模板
+
+## 核心思路
+
+把 Markdown 当成“内容源”，把版式规范抽成“preset”。
+
+你只要按固定约定写 Markdown：
+
+- `#`：文档标题
+- `##`：一级标题
+- `###`：二级标题
+- 空行分段
+- `-` / `*` / `+`：无序列表
+- `1.`：有序列表
+- `<!-- pagebreak -->`：分页
+
+然后执行一次命令，就能得到带统一字体、字号、缩进、页边距的 `.docx`。
+
+## 内置预设
+
+各 preset 的详细说明都放在 `src/mdstyledocx/preset_specs/` 下：
+
+- [default](src/mdstyledocx/preset_specs/default.md)：通用正式文档版式
+- [gov-cn](src/mdstyledocx/preset_specs/gov-cn.md)：中文政府公文风格基线
+- [gov-cn-hei](src/mdstyledocx/preset_specs/gov-cn-hei.md)：黑体标题、楷体二级标题、仿宋正文
+
+目录约定：
+
+- `*.json`：样式参数、页边距、字体、缩进等机器可读定义
+- `*.md`：该模板的写作约定、推荐语法和边界说明
+
+## 使用方式
+
+推荐直接用 `uv`：
+
+```bash
+uv sync
+uv run python -m unittest
+uv run mdstyledocx --list-presets
+uv run mdstyledocx --show-preset-rules gov-cn
+uv run mdstyledocx examples/gov_notice.md -o examples/gov_notice.docx --preset gov-cn
+```
+
+如果不使用 `uv`，也可以用传统方式：
+
+```bash
+pip install -e .
+python3 -m unittest
+mdstyledocx examples/gov_notice.md -o examples/gov_notice.docx --preset gov-cn
+```
+
+## 自定义预设
+
+可以在内置 preset 基础上再叠加一个 JSON 覆盖文件：
+
+```bash
+mdstyledocx input.md -o output.docx --preset gov-cn --preset-file my-preset.json
+```
+
+如果想先看某个模板要求什么 Markdown 写法：
+
+```bash
+mdstyledocx --show-preset-rules gov-cn
+```
+
+示例：
+
+```json
+{
+  "extends": "gov-cn",
+  "styles": {
+    "body": {
+      "line": 520,
+      "line_rule": "exact"
+    },
+    "title": {
+      "size_half_points": 40
+    }
+  }
+}
+```
+
+## Markdown 约定
+
+README 只保留通用约定。某个 preset 的专用写法，以对应的 `preset_specs/*.md` 为准。
+
+通用写法：
+
+```md
+# 关于开展示例工作的通知
+
+各有关单位：
+
+为统一输出格式，现将有关事项通知如下。
+
+## 一、工作目标
+
+1. 统一内容源。
+2. 统一输出格式。
+
+## 二、工作要求
+
+请各单位按要求执行。
+```
+
+## 当前边界
+
+当前版本优先保证：
+
+- 标题、段落、列表、分页可稳定导出
+- 预设版式可复用
+- 产物是标准 `.docx`
+
+暂未覆盖：
+
+- 表格
+- 图片
+- 脚注
+- 复杂嵌套列表
+- 目录自动生成
+
+如果后面继续做，这个工具可以自然扩展成：
+
+- 多个行业 preset 集合
+- frontmatter 驱动的页面元信息
+- 更完整的 Markdown 语法支持
+- GUI 或 Web 包装层

mdstyledocx-0.1.0/README.md

@@ -0,0 +1,135 @@
+# mdstyledocx
+
+一个按约定编写 Markdown、再一键导出标准化 Word (`.docx`) 的小工具。
+
+当前设计重点不是“完整支持所有 Markdown 语法”，而是“稳定地把结构化 Markdown 落成统一版式的 Word 文档”。它适合做：
+
+- 政府公文预设
+- 单位通知 / 简报 / 汇报材料
+- 团队内部统一模板
+
+## 核心思路
+
+把 Markdown 当成“内容源”，把版式规范抽成“preset”。
+
+你只要按固定约定写 Markdown：
+
+- `#`：文档标题
+- `##`：一级标题
+- `###`：二级标题
+- 空行分段
+- `-` / `*` / `+`：无序列表
+- `1.`：有序列表
+- `<!-- pagebreak -->`：分页
+
+然后执行一次命令，就能得到带统一字体、字号、缩进、页边距的 `.docx`。
+
+## 内置预设
+
+各 preset 的详细说明都放在 `src/mdstyledocx/preset_specs/` 下：
+
+- [default](src/mdstyledocx/preset_specs/default.md)：通用正式文档版式
+- [gov-cn](src/mdstyledocx/preset_specs/gov-cn.md)：中文政府公文风格基线
+- [gov-cn-hei](src/mdstyledocx/preset_specs/gov-cn-hei.md)：黑体标题、楷体二级标题、仿宋正文
+
+目录约定：
+
+- `*.json`：样式参数、页边距、字体、缩进等机器可读定义
+- `*.md`：该模板的写作约定、推荐语法和边界说明
+
+## 使用方式
+
+推荐直接用 `uv`：
+
+```bash
+uv sync
+uv run python -m unittest
+uv run mdstyledocx --list-presets
+uv run mdstyledocx --show-preset-rules gov-cn
+uv run mdstyledocx examples/gov_notice.md -o examples/gov_notice.docx --preset gov-cn
+```
+
+如果不使用 `uv`，也可以用传统方式：
+
+```bash
+pip install -e .
+python3 -m unittest
+mdstyledocx examples/gov_notice.md -o examples/gov_notice.docx --preset gov-cn
+```
+
+## 自定义预设
+
+可以在内置 preset 基础上再叠加一个 JSON 覆盖文件：
+
+```bash
+mdstyledocx input.md -o output.docx --preset gov-cn --preset-file my-preset.json
+```
+
+如果想先看某个模板要求什么 Markdown 写法：
+
+```bash
+mdstyledocx --show-preset-rules gov-cn
+```
+
+示例：
+
+```json
+{
+  "extends": "gov-cn",
+  "styles": {
+    "body": {
+      "line": 520,
+      "line_rule": "exact"
+    },
+    "title": {
+      "size_half_points": 40
+    }
+  }
+}
+```
+
+## Markdown 约定
+
+README 只保留通用约定。某个 preset 的专用写法，以对应的 `preset_specs/*.md` 为准。
+
+通用写法：
+
+```md
+# 关于开展示例工作的通知
+
+各有关单位：
+
+为统一输出格式，现将有关事项通知如下。
+
+## 一、工作目标
+
+1. 统一内容源。
+2. 统一输出格式。
+
+## 二、工作要求
+
+请各单位按要求执行。
+```
+
+## 当前边界
+
+当前版本优先保证：
+
+- 标题、段落、列表、分页可稳定导出
+- 预设版式可复用
+- 产物是标准 `.docx`
+
+暂未覆盖：
+
+- 表格
+- 图片
+- 脚注
+- 复杂嵌套列表
+- 目录自动生成
+
+如果后面继续做，这个工具可以自然扩展成：
+
+- 多个行业 preset 集合
+- frontmatter 驱动的页面元信息
+- 更完整的 Markdown 语法支持
+- GUI 或 Web 包装层

mdstyledocx-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mdstyledocx"
+version = "0.1.0"
+description = "Convert convention-based Markdown into standardized DOCX with reusable style presets."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "YANG Zijie" }]
+license = { text = "MIT" }
+dependencies = [
+    "python-docx>=1.2.0",
+]
+
+[project.scripts]
+mdstyledocx = "mdstyledocx.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mdstyledocx = ["preset_specs/*.json", "preset_specs/*.md"]

mdstyledocx-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mdstyledocx-0.1.0/src/mdstyledocx/__init__.py

@@ -0,0 +1,5 @@
+"""mdstyledocx package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

mdstyledocx-0.1.0/src/mdstyledocx/__main__.py

@@ -0,0 +1,5 @@
+from mdstyledocx.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mdstyledocx-0.1.0/src/mdstyledocx/cli.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from mdstyledocx.docx_writer import build_docx
+from mdstyledocx.markdown import parse_markdown
+from mdstyledocx.presets import list_presets, load_preset, load_preset_rules
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="mdstyledocx",
+        description="Convert convention-based Markdown into standardized DOCX using reusable presets.",
+    )
+    parser.add_argument("input", nargs="?", help="Input Markdown file path, or '-' to read from stdin.")
+    parser.add_argument("-o", "--output", help="Output DOCX file path.")
+    parser.add_argument(
+        "--preset",
+        default="default",
+        help="Built-in preset name. Use --list-presets to inspect available values.",
+    )
+    parser.add_argument(
+        "--preset-file",
+        type=Path,
+        help="Optional JSON override file to extend or replace parts of a preset.",
+    )
+    parser.add_argument(
+        "--list-presets",
+        action="store_true",
+        help="Print built-in presets and exit.",
+    )
+    parser.add_argument(
+        "--show-preset-rules",
+        metavar="PRESET",
+        help="Print the Markdown conventions and style notes for a built-in preset, then exit.",
+    )
+
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    if args.list_presets:
+        for name, description in list_presets():
+            print(f"{name}: {description}")
+        return 0
+
+    if args.show_preset_rules:
+        print(load_preset_rules(args.show_preset_rules).rstrip())
+        return 0
+
+    if not args.input:
+        parser.error("an input Markdown file is required unless --list-presets is used")
+
+    if args.input == "-":
+        markdown_text = sys.stdin.read()
+        if not args.output:
+            parser.error("--output is required when reading Markdown from stdin")
+        output_path = Path(args.output)
+    else:
+        input_path = Path(args.input)
+        markdown_text = input_path.read_text(encoding="utf-8")
+        output_path = Path(args.output) if args.output else input_path.with_suffix(".docx")
+
+    preset = load_preset(args.preset, args.preset_file)
+    base_path = Path.cwd() if args.input == "-" else input_path.parent
+    document = parse_markdown(markdown_text, base_path=base_path)
+    output_path.write_bytes(build_docx(document, preset))
+    print(f"Wrote {output_path} with preset '{preset.name}'")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mdstyledocx-0.1.0/src/mdstyledocx/docx_writer.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+from io import BytesIO
+
+from docx import Document as WordDocument
+from docx.document import Document as WordprocessingDocument
+from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING
+from docx.oxml.ns import qn
+from docx.shared import Pt, Twips
+
+from mdstyledocx.model import Block, Document, ImageSpan, InlineElement, InlineSpan
+from mdstyledocx.presets import Preset, Style
+
+
+@dataclass
+class BuildState:
+    preset: Preset
+    heading_counters: dict[int, int] = field(default_factory=dict)
+
+
+def build_docx(document: Document, preset: Preset) -> bytes:
+    word_document = WordDocument()
+    _configure_document(word_document, preset)
+    _set_core_properties(word_document, _document_title(document))
+
+    state = BuildState(preset=preset)
+    for block in document.blocks:
+        _append_block(word_document, block, state)
+
+    buffer = BytesIO()
+    word_document.save(buffer)
+    return buffer.getvalue()
+
+
+def _configure_document(word_document: WordprocessingDocument, preset: Preset) -> None:
+    section = word_document.sections[0]
+    section.page_width = Twips(preset.page.width)
+    section.page_height = Twips(preset.page.height)
+    section.top_margin = Twips(preset.page.margin_top)
+    section.right_margin = Twips(preset.page.margin_right)
+    section.bottom_margin = Twips(preset.page.margin_bottom)
+    section.left_margin = Twips(preset.page.margin_left)
+    section.header_distance = Twips(preset.page.header)
+    section.footer_distance = Twips(preset.page.footer)
+    section.gutter = Twips(preset.page.gutter)
+
+
+def _set_core_properties(word_document: WordprocessingDocument, title: str) -> None:
+    properties = word_document.core_properties
+    properties.title = title
+    properties.author = "mdstyledocx"
+    properties.last_modified_by = "mdstyledocx"
+    now = datetime.now(timezone.utc).replace(microsecond=0, tzinfo=None)
+    properties.created = now
+    properties.modified = now
+
+
+def _document_title(document: Document) -> str:
+    if document.metadata.get("title"):
+        return document.metadata["title"]
+    for block in document.blocks:
+        if block.kind == "heading" and block.level == 1:
+            return "".join(span.text for span in block.spans if isinstance(span, InlineSpan)).strip()
+    return "Document"
+
+
+def _append_block(word_document: WordprocessingDocument, block: Block, state: BuildState) -> None:
+    if block.kind == "page_break":
+        word_document.add_page_break()
+        return
+
+    rendered_spans = _rendered_spans(block, state)
+    style = _resolve_style(block, state.preset)
+    if _spans_have_image(rendered_spans):
+        style = replace(style, line=240, line_rule="auto")
+
+    paragraph = word_document.add_paragraph()
+    _apply_paragraph_style(paragraph, style)
+
+    if block.kind == "list_item":
+        prefix = "• " if block.list_kind == "bullet" else f"{block.number}. "
+        _add_text_run(paragraph, InlineSpan(text=prefix), style)
+
+    for span in rendered_spans:
+        if isinstance(span, ImageSpan):
+            _add_image_run(paragraph, span, state)
+        elif span.text:
+            _add_text_run(paragraph, span, style)
+
+    if not paragraph.runs:
+        paragraph.add_run("")
+
+
+def _resolve_style(block: Block, preset: Preset) -> Style:
+    if block.kind == "heading":
+        key = {1: "title", 2: "heading1", 3: "heading2"}.get(block.level, "heading3")
+        return preset.styles[key]
+
+    base = preset.styles["body"]
+    if block.kind == "list_item":
+        left_indent = (
+            preset.list_settings.base_left_indent
+            + block.list_level * preset.list_settings.level_step
+        )
+        return replace(
+            base,
+            first_line_indent=0,
+            left_indent=left_indent,
+            hanging=preset.list_settings.hanging,
+        )
+
+    return base
+
+
+def _apply_paragraph_style(paragraph, style: Style) -> None:
+    alignment_map = {
+        "left": WD_ALIGN_PARAGRAPH.LEFT,
+        "center": WD_ALIGN_PARAGRAPH.CENTER,
+        "right": WD_ALIGN_PARAGRAPH.RIGHT,
+        "justify": WD_ALIGN_PARAGRAPH.JUSTIFY,
+        "both": WD_ALIGN_PARAGRAPH.JUSTIFY,
+    }
+    if style.align:
+        paragraph.alignment = alignment_map[style.align]
+
+    paragraph_format = paragraph.paragraph_format
+    paragraph_format.space_before = Twips(style.spacing_before)
+    paragraph_format.space_after = Twips(style.spacing_after)
+    paragraph_format.left_indent = Twips(style.left_indent)
+
+    if style.hanging:
+        paragraph_format.first_line_indent = Twips(-style.hanging)
+    else:
+        paragraph_format.first_line_indent = Twips(style.first_line_indent)
+
+    if style.line_rule == "exact":
+        paragraph_format.line_spacing = Pt(style.line / 20)
+        paragraph_format.line_spacing_rule = WD_LINE_SPACING.EXACTLY
+    elif style.line_rule == "auto":
+        paragraph_format.line_spacing = style.line / 240
+    else:
+        paragraph_format.line_spacing = style.line / 240
+
+
+def _add_text_run(paragraph, span: InlineSpan, style: Style) -> None:
+    run = paragraph.add_run(span.text)
+    font_ascii = style.font_ascii
+    font_east_asia = style.font_east_asia
+    bold = style.bold or span.bold
+    italic = style.italic or span.italic
+
+    if span.code:
+        font_ascii = "Consolas"
+        font_east_asia = "等线"
+
+    run.font.name = font_ascii
+    run.font.size = Pt(style.size_half_points / 2)
+    run.bold = bold
+    run.italic = italic
+
+    r_fonts = run._element.get_or_add_rPr().get_or_add_rFonts()
+    r_fonts.set(qn("w:ascii"), font_ascii)
+    r_fonts.set(qn("w:hAnsi"), font_ascii)
+    r_fonts.set(qn("w:eastAsia"), font_east_asia)
+
+
+def _add_image_run(paragraph, span: ImageSpan, state: BuildState) -> None:
+    run = paragraph.add_run()
+    inline_shape = run.add_picture(span.path)
+    max_width = _max_image_width(state.preset)
+    if inline_shape.width > max_width:
+        scale = max_width / inline_shape.width
+        inline_shape.width = max_width
+        inline_shape.height = int(inline_shape.height * scale)
+
+    description = span.alt_text or os.path.basename(span.path)
+    inline_shape._inline.docPr.set("descr", description)
+    inline_shape._inline.docPr.set("name", description)
+
+
+def _max_image_width(preset: Preset) -> int:
+    return Twips(preset.page.width - preset.page.margin_left - preset.page.margin_right)
+
+
+def _spans_have_image(spans: list[InlineElement]) -> bool:
+    return any(isinstance(span, ImageSpan) for span in spans)
+
+
+def _rendered_spans(block: Block, state: BuildState) -> list[InlineElement]:
+    if block.kind != "heading":
+        return block.spans
+
+    scheme = state.preset.heading_numbering.get(block.level)
+    if not scheme:
+        return block.spans
+
+    _advance_heading_counters(state, block.level)
+    if _has_number_prefix(block.spans, scheme):
+        return block.spans
+
+    prefix = _format_heading_prefix(scheme, state.heading_counters[block.level])
+    return [InlineSpan(text=prefix)] + block.spans
+
+
+def _advance_heading_counters(state: BuildState, level: int) -> None:
+    state.heading_counters[level] = state.heading_counters.get(level, 0) + 1
+    for deeper_level in list(state.heading_counters):
+        if deeper_level > level:
+            state.heading_counters[deeper_level] = 0
+
+
+def _has_number_prefix(spans: list[InlineElement], scheme: str) -> bool:
+    text = "".join(span.text for span in spans if isinstance(span, InlineSpan)).lstrip()
+    patterns = {
+        "cn-section": r"^[一二三四五六七八九十百千万零〇两]+、",
+        "cn-paren": r"^（[一二三四五六七八九十百千万零〇两]+）",
+        "arabic-dot": r"^\d+[.．]\s*",
+    }
+    return re.match(patterns[scheme], text) is not None
+
+
+def _format_heading_prefix(scheme: str, number: int) -> str:
+    if scheme == "cn-section":
+        return f"{_to_chinese_number(number)}、"
+    if scheme == "cn-paren":
+        return f"（{_to_chinese_number(number)}）"
+    if scheme == "arabic-dot":
+        return f"{number}. "
+    raise ValueError(f"Unsupported heading numbering scheme: {scheme}")
+
+
+def _to_chinese_number(number: int) -> str:
+    digits = "零一二三四五六七八九"
+    units = ["", "十", "百", "千"]
+    raw = str(number)
+    parts: list[str] = []
+
+    for index, char in enumerate(raw):
+        digit = int(char)
+        unit_index = len(raw) - index - 1
+        if digit == 0:
+            if parts and parts[-1] != "零" and any(next_char != "0" for next_char in raw[index + 1 :]):
+                parts.append("零")
+            continue
+        if not (digit == 1 and unit_index == 1 and not parts and len(raw) == 2):
+            parts.append(digits[digit])
+        parts.append(units[unit_index])
+
+    return "".join(parts) or "零"