markdownpal 0.1.0__tar.gz

markdownpal-0.1.0/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(python:*)",
+      "Bash(.venv/bin/pip install:*)",
+      "Bash(/Users/hanchaoran/Documents/yeyecha/markdownpal/.venv/bin/pip install:*)",
+      "Bash(/Users/hanchaoran/Documents/yeyecha/markdownpal/.venv/bin/python:*)",
+      "Bash(python3:*)",
+      "Bash(.venv/bin/pytest:*)"
+    ]
+  }
+}

markdownpal-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.idea/
+dist/
+*.egg-info/
+.DS_Store

markdownpal-0.1.0/EXAMPLES.md

@@ -0,0 +1,201 @@
+# MarkdownPal Examples
+
+## Quick Start
+
+```python
+from markdownpal import Document
+from markdownpal.blocks import H1Block, TextBlock
+from markdownpal.inline import bold
+
+doc = Document()
+doc.append(H1Block("Hello, MarkdownPal"))
+doc.append(TextBlock(f"Build {bold('Markdown')} files with Python."))
+doc.save("output.md")
+```
+
+---
+
+## Block Types
+
+### Headings
+
+```python
+from markdownpal.blocks import H1Block, H2Block, H3Block, H4Block, H5Block, H6Block
+
+doc.append(H1Block("Title"))        # # Title
+doc.append(H2Block("Section"))      # ## Section
+doc.append(H3Block("Subsection"))   # ### Subsection
+doc.append(H4Block("Detail"))       # #### Detail
+doc.append(H5Block("Minor"))        # ##### Minor
+doc.append(H6Block("Tiny"))         # ###### Tiny
+```
+
+### Text & Formatting
+
+```python
+from markdownpal.blocks import TextBlock, QuoteBlock, HRBlock, CommentBlock
+from markdownpal.inline import bold, italic, code, strikethrough
+
+doc.append(TextBlock("Plain paragraph."))
+doc.append(TextBlock(f"{bold('Bold')}, {italic('italic')}, {code('inline code')}, {strikethrough('struck')}."))
+doc.append(QuoteBlock("A quote that spans\nmultiple lines."))
+doc.append(HRBlock())
+doc.append(CommentBlock("This comment is invisible in rendered output."))
+```
+
+### Code
+
+```python
+from markdownpal.blocks import CodeBlock
+
+doc.append(CodeBlock("print('hello world')", lang="python"))
+doc.append(CodeBlock("SELECT * FROM users;", lang="sql"))
+doc.append(CodeBlock("plain code block, no highlighting"))
+```
+
+### Lists
+
+```python
+from markdownpal.blocks import ULBlock, OLBlock, TaskListBlock
+
+doc.append(ULBlock(["Apples", "Bananas", "Cherries"]))
+
+doc.append(OLBlock(["Install", "Configure", "Run"]))
+
+doc.append(TaskListBlock([
+    ("Write tests", True),
+    ("Write code", True),
+    ("Deploy", False),
+]))
+```
+
+### Table
+
+```python
+from markdownpal.blocks import TableBlock
+
+doc.append(TableBlock(
+    headers=["Name", "Role", "Status"],
+    rows=[
+        ["Alice", "Engineer", "✅ Active"],
+        ["Bob",   "Designer", "✅ Active"],
+        ["Carol", "PM",       "🔄 Onboarding"],
+    ]
+))
+```
+
+### Images & Links
+
+```python
+from markdownpal.blocks import ImageBlock, LinkBlock
+
+doc.append(ImageBlock(src="https://example.com/logo.png", alt="Project Logo"))
+doc.append(ImageBlock(src="diagram.png"))  # alt is optional
+doc.append(LinkBlock(text="Documentation", url="https://example.com/docs"))
+```
+
+---
+
+## Inline Helpers
+
+Inline helpers return strings and can be composed or embedded inside any block content:
+
+```python
+from markdownpal.inline import bold, italic, code, strikethrough
+
+bold("important")            # **important**
+italic("note")               # *note*
+code("os.path.join()")       # `os.path.join()`
+strikethrough("deprecated")  # ~~deprecated~~
+
+# Composable
+bold(italic("emphasis"))     # ***emphasis***
+
+# Embed in blocks
+TextBlock(f"See {code('render()')} for details.")
+H2Block(f"API {italic('Reference')}")
+```
+
+---
+
+## Render to String
+
+Use `render()` to get the Markdown string directly without saving to disk:
+
+```python
+doc = MarkdownDocument()
+doc.append(H1Block("Report"))
+doc.append(TextBlock("Generated automatically."))
+
+output = doc.render()
+print(output)
+# # Report
+#
+# Generated automatically.
+```
+
+---
+
+## Save to File
+
+```python
+doc.save("report.md")              # relative path
+doc.save("/tmp/docs/report.md")    # absolute path
+```
+
+Files are written in UTF-8 and fully support international characters and emoji:
+
+```python
+doc.append(H1Block("项目文档"))
+doc.append(TextBlock("支持中文、日本語、한국어 및 emoji 🎉"))
+doc.save("国际化.md")
+```
+
+---
+
+## Complete Example
+
+```python
+from markdownpal import Document
+from markdownpal.blocks import (
+    H1Block, H2Block, H3Block,
+    TextBlock, CodeBlock, TableBlock,
+    ULBlock, TaskListBlock, HRBlock,
+)
+from markdownpal.inline import bold, italic, code
+
+doc = Document()
+
+doc.append(H1Block("Project Changelog"))
+doc.append(TextBlock(f"All notable changes are documented here. Format based on {bold('Keep a Changelog')}."))
+doc.append(HRBlock())
+
+doc.append(H2Block("v1.2.0 — 2026-04-12"))
+doc.append(H3Block("Added"))
+doc.append(ULBlock([
+    f"{code('TaskListBlock')} for checkbox lists",
+    "UTF-8 file output via save()",
+    "Inline helpers: bold, italic, code, strikethrough",
+]))
+
+doc.append(H3Block("Fixed"))
+doc.append(ULBlock([
+    f"{code('QuoteBlock')} now correctly handles multi-line text",
+]))
+
+doc.append(H2Block("Compatibility"))
+doc.append(TableBlock(
+    headers=["Python", "Supported"],
+    rows=[
+        ["3.9", "✅"],
+        ["3.10", "✅"],
+        ["3.11", "✅"],
+        ["3.12", "✅"],
+    ]
+))
+
+doc.append(H2Block("Installation"))
+doc.append(CodeBlock("pip install markdownpal", lang="bash"))
+
+doc.save("CHANGELOG.md")
+```

markdownpal-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rogerstacker
+
+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.

markdownpal-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: markdownpal
+Version: 0.1.0
+Summary: A pure-Python library for programmatically generating Markdown files.
+Project-URL: Homepage, https://github.com/rogerstacker/markdownpal
+Project-URL: Repository, https://github.com/rogerstacker/markdownpal
+Project-URL: Bug Tracker, https://github.com/rogerstacker/markdownpal/issues
+Author-email: Rogerstacker <rogerstacker3rd@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Rogerstacker
+        
+        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.
+License-File: LICENSE
+Keywords: builder,document,generator,markdown
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MarkdownPal
+
+A pure-Python library for programmatically generating Markdown (`.md`) files via a clean, block-based document builder API.
+
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## Features
+
+- **Block-based API** — compose documents from typed, self-contained block objects
+- **Inline formatting helpers** — `bold()`, `italic()`, `code()`, `strikethrough()`
+- **Full block support** — headings, paragraphs, quotes, code, lists, tables, images, links
+- **Save to file** — UTF-8 output with full support for international characters and emoji
+- **Zero dependencies** — no third-party packages required
+- **Python 3.9+**
+
+---
+
+## Installation
+
+```bash
+pip3 install markdownpal
+```
+
+---
+
+## Quick Start
+
+```python
+from markdownpal import Document
+from markdownpal.blocks import H1Block, H2Block, TextBlock, CodeBlock, ULBlock
+from markdownpal.inline import bold
+
+doc = Document()
+
+doc.append(H1Block("My Project"))
+doc.append(TextBlock(f"A {bold('simple')} example of MarkdownPal."))
+doc.append(H2Block("Installation"))
+doc.append(CodeBlock("pip install markdownpal", lang="bash"))
+doc.append(H2Block("Features"))
+doc.append(ULBlock(["Zero dependencies", "Clean API", "Python 3.9+"]))
+
+doc.save("output.md")
+```
+
+Output (`output.md`):
+
+```markdown
+# My Project
+
+A **simple** example of MarkdownPal.
+
+## Installation
+
+```bash
+pip install markdownpal
+```
+
+## Features
+
+- Zero dependencies
+- Clean API
+- Python 3.9+
+```
+
+---
+
+## Block Reference
+
+### Headings
+
+```python
+from markdownpal.blocks import H1Block, H2Block, H3Block, H4Block, H5Block, H6Block
+
+doc.append(H1Block("Title"))       # # Title
+doc.append(H2Block("Section"))     # ## Section
+doc.append(H3Block("Subsection"))  # ### Subsection
+```
+
+### Text
+
+```python
+from markdownpal.blocks import TextBlock, QuoteBlock, HRBlock, CommentBlock
+
+doc.append(TextBlock("A plain paragraph."))
+doc.append(QuoteBlock("A blockquote.\nSpanning multiple lines."))
+doc.append(HRBlock())                               # ---
+doc.append(CommentBlock("Hidden in rendered output."))  # <!-- ... -->
+```
+
+### Code
+
+```python
+from markdownpal.blocks import CodeBlock
+
+doc.append(CodeBlock("print('hello')", lang="python"))
+doc.append(CodeBlock("SELECT * FROM users;", lang="sql"))
+doc.append(CodeBlock("no language specified"))
+```
+
+### Lists
+
+```python
+from markdownpal.blocks import ULBlock, OLBlock, TaskListBlock
+
+doc.append(ULBlock(["Apples", "Bananas", "Cherries"]))
+
+doc.append(OLBlock(["Install", "Configure", "Run"]))
+
+doc.append(TaskListBlock([
+    ("Write tests", True),
+    ("Write code", True),
+    ("Deploy",      False),
+]))
+```
+
+### Table
+
+```python
+from markdownpal.blocks import TableBlock
+
+doc.append(TableBlock(
+    headers=["Name", "Role", "Status"],
+    rows=[
+        ["Alice", "Engineer", "Active"],
+        ["Bob",   "Designer", "Active"],
+    ]
+))
+```
+
+### Images & Links
+
+```python
+from markdownpal.blocks import ImageBlock, LinkBlock
+
+doc.append(ImageBlock(src="logo.png", alt="Project Logo"))
+doc.append(LinkBlock(text="Documentation", url="https://example.com/docs"))
+```
+
+---
+
+## Inline Helpers
+
+Inline helpers return plain strings and can be embedded inside any block content:
+
+```python
+from markdownpal.inline import bold, italic, code, strikethrough
+
+bold("important")            # **important**
+italic("note")               # *note*
+code("os.path.join()")       # `os.path.join()`
+strikethrough("deprecated")  # ~~deprecated~~
+
+# Composable
+bold(italic("emphasis"))     # ***emphasis***
+
+# Embed in blocks
+doc.append(TextBlock(f"Call {code('render()')} to get the output string."))
+```
+
+---
+
+## Document API
+
+```python
+doc = Document()
+doc.append(block)   # Add a Block instance
+doc.render()        # Returns the full Markdown string
+doc.save("out.md")  # Writes UTF-8 Markdown file to disk
+```
+
+`append()` raises `TypeError` if the argument is not a `Block` instance.  
+`render()` joins all blocks with a blank line (`\n\n`) between them.
+
+---
+
+## Project Structure
+
+```
+markdownpal/
+├── __init__.py          # Top-level public API
+├── document.py          # Document class
+├── inline.py            # Inline format helpers
+└── blocks/
+    ├── base.py          # Block abstract base class
+    ├── heading.py       # H1Block ~ H6Block
+    ├── text.py          # TextBlock, QuoteBlock, HRBlock, CommentBlock
+    ├── code.py          # CodeBlock
+    ├── list_.py         # ULBlock, OLBlock, TaskListBlock
+    ├── table.py         # TableBlock
+    └── media.py         # ImageBlock, LinkBlock
+```
+
+---
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/rogerstacker/markdownpal.git
+cd markdownpal
+
+# Install dev dependencies
+pip3 install -e ".[dev]"
+
+# Run tests
+pytest
+```
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 Rogerstacker