1amageek/Remark

Convert HTML to Markdown with OG metadata extraction and front matter generation 🎨✨

✨ 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

Clone the repo and move into it:

git clone https://github.com/1amageek/Remark.git
cd Remark

Install with make:

make install

Want a custom location? No problem! 🎯

PREFIX=/your/custom/path make install

🔧 Manual Installation

Clone the repo 📦
Build release version:

swift build -c release

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! 🎉

🍴 Fork it
🔨 Make your changes
🧪 Test them
🎯 Send a PR

📝 License

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

Package Metadata

Repository: 1amageek/Remark

Homepage: https://github.com/1amageek/Remark

Stars: 5

Forks: 2

Open issues: 0

Default branch: main

Primary language: swift

Topics: front-matter, html, markdown, ogp, swift

README: README.md