Skip to content
BranchesTags
 
 

Repository files navigation

Flytothesky MarkTL HTML Exporter

YouTube: 배움의 달인 X: @reallygood83

Flytothesky MarkTL HTML Exporter is a Flytothesky-maintained fork of MarkTL. It keeps the original MarkTL name and credit while carrying Flytothesky-specific setup, workflow, and runtime refinements.

It is inspired by the idea that HTML is often a better medium than Markdown for reviewing long AI-generated notes, strategy documents, research reports, decision memos, and interactive explainers.

English

Purpose

Markdown is excellent for writing, but long Markdown notes are often hard to read, compare, present, or share. MarkTL helps you convert the active Obsidian note into a purpose-built HTML artifact with stronger visual structure, optional AI transformation, internal preview, and share preparation.

MarkTL is not just a "pretty Markdown exporter." The goal is to help you create HTML artifacts that have a job: help someone read, decide, review, compare, tune, explain, publish, and then bring the result back into an AI session.

The core idea is simple:

Markdown is where you write. HTML is where an AI-made artifact can become a small interactive surface.

MarkTL artifacts are designed to be:

  • easier to read than long Markdown files
  • visually structured with sections, cards, tables, and navigation
  • interactive when trusted, with local controls, captured state, and copy-back-to-AI prompts
  • optionally transformed by AI into strategy briefs, research reports, decision memos, explainers, or slide-like documents
  • previewable inside Obsidian
  • exportable as self-contained static HTML
  • prepared for sharing through local links or static hosting bundles

What It Does

  • Opens an export modal from the ribbon icon or command palette.
  • Opens a setup wizard on first run so beginners can choose local export, Claude, Codex, or share-ready bundles.
  • Lets you choose the artifact goal, artifact type, template, AI provider, conversion mode, preview security, and sharing behavior.
  • Converts the currently active Markdown note into HTML.
  • Saves the result to a vault folder, defaulting to html-exports/.
  • Opens the generated HTML in an internal Obsidian preview pane.
  • Shows a progress modal so you can see whether AI or local fallback produced the result.
  • Works without AI through local Markdown-to-HTML conversion.
  • Supports AI conversion through verified providers:
    • Claude Code CLI
    • Codex CLI
  • Creates static hosting bundles for GitHub Pages, S3/R2, Netlify, Vercel, or any static host.

Artifact Goals

Start with what the HTML should do:

  • Readable artifact: make a long note easier to read, navigate, and share.
  • Decision room: extract the question, options, criteria, tradeoffs, risks, recommendation, and decision log.
  • Review room: help readers leave structured feedback and copy it back into Claude/Codex.
  • Compare options: lay out alternatives side by side with scorecards and tradeoff summaries.
  • Prompt playground: create editable controls and copyable state for the next AI iteration.
  • PR / code explainer: explain code, diffs, plans, risks, and reviewer checklists.
  • Public article: prepare a polished hosted page with social-preview-friendly framing.

Artifact Types

Choose an artifact type in the export modal:

  • Faithful Note: preserve the note while improving readability.
  • Strategy Brief: TL;DR, context, options, tradeoffs, risks, recommendation, next actions.
  • Research Report: abstract, findings, evidence, implications, source notes.
  • Decision Memo: question, criteria, options, comparison matrix, recommendation, dissenting view.
  • Interactive Explainer: progressive disclosure, copy buttons, local-only controls.
  • Slide Deck: sectioned, slide-like reading flow with one idea per section.

Templates

Included templates:

  • minimal
  • editorial
  • deck
  • dashboard
  • investor-brief
  • research-memo
  • interactive-report
  • playground

interactive-report can include trusted-mode interactive controls such as progress, generated TOC, collapsible sections, "copy as prompt", "copy as markdown", and "copy summary". playground adds an editable working-notes area, an emphasis slider, "copy prompt", and "copy state JSON" so the HTML file can act as a small review interface.

How To Install With BRAT

  1. Install the Obsidian BRAT plugin.
  2. Open BRAT settings.
  3. Choose Add Beta plugin.
  4. Paste this repository URL:
https://github.com/flytothesky23/marktl
  1. Enable Flytothesky MarkTL HTML Exporter in Obsidian community plugin settings.

Agent-Assisted Setup With Codex Or Claude Code

Many users install and configure tools by asking Codex or Claude Code to walk them through the process. MarkTL is designed for that workflow.

Open Flytothesky MarkTL setup in Obsidian and use:

  • Copy Codex setup prompt
  • Copy Claude setup prompt

Paste the copied prompt into Codex or Claude Code. The agent should help you:

  • install MarkTL through BRAT
  • choose Claude Code CLI or Codex CLI as the AI provider
  • configure GitHub Pages publishing
  • configure a fine-grained GitHub token without exposing it in chat
  • configure Giscus comments
  • export one test note
  • verify that the result modal shows a short public link, archive link, and comment status
  • open the published page and check the GitHub sign-in button plus Giscus comment box

Recommended share settings for agent-assisted setup:

Share target: GitHub Pages link
Preview/export: Trusted interactive preview
Reader feedback: Giscus GitHub comments
Copy share link by default: On
Publish path: marktl

The agent cannot safely create or reveal your GitHub token for you. Create a fine-grained token yourself, limit it to the Pages repository, and grant only Contents: Read and write.

How To Use

  1. Open a Markdown note in Obsidian.
  2. If this is your first run, choose a setup path:
    • Start simple: no AI required.
    • Use Claude: checks Claude Code CLI installation and login.
    • Use Codex: checks Codex CLI installation and login.
    • Prepare sharing: creates static-hosting-ready bundles.
  3. Click the MarkTL ribbon icon, or run Export active note to HTML... from the command palette.
  4. Choose what the HTML should do from the purpose cards, such as Read better, Present it, Review it, Compare options, Publish/share, or Work with AI again.
  5. Open Advanced only when you need to adjust:
    • Artifact goal
    • Artifact type
    • Template
    • AI CLI or local fallback
    • Conversion mode
    • Sanitized or trusted preview
    • Sharing target
  6. Click Export.
  7. Watch the progress modal and result summary.
  8. Review the generated HTML inside Obsidian. The preview toolbar can copy the artifact as an AI prompt, copy an outline, copy a section-feedback prompt, or open the generated file.
  9. Use the result summary to copy a share link, copy an AI handoff prompt, or regenerate the artifact as slides or an interactive report.

Why HTML?

HTML lets MarkTL add things Markdown alone cannot reliably provide as a portable artifact: responsive layouts, cards, bundled local images, generated navigation, collapsible sections, scorecards, sliders, editable review notes, copy buttons, slide-like reading flows, and static-hosting-ready folders.

The kick is the review loop: a reader can open the hosted HTML, navigate it, interact with it, leave comments, copy structured feedback or state, and paste that back into Claude/Codex for the next iteration.

Context Packs

The export modal includes a Context pack option:

  • Active note only: sends only the current note to the converter.
  • Include linked notes: lets AI read local Markdown notes referenced by wikilinks or Markdown links, capped and compacted for safety.

Context packs are supporting material only. The active note remains the source of truth. Missing or unreadable linked notes are reported as export warnings.

Interactive Controls

In Trusted interactive preview, the interactive-report template can add local-only controls such as generated contents, collapsible sections, reading progress, section filtering, expand all, copy as prompt, copy as markdown, copy summary, and copy outline JSON. The playground template adds editable review notes, an emphasis slider, and copyable state JSON for iterative work. Artifact goals push AI-generated HTML toward stronger purpose-built interfaces such as decision rooms, review rooms, comparison boards, prompt playgrounds, and PR explainers.

The Obsidian preview pane also provides plugin-shell controls outside the generated iframe: Copy as prompt, Copy outline, Copy section feedback, and Open generated file. These controls work even when the generated HTML itself has no buttons.

Reader Feedback With Giscus

MarkTL can append a Reader feedback section powered by Giscus. Readers sign in with GitHub inside the Giscus comment box, then leave public comments and reactions stored in GitHub Discussions.

To use it:

  1. Enable GitHub Discussions on the feedback repository.
  2. Install the Giscus GitHub App for that repository at https://github.com/apps/giscus.
  3. Open https://giscus.app and enter the same owner/repo.
  4. Choose pathname mapping. This matches GitHub Pages paths such as /marktl/s/<short-id>/.
  5. Choose a discussion category such as General or Announcements.
  6. Copy the generated data-repo-id and data-category-id values from the script block.
  7. Copy repo, repo-id, category, and category-id into MarkTL settings.
  8. Set Reader feedback mode to Giscus GitHub comments.
  9. Export with Trusted preview/export.

Giscus loads an external script from https://giscus.app/client.js, so it is intentionally disabled for sanitized exports.

For reallygood83/moondoc, the values look like this after Discussions and the Giscus App are enabled:

Giscus repository: reallygood83/moondoc
Giscus repository ID: R_kgDOSZNBng
Giscus category: General
Giscus category ID: DIC_kwDOSZNBns4C81kX
Giscus mapping: pathname
Giscus theme: preferred_color_scheme

If giscus.app shows "giscus cannot be used", check these in order:

  1. The repository is public.
  2. GitHub Discussions is enabled in the repository.
  3. A discussion category exists.
  4. The Giscus GitHub App is installed for that exact repository.
  5. You selected an existing category in giscus.app.

Already-published HTML does not update itself after you change Giscus settings. Re-export the note with GitHub Pages link selected so MarkTL can inject the Giscus script into the HTML.

Export QA

MarkTL runs a basic post-generation HTML QA pass before writing and previewing the result. It warns about missing document structure, missing responsive viewport, missing CSS, trusted exports with no script, dynamic markup in sanitized mode, missing bundled image references, and missing image alt text. The internal preview also runs a render QA pass after the iframe loads to flag nearly empty output, missing H1, broken images, unusually short renders, or trusted previews with no controls.

AI Providers

Currently verified:

  • Claude Code CLI
  • Codex CLI

Codex runs through codex exec --json --sandbox read-only --skip-git-repo-check - and reads the generated prompt from stdin. Claude Code CLI currently receives the generated prompt as a command-line argument, so avoid sending private notes to Claude if local process inspection is a concern. If Obsidian cannot find a command, set the full CLI path in settings. Gemini CLI is hidden for now because the local plugin-style probe did not complete reliably.

On Windows, set CLI paths explicitly if Obsidian cannot find global npm commands. MarkTL supports Windows npm shim locations and uses shell execution for Windows CLI shims.

Rich AI artifacts can take several minutes. MarkTL defaults the CLI timeout to 15 minutes and migrates older 5-minute settings upward because Claude Code can exceed 300 seconds on long Korean notes and interactive HTML artifacts.

Preview Security

  • Sanitized static preview: removes scripts, iframes, remote assets, and dangerous handlers.
  • Trusted interactive preview: allows self-contained inline JavaScript for local-only interactive artifacts.

Use trusted mode only for content you intentionally generated and trust.

Sharing

MarkTL supports three sharing targets:

  • Local file link: copies a file:// link to the generated HTML.
  • Static hosting bundle: writes:
  • GitHub Pages link: writes the same bundle locally, uploads it to GitHub, and copies the public Pages URL.
html-exports/share/<slug>/index.html
html-exports/share/<slug>/README.md
html-exports/share/<slug>/assets/<image>.png

Local file link stores files at:

html-exports/<slug>.html
html-exports/<slug>-assets/<image>.png

Static hosting bundle and GitHub Pages link always store files at:

html-exports/share/<slug>/index.html
html-exports/share/<slug>/assets/<image>.png

For GitHub Pages publishing, fill these settings:

  • GitHub repository: owner/repo
  • GitHub branch: usually main
  • GitHub Pages base URL: for example https://owner.github.io/repo
  • Publish path: folder inside the repository, for example marktl
  • GitHub token: fine-grained token with Contents read/write permission for that repository

Creating the GitHub token

Use a fine-grained token, not a broad classic token:

  1. Open https://github.com/settings/personal-access-tokens/new.
  2. Set a clear token name, for example MarkTL Pages publisher.
  3. Set an expiration date.
  4. Under Repository access, choose Only select repositories.
  5. Select only the repository MarkTL publishes to, for example reallygood83/moondoc.
  6. Under Repository permissions, grant Contents → Read and write.
  7. Leave other permissions unset unless you know you need them.
  8. Generate the token and paste it into GitHub token in MarkTL settings.

MarkTL stores this token in the Obsidian plugin data file. Keep the token narrow, rotate it if it appears on screen during a recording, and avoid using a token that can access unrelated repositories.

The canonical public URL is:

<GitHub Pages base URL>/<Publish path>/<slug>/

MarkTL also publishes the same document at a shorter share URL and copies that shorter URL after export:

<GitHub Pages base URL>/<Publish path>/s/<short-id>/

For social sharing, MarkTL injects Open Graph and Twitter card metadata into the exported HTML. The preview title comes from frontmatter title or the first H1, the description comes from the opening note text, and the image uses the first bundled local image when available.

MarkTL also maintains a share home page and machine-readable index:

<GitHub Pages base URL>/<Publish path>/
<GitHub Pages base URL>/<Publish path>/index.json

Each GitHub Pages publish adds or updates one entry by <slug>. Re-exporting the same note updates that entry; publishing a different note adds a new entry. The share home is an archive page with searchable cards, tag filters, excerpts, artifact type labels, source paths, and newest-first ordering.

GitHub tokens are stored in the plugin data file. Use a dedicated repository and a narrow fine-grained token. Public publishing should always be intentional.

Private repository Pages depends on the GitHub account or organization plan. If GitHub Pages cannot be enabled for a private repository, either make the share repository public, upgrade to a plan that supports private Pages, or use a different static host that can deploy from private repositories.

Local Images

MarkTL bundles local note images during export. It detects Obsidian embeds and Markdown images such as:

![[diagram.png]]
![[Attachments/chart.webp|Chart]]
![Chart](images/chart.png)

Resolved image files are copied next to the generated HTML and image src values are rewritten to the bundled asset path:

html-exports/<note>.html
html-exports/<note>-assets/<image>.png

For static bundles, images are written under share/<slug>/assets/. Remote images and data URLs are left unchanged.

Development

npm install
npm test
npm run typecheck
npm run build

The build creates main.js, which BRAT uses together with manifest.json and styles.css.

한국어

목적

Markdown은 작성하기에는 좋지만, 긴 노트나 AI가 만든 분석 문서를 읽고 비교하고 공유하기에는 한계가 있습니다. MarkTL은 Obsidian의 현재 노트를 읽기 쉽고, 시각적으로 구조화되어 있고, 공유 준비가 된 HTML artifact로 바꾸는 플러그인입니다.

MarkTL은 단순한 "예쁜 Markdown 변환기"가 아닙니다. 목표는 읽기, 의사결정, 리뷰, 비교, 튜닝, 코드 설명, 공개 공유처럼 분명한 역할을 가진 HTML artifact를 만드는 것입니다.

핵심 아이디어는 단순합니다.

Markdown은 쓰는 곳이고, HTML은 AI가 만든 결과물이 작은 인터랙티브 작업면이 되는 곳입니다.

MarkTL artifact는 다음을 목표로 합니다.

  • 긴 Markdown보다 읽기 쉬운 문서
  • 섹션, 카드, 표, 목차, 시각적 위계가 있는 문서
  • trusted mode에서는 로컬 컨트롤, 상태 저장, AI에게 다시 붙여넣을 수 있는 copy-back prompt가 있는 문서
  • AI가 전략 브리프, 리서치 리포트, 의사결정 메모, 인터랙티브 설명서, 슬라이드형 문서로 재구성할 수 있는 문서
  • Obsidian 내부에서 바로 미리보기 가능한 문서
  • 하나의 정적 HTML 파일로 보관 가능한 문서
  • 로컬 링크 또는 정적 호스팅 번들로 공유 준비가 되는 문서

주요 기능

  • 리본 아이콘 또는 명령 팔레트에서 export 모달을 엽니다.
  • 첫 실행 시 setup wizard를 열어 local export, Claude, Codex, share-ready bundle 중 쉽게 선택할 수 있습니다.
  • artifact goal, artifact type, 템플릿, AI provider, 변환 모드, preview 보안, 공유 방식을 선택할 수 있습니다.
  • 현재 열려 있는 Markdown 노트를 HTML로 변환합니다.
  • 기본적으로 vault 안의 html-exports/ 폴더에 저장합니다.
  • 생성된 HTML을 Obsidian 내부 preview pane에서 보여줍니다.
  • 진행 모달을 통해 AI 결과인지 local fallback인지 확인할 수 있습니다.
  • AI 없이도 local Markdown-to-HTML 변환으로 동작합니다.
  • 검증된 AI provider를 지원합니다.
    • Claude Code CLI
    • Codex CLI
  • GitHub Pages, S3/R2, Netlify, Vercel 같은 정적 호스팅에 올릴 수 있는 bundle을 만들 수 있습니다.

Artifact Goal

먼저 HTML이 무엇을 해야 하는지 선택합니다.

  • Readable artifact: 긴 노트를 읽고 탐색하고 공유하기 쉽게 변환
  • Decision room: 질문, 선택지, 기준, tradeoff, risk, recommendation, decision log 중심
  • Review room: 독자가 구조화된 피드백을 남기고 Claude/Codex로 다시 가져갈 수 있는 리뷰 화면
  • Compare options: 여러 선택지를 나란히 비교하고 scorecard와 tradeoff를 보여주는 화면
  • Prompt playground: 수정 가능한 컨트롤과 copyable state를 가진 다음 AI iteration용 작업면
  • PR / code explainer: 코드, diff, 기술 계획, risk, reviewer checklist를 설명하는 화면
  • Public article: 공유와 SNS preview를 고려한 공개 글 화면

Artifact Type

Export 모달에서 artifact type을 선택할 수 있습니다.

  • Faithful Note: 원문을 최대한 보존하면서 읽기 쉽게 변환
  • Strategy Brief: TL;DR, 맥락, 선택지, tradeoff, risk, recommendation, next action 중심
  • Research Report: abstract, key findings, evidence, implication, source note 중심
  • Decision Memo: 질문, 기준, 선택지, 비교표, 추천안, 반대 의견, decision log 중심
  • Interactive Explainer: 목차, 접기/펼치기, copy button 등 상호작용 중심
  • Slide Deck: 섹션별로 슬라이드처럼 읽히는 문서

템플릿

포함된 템플릿:

  • minimal
  • editorial
  • deck
  • dashboard
  • investor-brief
  • research-memo
  • interactive-report
  • playground

interactive-report는 trusted mode에서 progress bar, 자동 목차, 섹션 접기/펼치기, copy as prompt, copy as markdown, copy summary 같은 기능을 포함할 수 있습니다. playground는 편집 가능한 working notes, 강조도 slider, copy prompt, copy state JSON을 제공해서 HTML 파일을 작은 리뷰 인터페이스처럼 사용할 수 있게 합니다.

BRAT으로 설치하는 방법

  1. Obsidian에서 BRAT 플러그인을 설치합니다.
  2. BRAT 설정을 엽니다.
  3. Add Beta plugin을 선택합니다.
  4. 아래 저장소 주소를 붙여넣습니다.
https://github.com/flytothesky23/marktl
  1. Obsidian community plugin 설정에서 Flytothesky MarkTL HTML Exporter를 활성화합니다.

Codex / Claude Code로 설치와 설정하기

많은 구독자는 직접 설정 화면을 하나씩 만지기보다 Codex나 Claude Code에게 설치와 설정을 맡기는 방식이 더 편합니다. MarkTL은 이 흐름에 맞게 준비되어 있습니다.

Obsidian에서 Flytothesky MarkTL setup을 열고 아래 버튼을 사용하세요.

  • Copy Codex setup prompt
  • Copy Claude setup prompt

복사된 프롬프트를 Codex 또는 Claude Code에 붙여넣으면 agent가 아래 과정을 순서대로 도와주도록 설계되어 있습니다.

  • BRAT으로 MarkTL 설치
  • Claude Code CLI 또는 Codex CLI provider 선택
  • GitHub Pages publish 설정
  • GitHub token을 채팅에 노출하지 않고 설정
  • Giscus 댓글 설정
  • 테스트 노트 하나 export
  • 결과 모달에서 짧은 공개 링크, 아카이브 링크, 댓글 상태 확인
  • 실제 공개 페이지를 열어 GitHub 로그인 버튼과 Giscus 댓글창 확인

권장 공유 설정:

Share target: GitHub Pages link
Preview/export: Trusted interactive preview
Reader feedback: Giscus GitHub comments
Copy share link by default: On
Publish path: marktl

AI agent가 GitHub token을 안전하게 대신 발급하거나 공개해줄 수는 없습니다. token은 사용자가 직접 만들고, Pages repo 하나로 범위를 제한하고, 권한은 Contents: Read and write만 주는 것을 권장합니다.

사용 방법

  1. Obsidian에서 Markdown 노트를 엽니다.
  2. 첫 실행이라면 setup path를 선택합니다.
    • Start simple: AI 없이 바로 사용
    • Use Claude: Claude Code CLI 설치와 로그인 상태 확인
    • Use Codex: Codex CLI 설치와 로그인 상태 확인
    • Prepare sharing: 정적 호스팅용 bundle 생성
  3. MarkTL 리본 아이콘을 클릭하거나 명령 팔레트에서 Export active note to HTML...을 실행합니다.
  4. Read better, Present it, Review it, Compare options, Publish/share, Work with AI again 같은 목적 카드를 선택합니다.
  5. 필요한 경우에만 Advanced를 열어 다음을 조정합니다.
    • Artifact goal
    • Artifact type
    • Template
    • AI CLI 또는 local fallback
    • Conversion mode
    • Sanitized preview 또는 Trusted preview
    • Sharing target
  6. Export를 누릅니다.
  7. 진행 모달과 결과 요약을 확인합니다.
  8. Obsidian 내부 HTML Preview에서 결과를 확인합니다. Preview toolbar에서 artifact를 AI prompt로 복사하거나, outline을 복사하거나, section feedback prompt를 복사하거나, 생성 파일을 열 수 있습니다.
  9. 결과 요약에서 share link를 복사하고, AI handoff prompt를 복사하고, slides 또는 interactive report로 다시 생성할 수 있습니다.

왜 HTML인가?

HTML을 사용하면 Markdown만으로는 휴대 가능한 artifact로 만들기 어려운 기능을 넣을 수 있습니다. 반응형 레이아웃, 카드형 섹션, 로컬 이미지 bundle, 자동 목차, 접기/펼치기, scorecard, slider, 편집 가능한 리뷰 메모, copy button, 슬라이드형 읽기 흐름, 정적 호스팅 준비 폴더를 만들 수 있습니다.

진짜 kick은 review loop입니다. 독자는 공유된 HTML 링크를 열고, 읽고, 조작하고, 댓글을 남기고, 구조화된 피드백이나 상태를 복사해서 다시 Claude/Codex에 넣을 수 있습니다.

Context Pack

Export 모달에는 Context pack 옵션이 있습니다.

  • Active note only: 현재 노트만 변환기에 보냅니다.
  • Include linked notes: wikilink 또는 Markdown link로 연결된 로컬 Markdown 노트를 AI가 참고하도록 합니다. 안전을 위해 개수와 길이를 제한하고 압축합니다.

Context pack은 보조 자료입니다. 현재 열린 노트가 항상 기준이며, 찾을 수 없거나 읽을 수 없는 linked note는 export warning으로 표시됩니다.

인터랙티브 컨트롤

Trusted interactive preview에서 interactive-report 템플릿은 자동 목차, 접기/펼치기, 읽기 progress, 섹션 필터, 전체 펼치기, copy as prompt, copy as markdown, copy summary, copy outline JSON 같은 로컬 전용 컨트롤을 넣을 수 있습니다. playground 템플릿은 편집 가능한 리뷰 메모, 강조도 slider, copyable state JSON을 제공합니다. Artifact goal은 AI가 decision room, review room, comparison board, prompt playground, PR explainer처럼 목적이 분명한 HTML 인터페이스를 만들도록 유도합니다.

Obsidian preview pane 자체도 생성된 iframe 밖에서 Copy as prompt, Copy outline, Copy section feedback, Open generated file 컨트롤을 제공합니다. 생성된 HTML에 버튼이 없어도 이 preview toolbar를 사용할 수 있습니다.

Giscus 독자 피드백

MarkTL은 Giscus 기반 Reader feedback 섹션을 HTML 하단에 붙일 수 있습니다. 독자는 Giscus 댓글창 안에서 GitHub로 로그인하고, 댓글과 reaction을 GitHub Discussions에 남깁니다.

사용 방법:

  1. 피드백을 저장할 GitHub repo에서 Discussions를 활성화합니다.
  2. https://github.com/apps/giscus에서 해당 repo에 Giscus GitHub App을 설치합니다.
  3. https://giscus.app을 열고 같은 owner/repo를 입력합니다.
  4. Page ↔ Discussion mapping은 pathname을 선택합니다. GitHub Pages 경로 /marktl/s/<short-id>/와 잘 맞습니다.
  5. Discussion category는 General 또는 Announcements처럼 실제 존재하는 category를 선택합니다.
  6. 생성된 script block에서 data-repo-id, data-category-id 값을 복사합니다.
  7. repo, repo-id, category, category-id 값을 MarkTL 설정에 입력합니다.
  8. Reader feedback mode를 Giscus GitHub comments로 설정합니다.
  9. Trusted preview/export로 export합니다.

Giscus는 https://giscus.app/client.js 외부 스크립트를 로드하므로 sanitized export에서는 의도적으로 비활성화됩니다.

reallygood83/moondoc 기준으로 Discussions와 Giscus App이 설정된 뒤 값은 아래처럼 입력합니다.

Giscus repository: reallygood83/moondoc
Giscus repository ID: R_kgDOSZNBng
Giscus category: General
Giscus category ID: DIC_kwDOSZNBns4C81kX
Giscus mapping: pathname
Giscus theme: preferred_color_scheme

giscus.app에서 "giscus를 사용할 수 없습니다"가 나오면 아래 순서로 확인하세요.

  1. repo가 public인지 확인합니다.
  2. repo에서 GitHub Discussions가 켜져 있는지 확인합니다.
  3. Discussion category가 실제로 존재하는지 확인합니다.
  4. Giscus GitHub App이 정확히 그 repo에 설치되어 있는지 확인합니다.
  5. giscus.app에서 존재하는 category를 선택했는지 확인합니다.

이미 발행한 HTML은 Giscus 설정 변경 후 자동으로 바뀌지 않습니다. GitHub Pages link로 같은 노트를 다시 export해야 MarkTL이 HTML 안에 Giscus script를 삽입합니다.

Export QA

MarkTL은 HTML을 저장하고 preview하기 전에 기본 QA를 실행합니다. 문서 구조, responsive viewport, inline CSS, trusted mode의 script 유무, sanitized mode의 동적 markup, bundled image 참조 누락, image alt 누락을 warning으로 알려줍니다. 내부 preview는 iframe 로드 후 render QA도 실행해서 거의 빈 화면, H1 누락, 깨진 이미지, 비정상적으로 짧은 렌더, trusted preview인데 컨트롤이 없는 경우를 표시합니다.

AI Provider

현재 검증된 provider:

  • Claude Code CLI
  • Codex CLI

Codex는 codex exec --json --sandbox read-only --skip-git-repo-check - 형태로 실행되며 생성 prompt를 stdin으로 전달합니다. Claude Code CLI는 현재 생성 prompt를 command-line argument로 받으므로, 로컬 process inspection이 걱정되는 private note는 Claude로 보내지 않는 편이 좋습니다. Obsidian이 명령을 찾지 못하면 설정에 CLI 전체 경로를 입력하세요. Gemini CLI는 현재 로컬 plugin-style probe가 안정적으로 완료되지 않아 UI에서 제외했습니다.

Windows에서는 Obsidian이 전역 npm 명령을 찾지 못하면 CLI 전체 경로를 직접 입력하세요. MarkTL은 Windows npm shim 경로와 Windows CLI shim 실행 방식을 지원합니다.

풍부한 AI artifact는 몇 분이 걸릴 수 있습니다. MarkTL은 CLI timeout 기본값을 15분으로 두며, 기존 5분 설정은 자동으로 15분으로 올립니다. 긴 한국어 노트와 인터랙티브 HTML artifact에서는 Claude Code가 300초를 넘는 경우가 있기 때문입니다.

Preview 보안

  • Sanitized static preview: script, iframe, remote asset, 위험한 handler를 제거합니다.
  • Trusted interactive preview: 사용자가 명시적으로 신뢰한 경우 self-contained inline JavaScript를 허용합니다.

Trusted mode는 의도적으로 생성하고 신뢰하는 문서에만 사용하세요.

공유

MarkTL은 세 가지 공유 방식을 지원합니다.

  • Local file link: 생성된 HTML의 file:// 링크를 복사합니다.
  • Static hosting bundle: 아래 구조를 생성합니다.
  • GitHub Pages link: 같은 bundle을 로컬에 만들고 GitHub에 업로드한 뒤 공개 Pages URL을 복사합니다.
html-exports/share/<slug>/index.html
html-exports/share/<slug>/README.md
html-exports/share/<slug>/assets/<image>.png

Local file link는 아래 경로에 저장합니다.

html-exports/<slug>.html
html-exports/<slug>-assets/<image>.png

Static hosting bundle과 GitHub Pages link는 항상 아래 경로에 저장합니다.

html-exports/share/<slug>/index.html
html-exports/share/<slug>/assets/<image>.png

GitHub Pages publish를 쓰려면 설정에 아래 값을 입력합니다.

  • GitHub repository: owner/repo
  • GitHub branch: 보통 main
  • GitHub Pages base URL: 예 https://owner.github.io/repo
  • Publish path: repo 안의 폴더, 예 marktl
  • GitHub token: 해당 repo에 Contents read/write 권한이 있는 fine-grained token

GitHub token 발급 방법

넓은 권한의 classic token보다 fine-grained token을 권장합니다.

  1. https://github.com/settings/personal-access-tokens/new를 엽니다.
  2. Token name을 알아보기 쉽게 입력합니다. 예: MarkTL Pages publisher
  3. Expiration을 설정합니다.
  4. Repository access에서 Only select repositories를 선택합니다.
  5. MarkTL이 publish할 repo만 선택합니다. 예: reallygood83/moondoc
  6. Repository permissions에서 Contents → Read and write를 부여합니다.
  7. 다른 권한은 필요하지 않으면 비워둡니다.
  8. token을 생성한 뒤 MarkTL settings의 GitHub token에 붙여넣습니다.

MarkTL은 이 token을 Obsidian plugin data file에 저장합니다. 녹화 중 token이 화면에 노출되었다면 즉시 revoke/rotate하고, unrelated repo에 접근 가능한 token은 사용하지 마세요.

정식 공개 URL은 아래처럼 만들어집니다.

<GitHub Pages base URL>/<Publish path>/<slug>/

MarkTL은 같은 문서를 짧은 공유 URL에도 함께 발행하고, export 후에는 이 짧은 URL을 복사합니다.

<GitHub Pages base URL>/<Publish path>/s/<short-id>/

SNS 공유를 위해 exported HTML에는 Open Graph와 Twitter card metadata가 들어갑니다. 미리보기 제목은 frontmatter title 또는 첫 H1에서 가져오고, 설명은 노트 앞부분에서 만들며, 이미지는 가능한 경우 첫 번째 bundled local image를 사용합니다.

MarkTL은 공유 홈 페이지와 기계가 읽을 수 있는 index도 함께 관리합니다.

<GitHub Pages base URL>/<Publish path>/
<GitHub Pages base URL>/<Publish path>/index.json

GitHub Pages publish를 할 때마다 <slug> 기준으로 항목이 추가되거나 갱신됩니다. 같은 노트를 다시 export하면 해당 항목이 최신본으로 바뀌고, 다른 노트를 publish하면 목록에 새 항목이 추가됩니다. 공유 홈은 검색 가능한 카드형 아카이브 페이지이며 태그 필터, 요약, artifact type, 원본 경로, 최신순 정렬을 제공합니다.

GitHub token은 플러그인 데이터 파일에 저장됩니다. 전용 repo와 권한이 좁은 fine-grained token을 쓰세요. 공개 publish는 항상 사용자가 명시적으로 선택해야 합니다.

Private repo에서 GitHub Pages를 쓸 수 있는지는 GitHub 계정 또는 조직 플랜에 따라 달라집니다. private repo에서 Pages를 켤 수 없다면 share repo를 public으로 바꾸거나, private Pages를 지원하는 플랜을 쓰거나, private repo 배포를 지원하는 다른 정적 호스팅을 사용해야 합니다.

로컬 이미지

MarkTL은 export 과정에서 노트의 로컬 이미지를 함께 bundle로 만듭니다. 아래 문법을 감지합니다.

![[diagram.png]]
![[Attachments/chart.webp|Chart]]
![Chart](images/chart.png)

찾은 이미지 파일은 생성된 HTML 옆으로 복사되고, HTML의 이미지 src는 bundle 안의 asset 경로로 바뀝니다.

html-exports/<note>.html
html-exports/<note>-assets/<image>.png

Static bundle에서는 이미지가 share/<slug>/assets/ 아래에 저장됩니다. 원격 이미지와 data URL은 그대로 둡니다.

개발

npm install
npm test
npm run typecheck
npm run build

빌드하면 BRAT에서 사용하는 main.js가 생성됩니다. manifest.json, styles.css와 함께 배포됩니다.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages