[Web] README.md 파일 HTML 형식으로 렌더링하기(markdown → HTML)

티스토리 뷰

Web

[Web] README.md 파일 HTML 형식으로 렌더링하기(markdown → HTML)

Assum 2023. 5. 15. 14:09

728x90

안녕하세요🐾

커스텀 라이브러리 배포 작업 진행 중 깃허브 라이브러리 페이지처럼 HTML 내에 README.md 파일을 표시 해야할 일이 생겼습니다.

CDN을 이용해 HTML 파일 내에서 마크다운 파일을 렌더링하는 방식으로 문제를 해결하게 되었고 그 과정을 공유하려 합니다.

알아볼까요? 😎

1. HTML 설정

저는 Visual Studio Code를 이용하였습니다. 마크다운 뷰어의 기능도 제공하고 제한적이지만 웹 환경에서의 테스트도 병행 할 수 있어 추천합니다.

비주얼스튜디오코드에서 html 파일을 만들고 html:5 를 입력하면, HTML의 기본 구조를 만들어 줍니다.

2. CDN 및 태그 설정

md-block을 이용하여 CDN을 설정하였습니다. md-block은 마크다운을 HTML로 랜더링하는 컴포넌트입니다.

이용방법은 아래의 코드 예제처럼 <haed> 태그 사이 md-block이라는 주석 밑에 보이는 스크립트 코드 한줄을 삽입합니다.

그 다음 <body> 태그 내에 <md-block> 태그를 선언하여 그 사이에 마크다운을 입력하면 됩니다.

저는 md-block의 API 문서를 보니 <md-block> 태그에 src 속성으로 마크다운 파일을 직접 지정 할 수 있는 기능이 있어 이 방법을 이용하였습니다.

src의 경로를 보니 html과 README.md 파일은 하나의 디렉토리에 같이 넣어주어야겠죠?

예제로 사용될 README.md 파일은 이곳을 이용하였습니다.

HTML 코드와 예제로 쓰일 READEME.md 파일은 아래와 같습니다.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    
    <!-- md-block -->
    <script type="module" src="https://md-block.verou.me/md-block.js"></script>
</head>
<body>
    <div class="markdown-body">
        <md-block src="./README.md">
            <!-- README.md 로드 실패시 보이는 문구 -->
            `README.md` was *not* found
        </md-block>
    </div>
</body>
</html>

3. 실행 환경 설정

이제 작성된 html 실행 해보면 에러를 만나게 됩니다. :)

요약하자면 CORS policy에 위반되었다는 내용입니다. CORS policy 위반에 대한 케이스는 여러가지이지만, 이 상황인 경우

http, https 환경에서 실행되지 않은 html에서 src를 사용해 파일을 로드하려하면 생기는 에러입니다.

그렇다면 html을 로컬이 아닌 웹 환경에서 실행하면 테스트를 해 볼 수 있겠죠?

간단합니다. Visual Studio Code - Extension - Live Server를 설치해주세요.😎

설치가 완료되었다면 html 코드 영역에서 마우스 우클릭을 한 뒤 Open with Live Server을 눌러 웹 환경에서 html 파일을 실행합니다.

마크다운 파일의 HTML 렌더링이 완료되어 화면에 표시되었습니다.

음 그런데.. 결과 화면이 뭔가 밋밋하죠? 마크다운 뷰어로 보이는 모습과 너무 다릅니다.

HTML로 렌더링은 되었지만 마크다운 형식의 디자인(.css)이 빠진 결과물이 나왔다면 .css를 찾아 적용하면 되겠죠?

HTML 헤더 사이에 깃허브 마크다운 형식의 css도 추가해봅시다.

<head>
    ...
    
    <!-- github-markdown-light 테마 -->
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.2.0/github-markdown-light.css" integrity="sha512-n5zPz6LZB0QV1eraRj4OOxRbsV7a12eAGfFcrJ4bBFxxAwwYDp542z5M0w24tKPEhKk2QzjjIpR5hpOjJtGGoA==" crossorigin="anonymous" referrerpolicy="no-referrer" />
    <!-- github-markdown-light 테마 -->
    
    ...
</head>

다시 실행해보면 확연히 달라진 디자인을 볼 수 있습니다.

저는 light 테마를 썼지만, 어두운 느낌을 원한다면 github-markdown-css 라이브러리 페이지에서 dark 테마를 찾아 넣으시면 됩니다.

다시 실행해볼까요?

여기서 끝! 마쳐도 되지만 한가지 아쉬운 부분이 있습니다.

README.md 파일 내의 코드 블럭 부분이 HTML로 렌더링 될 때 <code> 태그로 변환되어 들어가게 되는데요.

아래의 이미지처럼 언어에 따른 부분 강조 처리나 색상 표시 부분이 몽땅 빠져 공허한 느낌이 듭니다.

개발자에게 색깔 없는 코드블록은 상당히 보기 괴롭습니다.

마지막으로 렌더링된 코드블록을 알록달록하게 꾸며줄 prism이라는 CDN을 하나 더 추가하도록 하겠습니다.

아래의 코드처럼 head 사이와 body 블록끝에 prism 스크립트를 한줄씩만 넣어주면 완성입니다.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <!-- github-markdown-light -->
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.2.0/github-markdown-light.css" integrity="sha512-n5zPz6LZB0QV1eraRj4OOxRbsV7a12eAGfFcrJ4bBFxxAwwYDp542z5M0w24tKPEhKk2QzjjIpR5hpOjJtGGoA==" crossorigin="anonymous" referrerpolicy="no-referrer" />
    <!-- github-markdown-light -->
    <!-- prism code theme -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/hi098123/prism-for-tistory/prism.css">
    <!-- prism code theme -->
    <!-- prism.js에 포함된 언어 - 티스토리 기본 에디터 언어 목록들 -->
    <!--
        HTML
        CSS
        Javasvript
        Python
        Java
        C++
        Kotlin
        Swift
        PHP
        GO
    -->

    <script type="module" src="https://md-block.verou.me/md-block.js"></script>
    <title>Document</title>
</head>
<body>
    <div class="markdown-body">
        <md-block src="./README.md">
            `README.md` was *not* found
        </md-block>
    </div>
    <script src="https://cdn.jsdelivr.net/gh/hi098123/prism-for-tistory/prism.js"></script>
</body>
</html>

주석을 참고하시면 제가 사용한 prism.js 버전은 티스토리에서 기본 제공하는 코드블록 컴포넌트입니다.

지원되는 언어는 주석에 나타낸 것들이며, 저 언어 이외에 다른 언어의 코드블록을 나타내려면 prism에서 지원되는 CDN을 찾아 추가해 주시면 됩니다!

이제 완성된 HTML 코드를 Open with Live Server를 통해 실행해보면 알록달록한 코드블록을 볼 수 있습니다.