Contents

1amageek/remark

Convert HTML to beautiful Markdown with ease! ✨ Remark is a Swift library and command-line tool designed to parse HTML content into Markdown, with support for extracting Open Graph (OG) metadata and front matter generation. Perfect for static site generators and Markdown-based ap

✨ Features

  • 📝 HTML to Markdown Conversion: Convert HTML elements to clean, readable Markdown
  • 🌐 Open Graph (OG) Data Extraction: Extract social media tags automatically
  • 📋 Front Matter Generation: Generate front matter with title, description, and OG metadata
  • 🎯 Smart Indentation: Perfect handling of nested lists and quotes
  • 🔗 URL Resolution: Automatically resolves relative URLs to absolute URLs
  • 🎨 Intelligent Link Text: Prioritizes accessibility with aria-label > img[alt] > title > text

🚀 Installation

📚 As a Library (Swift Package Manager)

Add Remark to your Package.swift: 

dependencies: [
    .package(url: "https://github.com/1amageek/Remark.git", branch: "main")
]

💻 As a Command Line Tool

🍃 Using Mint (Recommended)

Mint is the easiest way to install Swift command line tools! 🚀

mint install 1amageek/Remark

That's it! Now you can use remark from anywhere! ✨

🛠 Using Make
  1. Clone the repo and move into it:
git clone https://github.com/1amageek/Remark.git
cd Remark
  1. Install with make:
make install

Want a custom location? No problem! 🎯

PREFIX=/your/custom/path make install
🔧 Manual Installation
  1. Clone the repo 📦
  2. Build release version:
swift build -c release
  1. Copy to your bin:
cp .build/release/remark /usr/local/bin/remark

🎮 Usage

🖥 Command Line Interface

Convert HTML from any URL to Markdown: ✨

remark https://example.com

Include the fancy front matter: 📋

remark --include-front-matter https://example.com

Just the plain text, please! 📝

remark --plain-text https://example.com

📚 Library Usage

Here's a quick example to get you started! 🚀

import Remark

let htmlContent = """
<!DOCTYPE html>
<html>
<head>
    <title>My Amazing Page ✨</title>
    <meta name="description" content="Something awesome!">
    <meta property="og:image" content="https://example.com/cool.jpg">
</head>
<body>
    <h1>Welcome! 🎉</h1>
    <p>This is <strong>amazing</strong> content.</p>
</body>
</html>
"""

do {
    let remark = try Remark(htmlContent)
    print("✨ Title:", remark.title)
    print("📝 Description:", remark.description)
    print("🌐 OG Data:", remark.ogData)
    print("📄 Markdown:\n", remark.page)
} catch {
    print("❌ Error:", error)
}

🎨 Example Output

Your HTML becomes beautiful Markdown:

---
title: "My Amazing Page ✨"
description: "Something awesome!"
og_image: "https://example.com/cool.jpg"
---

# Welcome! 🎉

This is **amazing** content.

🛠 Development

🏗 Building

make build      # 🚀 Release build
make debug      # 🔍 Debug build

🧪 Testing

make test       # 🎯 Run tests

🧹 Cleaning

make clean      # 🧹 Clean build artifacts

📦 Dependencies

make update     # 🔄 Update all dependencies
make resolve    # 🎯 Resolve dependencies

🧪 Tests

Here's an example test for OGP extraction using Swift Testing:

import Testing
@testable import Remark

@Test("OGP data extraction")
func testOGPDataExtraction() throws {
    let htmlContent = """
    <meta property="og:image" content="https://example.com/cool.jpg" />
    <meta property="og:title" content="Amazing Page ✨" />
    """

    let remark = try Remark(htmlContent)
    #expect(remark.ogData["og_image"] == "https://example.com/cool.jpg")
    #expect(remark.ogData["og_title"] == "Amazing Page ✨")
}

🌟 Contributing

Love Remark? Want to make it better? Contributions are welcome! 🎉

  1. 🍴 Fork it
  2. 🔨 Make your changes
  3. 🧪 Test them
  4. 🎯 Send a PR

📝 License

Remark is available under the MIT license. See the LICENSE file for more info. ✨

Package Metadata

Repository: 1amageek/remark

Default branch: main

README: README.md