C++ (17+) için yüksek performanslı ve kolay kullanımlı HTML -> Markdown Dönüşüm kütüphanesi

    8 Ekim 2025
    9 görüntüleme

    Github Repository: https://github.com/leventkaragol/libcpp-html-to-md

    linux windows

    Amaç

    Yapay Zeka çağında, verinin kalitesi ve formatı, algoritmanın kendisi kadar kritik bir hale geldi. Özellikle Retrieval-Augmented Generation (RAG) gibi sistemlerin başarısı, temel dil modellerine (LLM) sunulan bilginin ne kadar temiz ve anlamlı olduğuna doğrudan bağlıdır. Ham HTML, semantik zenginliğine rağmen, LLM'ler için bir 'gürültü' kaynağıdır; sayısız etiket, script ve stil bilgisi, asıl metnin özünü gölgeler. libcpp-html-to-md kütüphanesini, bu stratejik ihtiyaca cevap vermek için, yüksek performanslı bir C++ çözümü olarak geliştirmeye çalıştım. Kütüphanenin temel amacı, HTML'in yapısal kaosunu, LLM'lerin en verimli şekilde işleyebileceği temiz, yapılandırılmış ve anlamlı bir Markdown formatına dönüştürerek RAG sistemleri için besleme (ingestion) süreçlerini optimize etmektir.

    Projeye Nasıl Eklenir?

    Bu header-only bir kütüphanedir. Yani aslında tek yapmanız gereken src klasöründeki libcpp-html-to-md.hpp dosyasını projenize eklemek ve #include ile kullanmaya başlamaktır.

    Ancak bu kütüphane, arka planda libxml2 kütüphanesini kullanır. Dolayısıyla, kullanmadan önce projenize libxml2 kütüphanesini eklemeniz gerekir.

    Kullanım örneklerini Github Repository'deki "examples" klasöründe bulabilirsiniz. Aşağıda örnek bir CMakeLists.txt dosyası içeriği de bulabilirsiniz.

    cmake_minimum_required(VERSION 3.14)

project(myProject)

find_package(libxml2 REQUIRED)

add_executable(myProject main.cpp libcpp-html-to-md.hpp)

target_include_directories(myProject PRIVATE ${LIBXML2_INCLUDE_DIR})

target_link_libraries(myProject PRIVATE ${LIBXML2_LIBRARIES})
    İpucu!
    Kütüphaneyi Windows'ta çalıştırmak için Iconv kütüphanesine de ihtiyaç vardır. Github'daki examples klasöründeki CMakeLists.txt dosyası, her iki platformda da çalışmak için gerekli eklentileri içerir.

    Nasıl Kullanılır?

    "MarkdownConverter" sınıfının "convert" metodunu çağırarak, string değişkeninde yer alan HTML içeriğini herhangi bir özelleştirmeye gerek kalmadan Markdown formatına dönüştürebilirsiniz.

    #include "libcpp-html-to-md.hpp"

using namespace lklibs;

int main() {

    const auto htmlContent = R"(
    <html>
        <head>
            <title>Test</title>
        </head>
        <body>
            <h1>Simple H1 Header</h1>
            <p>Simple Paragraph</p>
            <h2>Another H2 Header</h2>
            <ol>
                <li>First item</li>
                <li>Second item</li>
            </ol>

            <table>
                <tr>
                    <td>Row 1, Cell 1</td>
                    <td>Row 1, Cell 2</td>
                </tr>
                <tr>
                    <td>Row 2, Cell 1</td>
                    <td>Row 2, Cell 2</td>
                </tr>
            </table>
        </body>
    </html>
    )";

    MarkdownConverter mdConverter(htmlContent);

    const auto markdownContent = mdConverter.convert();

    std::cout << markdownContent << std::endl;

    return 0;
}

    Semantik Versiyonlama

    Kütüphanenin sürümlemesi, geleneksel semantik versiyonlama kullanılarak yapılır. Buna göre, MAJOR.MINOR.PATCH biçiminde yapılan sürümlemede;

    PATCH: Olası hata düzeltmeleri ve iyileştirmeleri içerir. Bunu mutlaka edinmek istersiniz.

    MINOR: Geriye dönük uyumluluk sayesinde eklenen ek işlevler. Muhtemelen bunu edinmek istersiniz, zararı olmaz.

    MAJOR: Geriye dönük uyumluluğu bozan ek işlevler. Nelerin değiştiğini anlamanız ve muhtemelen kendi kodunuzda değişiklik yapmanız gerekecek. Böyle bir şey yayınlarsam, geçiş için gereken değişiklikleri kesinlikle dokümana eklerim.

    Lisans

    Proje MIT lisansı ile lisanslanmıştır. Ticari kullanıma uygundur. Tam metni aşağıda bulabilirsiniz.

    MIT License

Copyright (c) 2024 Levent KARAGÖL

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.

    İletişim

    Kütüphaneyle ilgili sorun yaşıyorsanız, lütfen GitHub'da bir konu açın. Lütfen isteğinizi, sorununuzu veya sorunuzu olabildiğince ayrıntılı bir şekilde açıklayın ve derleyicinizin, işletim sisteminizin ve kullandığınız kütüphanenin sürümünü de belirtin. Yeni bir konu açmadan önce, lütfen konunun daha önce kapatılmış konularda bulunmadığından emin olun.

    Yazar: Levent KARAGÖL

    Makaleyi Paylaş: