명령줄

slides [deck.md] [flags]
slides [command] [flags] deck.md

명령

slides <command> --help는 명령의 플래그를 출력합니다. 플래그는 프레젠테이션 앞에 와도, 뒤에 와도 됩니다. slides deck.md -o out.html과 slides -o out.html deck.md는 같습니다. 긴 플래그는 대시 두 개(--html)로 쓰며, 짧은 플래그는 -o 하나뿐입니다. build는 -o로 따로 지정하지 않으면 deck.md 옆에 deck.html을 씁니다.

플래그

여러 프레젠테이션과 디렉터리

v0.6.0부터 build는 여러 프레젠테이션, 디렉터리(그 아래에서 재귀적으로 찾은 프레젠테이션), 패턴을 받을 수 있으며, 최대 --parallel개를 동시에 빌드합니다. -는 표준 입력입니다. marp-cli와 달리 -로 지정하지 않으면 파이프를 읽지 않습니다.

패턴은 marp-cli의 glob과 같은 방식으로 해석됩니다(**와 {a,b}는 v0.7.0부터. 셸이 펼치지 않고 slides에 넘기도록 따옴표로 감싸십시오). 이름 안에서는 *, ?, [a-z], {md,txt}를, 디렉터리 여러 단계에는 **를 쓰므로 'docs/**/*.md'는 트리 안의 모든 프레젠테이션을 가리킵니다. 와일드카드는 점으로 시작하는 이름과 일치하지 않고, node_modules 안은 찾지 않으며, 대소문자를 구분하고(*.md는 UPPER.MD를 찾지 않음), 패턴과 일치하는 것은 확장자와 관계없이 변환됩니다. 아무것도 일치하지 않는 패턴은 오류입니다.

• **-I dir**는 marp-cli처럼 dir 아래의 Markdown 파일(소문자 .md, .mdown, .markdown, .markdn)을 찾으며, node_modules와 점으로 시작하는 디렉터리는 찾지 않습니다. -o out을 지정하면 각 프레젠테이션은 dir 아래의 경로를 out 아래에 그대로 옮긴 위치에 쓰입니다. dir/sub/b.md는 out/sub/b.html(플래그에 따라 b.pdf, b.001.png, b.txt, …)이 됩니다. -o가 없으면 출력은 각 프레젠테이션 옆에 쓰입니다. -I와 함께 프레젠테이션을 지정하면 오류이며, 여러 프레젠테이션에 -o file을 지정해도 오류입니다(-o -는 허용).
• **-P n**은 프레젠테이션 n개를 동시에 빌드합니다. 프레젠테이션 하나의 렌더링도 이미 여러 코어를 쓰므로 n은 코어 수로 제한되며, -o -이면 하나씩 차례로 빌드합니다. 한 프레젠테이션의 메시지는 함께 묶여 출력되고, 실패한 프레젠테이션이 있어도 나머지는 멈추지 않습니다. 종료 상태는 1이며 메시지에 실패 목록이 나옵니다.

전환 효과와 발표 페이지

v0.6.0부터 marp-cli의 transition 디렉티브가 동작합니다. <!-- transition: fade 1s -->처럼 이름과 선택적 지속 시간을 쓰면 해당 슬라이드와 그 뒤의 슬라이드에 적용되고, <!-- _transition: cover -->는 한 슬라이드에만 적용됩니다. 기본 제공 이름은 marp-cli와 같습니다: clockwise, counterclockwise, cover, coverflow, cube, cylinder, diamond, drop, explode, fade, fade-out, fall, flip, glow, implode, in-out, iris-in, iris-out, melt, overlap, pivot, pull, push, reveal, rotate, slide, star, swap, swipe, swoosh, wipe, wiper, zoom. none은 전환 효과를 끕니다. 페이지는 보는 사람이 전환 효과가 지정된 슬라이드에서 앞으로 넘어갈 때와 그 슬라이드로 돌아올 때 브라우저의 View Transition API로 효과를 재생합니다. 이 API가 없는 브라우저는 이전처럼 슬라이드를 바꾸고, 동작 줄이기를 요청한 사용자에게는 단순한 페이드가 적용됩니다. 테마는 marp-transition-NAME(또는 marp-outgoing-과 marp-incoming-, 그리고 -backward)이라는 이름으로 자체 키프레임을 제공할 수 있으며, 이 키프레임이 기본 제공 키프레임보다 먼저 쓰입니다.

페이지에는 이전, 페이지, 다음, 전체 화면 버튼으로 이루어진 화면 컨트롤러가 있습니다. 포인터를 움직이거나 키를 누르면 나타났다가 잠시 뒤 사라지며 (--bespoke.osc=false로 제거), --bespoke.progress를 쓰면 진행률 막대도 표시됩니다. 이제 진행률 막대는 marp-cli처럼 기본적으로 꺼져 있습니다. 이전에는 항상 그려졌습니다.

발표자 보기

v0.7.0부터 페이지에 marp-cli의 발표자 보기가 있습니다. p를 누르거나 컨트롤러의 마지막 버튼을 누르면 현재 슬라이드, 그다음 단계, 발표자 노트, 페이지, 시각, 타이머가 있는 창이 열립니다(타이머를 클릭하면 초기화되고, +와 -로 노트 크기를 조절하며, 슬라이드와 노트 사이의 막대는 끌어서 움직일 수 있습니다). 두 창은 양방향으로 연동됩니다. 어느 창에서든 화살표 키, 다음 단계 클릭, Previous/Next 클릭으로 다른 창도 한 단계(프래그먼트)씩 움직입니다.

marp-cli 4.5.1 소스에서 확인한 것과 같은 방식으로 동작합니다. 창은 같은 파일의 ?view=presenter&sync=KEY이고, 다음 단계는 같은 페이지를 ?view=next로 프레임에 띄운 것이며, 두 창은 localStorage(bespoke-marp-sync-KEY)로 위치를 공유합니다. 따라서 서버도 네트워크도 필요 없지만, localStorage가 없는 브라우저에서는 동작하지 않습니다(버튼이 이를 알려 줍니다). 노트는 텍스트이며 &, <, >가 이스케이프되므로 노트가 마크업이 될 수 없습니다. 노트는 발표자 보기가 가져갈 수 있도록 페이지 안에 숨겨져 있어, 화면 낭독기가 청중에게 읽어 주는 내용에는 포함되지 않습니다. --bare 페이지에는 이 기능이 없습니다. 발표자 보기는 페이지 크기를 약 10 KB 늘립니다.

개요 보기

v0.8.0부터 o(또는 Escape. marp-cli는 두 키 모두로 전환합니다), 컨트롤러의 격자 버튼, 발표자 보기의 페이지 카운터를 누르면 모든 슬라이드가 페이지 위의 격자에 온전히 표시됩니다. 화살표 키로 슬라이드를 고르고(위아래는 행 단위), Home과 End로 처음과 끝으로 가며, 다른 창도 따라 움직입니다. Enter, Space, 클릭으로 슬라이드를 선택하면 페이지 위에서는 개요가 닫힙니다. 발표자 보기 위에서는 선택해도 개요가 열린 채로 남습니다(발표자가 보여 줄 슬라이드를 고른 뒤에도 계속 살펴볼 수 있도록). “Close overview” 버튼, o, Escape로 닫습니다. 이 기능도 marp-cli와 같습니다. 같은 페이지를 다시 ?view=overview&sync=KEY 프레임에 띄우고 localStorage로 위치를 공유하며, 네트워크를 쓰지 않습니다. 격자 안의 슬라이드는 포커스를 받을 수 있고 “Slide N” 레이블이 붙으며, 닫힌 개요는 비활성(inert) 상태이므로 키보드나 화면 낭독기 사용자가 그 안으로 들어가는 일은 없습니다. 두 보기를 합치면 페이지 크기가 약 15 KB 늘어납니다.

설정 파일

marp-cli는 작업 디렉터리의 파일에서 옵션을 읽으며, slides도 그 파일이 데이터일 때 똑같이 읽습니다: .marprc(YAML. JSON도 YAML입니다), .marprc.json, .marprc.yaml, .marprc.yml, .config/marprc*, 또는 package.json의 marp 키. --config-file(-c)로 임의의 JSON 또는 YAML 파일(예: marp.config.json)을 지정할 수 있습니다. marp-cli의 검색과 마찬가지로 작업 디렉터리만 찾고 상위 디렉터리는 찾지 않습니다. JavaScript나 TypeScript 파일(marp.config.js …)은 프로그램이므로 slides는 실행하지 않으며, 그 사실을 알리고 계속 진행합니다. 옵션은 marp-cli 문서에 있는 것 중 여기서 의미가 있는 것들입니다: title, description, author, keywords, url, ogImage, lang, theme, themeSet, html, allowLocalFiles, template, bespoke, inputDir, output, parallel, pdf, pptx, notes, pdfNotes, pdfOutlines, images, image, imageScale, jpegQuality, watch, server, preview. 경로는 파일 기준 상대 경로이며, 명령줄이 우선합니다. engine, options, browser*는 Marp 엔진과 브라우저가 필요하므로 --browser* 플래그와 마찬가지로 경고와 함께 무시됩니다. 따라서 marp-cli용으로 작성한 스크립트도 계속 동작합니다. (slides.yaml과 slides.hcl은 kind, 템플릿 데이터와 함께 별개이며 이전과 똑같이 읽습니다.)

감시, 서버, 미리 보기

v0.6.0부터 marp-cli의 경로와 실시간 새로 고침 프로토콜을 지원합니다(marp-cli 4.5.1 소스에서 확인하고 실행 중인 marp -s와 비교했습니다).

slides --server dir(-s)는 디렉터리를 http://127.0.0.1:8080/에서 제공합니다(PORT 환경 변수로 포트를 바꿀 수 있으며, 이미 사용 중인 포트는 그 사실을 알리는 오류가 됩니다).

페이지는 /.__marp-cli-watch-notifier__/<id>로 WebSocket을 엽니다. id는 프레젠테이션 경로의 SHA-256입니다. 서버는 ready를 보낸 다음, 프레젠테이션이나 디렉터리 아래의 무언가가 바뀌면 reload를 보냅니다. 끝의 슬래시 없이 요청한 디렉터리는 슬래시가 붙은 경로로 리디렉션됩니다(marp-cli는 그 경로에서 색인을 제공하므로 페이지의 상대 링크가 깨집니다).

--watch(-w)는 프레젠테이션을 빌드한 뒤 바뀐 프레젠테이션을 다시 빌드하고, --theme-set 파일, kind 파일이나 데이터 파일, 설정이 바뀌면 전체를 다시 빌드합니다. 이렇게 쓴 페이지는 루프백에 소켓(포트 37717 또는 그다음 빈 포트)을 열고, 해당 프레젠테이션이 다시 빌드되면 새로 고침합니다. 빌드에 실패한 프레젠테이션은 보고된 뒤에도 계속 감시됩니다. --preview(-p)는 기본 브라우저로 서버나 방금 빌드한 HTML 페이지를 엽니다. slides에는 구동할 브라우저가 없으므로 자체 창은 없습니다.

서버는 컴퓨터로 들어오는 통로이므로, 모든 인터페이스에서 수신하고 아무것도 검사하지 않는 marp-cli보다 엄격합니다.

• 127.0.0.1에서 수신합니다. --host로 바꿀 수 있지만 경고가 나오며, 와일드카드 주소에서는 더 이상 Host 헤더를 검사할 수 없습니다.
• Host 헤더는 루프백 이름(localhost, 127.0.0.1, [::1], *.localhost)이거나 서버가 수신하는 호스트여야 하며, 이것이 DNS 리바인딩을 막습니다.
• WebSocket의 **Origin**은 서버 자신의 출처여야 합니다. 감시 모드의 소켓은 파일에서 연 페이지의 null 출처도 받습니다. 다른 사이트에서 온 요청 중 탐색이 아닌 것(스크립트, 이미지, fetch)은 거부됩니다.
• 경로는 정규화하고 심볼릭 링크를 해석하며, 그 결과가 디렉터리 안에 있어야 합니다. ..와 디렉터리 밖을 가리키는 링크는 거부되며, 밖에 있는 프레젠테이션의 ?pdf도 거부됩니다. 점으로 시작하는 이름(.git, .env)은 제공하지 않습니다.
• GET과 HEAD만 받습니다. 동시 변환 수는 몇 개로 제한되고, 감시하는 디렉터리는 최대 4096개이며 node_modules 안이나 점으로 시작하는 디렉터리 아래는 감시하지 않습니다.

페이지 메타데이터

marp-cli와 마찬가지로 명령줄이 프레젠테이션보다 우선합니다. marp-cli에서는 플래그가 마지막 디렉티브 주석 하나로 프레젠테이션 끝에 덧붙여집니다. 규칙은 marp-cli 4.5.1에서 확인했으며 그 출력과 비교하는 테스트로 고정되어 있습니다 (v0.6.0부터).

• title을 지정하지 않은 프레젠테이션은 가장 낮은 수준의 첫 제목 텍스트를 쓴 그대로 가져옵니다(# **Bold** title이면 **Bold** title). 제목이 없으면 <title>도 없습니다.
• keywords는 쉼표로 나누고 앞뒤 공백을 없앤 뒤 중복을 제거합니다. 프런트 매터의 목록은 그대로 받아들입니다. marp-cli와 마찬가지로 키워드가 두 개 이상일 때만 페이지에 keywords 태그가 들어가며, 하나뿐이면 들어가지 않습니다.
• 유효하지 않은(절대 경로가 아닌) url은 경고와 함께 무시되고 이전 값이 유지됩니다. 유효한 값은 <link rel="canonical">과 og:url도 씁니다.
• author와 description에는 대응하는 Open Graph 태그가 함께 붙습니다. og:image:alt와 큰 Twitter 카드에는 제목과 이미지가 모두 필요합니다.

이미지, PDF, PPTX, ODP

marp-cli와 마찬가지로 -o에 .pdf, .pptx, .odp, .png, .jpg 확장자를 쓰면 그에 맞는 형식이 선택됩니다. 출력 디렉터리는 자동으로 만들어집니다. PDF는 슬라이드 크기의 페이지가 슬라이드당 하나씩 있고, 슬라이드와 그 제목으로 이루어진 개요가 들어갑니다.

PDF 노트와 개요

v0.6.0부터 PDF는 marp-cli의 두 옵션을 지원하며, 같은 프레젠테이션에 대해 marp-cli 4.5.1이 쓴 PDF와 비교했습니다.

• --pdf-notes는 각 슬라이드의 발표자 노트를 해당 페이지에 노트 주석으로 넣습니다. 왼쪽 아래에 노란 노트 아이콘이 표시되며, 내용은 노트(주석이 여러 개면 빈 줄로 연결)이고 제목은 프레젠테이션의 author입니다. marp-cli와 마찬가지로 --pdf-notes만 지정해도 PDF를 만듭니다.
• 개요에는 슬라이드마다 굵은 글씨의 “Page N” 책갈피가 있고, 그 아래에 슬라이드의 제목이 수준별로 중첩됩니다(--pdf-outlines.pages와 --pdf-outlines.headings로 각각 선택). 개요는 여기서는 기본적으로 켜져 있고 marp-cli에서는 꺼져 있습니다. slides는 항상 개요를 써 왔습니다. 몇백 바이트밖에 들지 않고 긴 프레젠테이션을 쉽게 탐색할 수 있게 해 주므로 기본값을 유지합니다. --pdf-outlines=false나 marp-cli의 --no-pdf-outlines로 끄며, .pages나 .headings에 =false를 쓰면 해당 부분만 뺍니다. 제목 책갈피는 해당 슬라이드로 이동합니다. marp-cli는 제목 위치까지 스크롤합니다.

렌더링은 go-webengine이 하고 PDF는 go-pdfkit이 씁니다. 기본 제공 테마가 요구하는 글꼴(Lato, Roboto Mono)은 go-opentype/fonts에서 가져와 내장하므로, 렌더링 중 네트워크에 접근하는 일이 없습니다. Chrome은 쓰지 않습니다.

--image-scale 2는 CSS 픽셀당 장치 픽셀 2개로 렌더링합니다. 로컬 이미지는 --allow-local-files를 지정하지 않으면 거부되며, 지정하더라도 프레젠테이션 디렉터리 아래의 파일만 읽습니다. 따라서 다른 곳에서 받은 프레젠테이션이 ~/.ssh에 접근할 수 없습니다. 여러 장의 배경과 화면을 나누는 배경 (![bg left:40%])은 Marp의 레이어와 똑같이 렌더링됩니다.

--pptx는 go-ooxml의 WritePresentation으로 발표자 노트와 프레젠테이션 메타데이터를 포함해 씁니다. v0.5.0부터 슬라이드는 편집할 수 있습니다(아래 참고). --pptx-raster는 marp-cli처럼 슬라이드마다 슬라이드 전체 크기 그림 한 장을 쓰며, 배율 기본값은 2이고 --image-scale로 바꿀 수 있습니다. 결과는 LibreOffice에서 열립니다. LibreOffice에서만 테스트했으며 PowerPoint와 Keynote에서는 테스트하지 않았습니다.

--odp는 go-odf의 WritePresentation으로 발표자 노트를 포함한 OpenDocument 프레젠테이션을 씁니다. --odp-raster는 슬라이드당 그림 한 장을 씁니다.

편집 가능한 PPTX와 ODP

v0.5.0부터 PPTX와 ODP의 슬라이드는 편집할 수 있습니다. marp-cli의 PPTX는 슬라이드당 그림 한 장이며, 실험적 기능인 --pptx-editable은 PDF를 LibreOffice로 변환합니다. 여기서는 각 슬라이드를 PNG와 PDF 내보내기가 그리는 것과 같은 레이아웃에서 그립니다.

• 텍스트의 각 줄은 레이아웃된 위치에 놓인 텍스트 상자이며, 슬라이드 레이아웃에 쓰인 글꼴을 씁니다. 글꼴은 파일에 내장되므로 Lato나 Inter가 없는 컴퓨터에서도 똑같이 보이며(LibreOffice 25.8로 확인), 굵게, 기울임, 색, 자간, 클릭 가능한 링크도 유지됩니다.
• 배경, 테두리, 둥근 상자는 도형입니다. 그레이디언트는 PPTX에서는 그레이디언트 채우기, ODP에서는 그림입니다(ODF 그레이디언트는 색이 두 개뿐입니다).
• 그림은 여러 슬라이드에 나오더라도 한 번만 저장됩니다.
• 슬라이드로 표현할 수 없는 것(opacity가 적용된 요소, filter, 흐린 그림자, 수식)은 해당 요소의 그림이 되며, 그 위에 텍스트가 유지됩니다.

LibreOffice로 다시 렌더링하면 슬라이드는 PNG 내보내기와 픽셀 기준 0.04–2 % 이내로 일치합니다. --pptx-raster와 --odp-raster는 슬라이드당 그림 한 장을 유지합니다.

벡터 PDF

v0.4.0부터 PDF는 벡터로 그려집니다. go-webengine이 레이아웃된 슬라이드를 픽셀 대신 PDF에 직접 그립니다. 텍스트는 슬라이드 레이아웃에 쓰인 글꼴의 텍스트로, /ToUnicode 맵과 함께 서브셋으로 내장되므로 선택, 검색, 복사할 수 있습니다. 배경, 테두리, 그레이디언트는 패스와 셰이딩이며, 여러 슬라이드에 나오는 이미지는 한 번만 내장되고 링크는 클릭할 수 있습니다. 슬라이드 100장 벤치마크 프레젠테이션은 758 KiB로, marp-cli의 837 KiB와 v0.3.0 이미지 PDF의 10 MiB보다 작으며 0.3 s 만에 작성됩니다.

여기서 벡터로 표현할 수 없는 요소(opacity < 1이 적용된 요소, filter나 회전이 있는 요소, 흐린 box-shadow, 불투명도가 점점 옅어지는 그레이디언트)는 해당 요소만 비트맵으로 그리고, 그 위에 텍스트를 보이지 않게 겹쳐 선택할 수 있게 합니다. 수식은 아직 비트맵입니다. --pdf-raster는 v0.3.0처럼 페이지마다 이미지 한 장을 씁니다.

slides.yaml

프레젠테이션 옆의 설정 파일이 그 프레젠테이션에 적용되므로, 한 폴더의 프레젠테이션들이 설정 파일 하나를 공유합니다.

kinds: kinds.yaml        # a mapping of kinds, or file(s) holding one
themes:                  # theme CSS files or directories
  - themes/
data:                    # template data
  company: Example Inc.
html: false              # allow all raw HTML
lang: en

kind: 프레젠테이션 자체의 kinds:가 설정 파일과 명령줄의 kind보다 우선합니다. 데이터: 설정 파일과 명령줄의 data가 프레젠테이션의 프런트 매터보다 우선하므로, 같은 프레젠테이션을 서로 다른 데이터로 빌드할 수 있습니다.

계획된 기능

아직 구현되지 않은 기능은 PDF 안의 수식을 벡터로 출력하는 것입니다. 구현되면 이 페이지에 명령이나 플래그로 추가됩니다.