Emacs > 논문 쓰기> Org-mode 기초부터 시작하기

3604 2025. 1. 25. 13:43

728x90

출처: https://edykim.com/ko/post/start-with-orgmode-basics/

Org-mode 기초부터 시작하기

Emacs에서 사용할 수 있는 강력한 생산성 도구 Org-mode 튜토리얼, 번역.

최근 emacs에 대한 유튜브를 보는데 전혀 IT쪽 일을 하지 않는 사람도 org-mode 때문에 emacs를 사용한다는 얘기를 듣고 문서를 찾아보게 되었다.

emacs는 아예 처음 사용해보는데 이 문서에 emacs 기능도 간략하게 설명하고 있어서 org-mode의 기능을 살펴보는데 불편함이 없었다. 각각 기능도 강력하고 일반 텍스트를 이렇게 멋지게 조작 가능한게 놀랍다. markdown이나 html로 내보내는 기능도 멋지다. 내보내는 포맷은 플러그인으로 추가도 가능하다. 익숙해지면 정말 유용할 것 같다.

이 번역 문서는 GNU 자유 문서 사용 허가서 버전 1.3 또는 그 이후의 버전이 적용된다. 코드 예제는 GNU GPL 버전 3 또는 이후 버전이 적용된다. 원본은 Org mode beginning at the basics 페이지에서 찾을 수 있다.

Org-mode 기초부터 시작하기

Org-mode는 공식 웹페이지에서 설명하는 것과 같이 노트와 할 일 목록을 관리하고 프로젝트 계획을 작성하거나 저작하는데 사용할 수 있는, 빠르고 효과적인 플레인 텍스트 시스템입니다. Emacs 22.2와 XEmacs 22.1부터 지원하기 시작했습니다. 아래 내용은 간단한 튜토리얼로 Emacs와 org-mode를 사용하는 방법을 설명합니다.

Emacs에 대해 알아야 할, 정말 최소한의 지식

무엇이든지 하고싶은 일을 하기 위해서 Emacs에서 필수적으로 알아야 할 최소 지식은 다른 애플리케이션에서 알아야 하는 양보다 많습니다. 하지만 이런 비교는 일반적인 장난감과 레고를 비교하는 것과 같습니다. 레고는 시작하기 어렵지만 (작은 플라스틱 조각이 가득한 상자에서 시작합니다) 장기적으로 봤을 때는 더 많은 것을 만들 수 있습니다.

Emacs는 단축키가 풍부합니다. 처음 시작할 때는 이런 특징에 짜증날지 모르지만 시간이 흐를수록 마우스를 점점 적게 사용하게 되고 실제로 더 빠르게 작업을 할 수 있게 될겁니다.

기본적인 모든 동작은 마우스를 사용할 수 있습니다. 파일을 열거나 저장하는 등의 작업은 메뉴에서 모두 가능한 동작입니다. 하지만 키보드에서 손을 때고 마우스를 잡는 방법보다 단축키를 사용하는 방식이 훨씬 빠르다는 것을 알게될 것입니다.

Emacs는 이중 단축키를 많이 사용합니다. 대부분의 애플리케이션처럼 Alt-F 나 Alt-S 대신에 Control-X Control-F 와 Control-X Control-S 를 사용합니다. 처음에는 생산성에 반하는 것처럼 느껴질지 몰라도 금방 익숙해질 겁니다.

노트: 키 축약 표현

M – Alt (고대 키보드에서는 Meta 키였습니다.)
C – Control
S – Shift
C-x f – 이 표기는 Control 과 x를 누른 후, 둘 다 손을 땐 다음에 f를 누른다는 의미입니다.

어느 버전의 Emacs를 사용해야 하나요?

어느 버전이든 다 똑같이 느껴진다면 XEmacs보다 Emacs를 선택하기 바랍니다. (이 말에 동의하지 못한다면 이미 이 문장을 넘겨도 될 만큼 알고 있다는 의미입니다.) 다음 링크가 도움이 될 겁니다.

리눅스에서는 패키지 매니저를 사용해서 Emacs를 설치합니다. 데비안이라면 다음처럼 설치합니다.

sudo apt-get install emacs

설정하기

Emacs를 시작할 때 가장 큰 고통은 바로 설정하기에 있습니다. 설정을 위한 메뉴도 없고 텍스트 파일을 수정해야 합니다. (메뉴가 있다고 얘기하긴 하는데 그건 그냥 순수한 사람들을 낚는 겁니다.) 설정 파일의 위치는 (심지어 이름까지도) 어떤 운영체제를 사용하느냐에 따라 다릅니다. 하지만 플랫폼에 상관없이 그 내용은 거의 일치합니다. 대다수 사람들은 동일한 설정 파일을 다른 운영체제서 사용합니다. 장기적으로 보면 최고의 선택이나 마찬가지죠!

설정 파일의 위치는 다음과 같습니다.

Aquamacs: ~/Library/Preferences/Aquamacs Emacs/Preferences.el
일반적인 emacs on Linux or OS X: ~/.emacs
Windows: c:\emacs\.emacs.d\init.txt (예제 설치에 따르면 이렇습니다)

org-mode 시작하기

이 챕터에서 사용하는 새로운 단축키는 다음과 같습니다.

C-x s – 문서 저장하기
C-x f – 문서 열기

첫 org-mode 문서

이제 첫 org-mode 문서를 시작하기 위해서 알아야 할 모든 지식을 습득했습니다. Emacs를 시작합니다. 완전히 새로 설치한 Emacs라면 Emacs의 스플래시 화면을 볼 수 있을 겁니다. 이 화면에는 Emacs 튜토리얼과 여러 문서를 볼 수 있는 바로가기가 있지만 지금은 건너뛰고 다음으로 넘어갑니다.

C-x f 단축키를 사용해서 새 문서를 시작합니다. 이 단축키는 문서를 열기 위한 기능을 제공합니다. (Emacs에서는 버퍼라고 말합니다.) 여기에 *1.org*라고 입력합니다. 이제 새로운 빈 문서가 화면에 나타납니다.

이 문서를 저장하기 위해서 저장 아이콘을 누르거나 C-x s 단축키를 누르고 1.org를 입력합니다.

Emacs는 org-mode 문서를 편집하려고 한다는 점을 아직 이해하지 못합니다. 현재 문서에서 org-mode를 활성화하려면 다음 명령을 입력합니다.

M-x org-mode

이 명령으로 현재 문서에서 org-mode를 활성화 할 수 있습니다.

Emacs가 org-mode 문서를 인식하도록 다음 내용을 문서 상단 에 추가합니다.

MY PROJECT -*- mode: org -*-

여기에 사용한건 뺄셈 기호며 밑줄이 아닙니다. MY PROJECT는 문서의 제목이며 마음대로 지정할 수 있습니다.

이 한 줄의 내용이 이 문서에서 org-mode를 활성화합니다. 이 내용을 넣으면 파일 확장자와 상관없이 org-mode가 동작합니다.

org 파일에서 항상 org-mode를 활성화하려면 Emacs 설정을 수정해야 합니다. 수정하는 방법은 다음 섹션에서 설명합니다.

Emacs 설정 처음으로 수정하기

Emacs 설정 파일을 엽니다. Emacs에서 이 파일을 열기 위해서 C-x f 를 사용합니다. (설정 파일의 경로는 설정을 참고합니다.) 그리고 다음 내용을 추가합니다.

;; -*- mode: elisp -*-

;;스플래시 화면을 끔 (다시 켜려면 t를 0으로 변경)
(setq inhibit-splash-screen t)

;;문법 강조를 활성화
(global-font-lock-mode t)
(transient-mark-mode 1)

;;;;org-mode 설정
;;org-mode 활성화
(require 'org)
;;org-mode를 .org로 끝나는 파일에서 활성화
(add-to-list 'auto-mode-alist '("\\.org$" . org-mode))

Emacs를 재시작합니다.

노트: 앞에서 추가했던 mode 행은 1) Emacs의 설정에 지정한 org-mode 확장자와 다른 확장자를 사용하는 경우 (예로 myfile.txt) 2) auto-mode-alist 행을 설정에 추가하지 않은 경우에만 필요합니다.

목록과 노트 관리하기

이 장에서 사용하는 단축키입니다.

TAB / S-TAB – 접기/펴기
M-up/down – 제목행 위/아래로 이동하기
M-left/right – 제목행 수준 높이기/낮추기
M-RET – 새 제목행 추가하기
C-x s – 파일 저장하기
C-h t – Emacs 튜토리얼

이제 org-mode 문서를 사용할 수 있도록 설정한 Emacs가 있으니 이제 시작하기만 하면 됩니다. org-mode를 시작하는데 도움이 될 개요를 적는 것으로 시작합니다. 새 문서를 열고 (C-x b) 2.org를 입력한 다음에 아래 내용을 복사해서 붙여넣습니다.

#-*- mode: org -*-
#+STARTUP: showall

* org-mode 시작을 환영합니다
  Org-mode에 오신 것을 환영하고 감사드립니다. org에서 개요를 작성하기는 매우 간편합니다.
  그냥 텍스트거든요! 그저 입력하면 됩니다.

* 제목행은 하나 이상의 별 문자로 시작합니다.
  제목은 별 하나, 부제목은 별 두 개 방식으로 숫자를 늘려갑니다.

* 목록 작성하기
** 개요 이동하기
** 제목행 이동하기

파일을 2.org로 저장합니다. (C-x s) 저장하면 문법 강조가 켜져있어서 색상이 변경되는 것을 확인할 수 있습니다. Emacs가 org-mode에서 작업중인 것을 알고 있기 때문입니다.

이제 정말로 org-mode를 시작할 준비가 되었습니다!

목록 작업하기

목록은 브레인스토밍과 모든 항목을 관리하는데 뛰어난 방식입니다. 목록을 사용하면 기록을 하는 동안 큰 그림 그리기에 집중할 수 있도록 돕습니다.

가장 먼저 할 일은 접기입니다. 특히 문서가 길어질 때는 이 기능이 유용합니다. 예제 문서에서 첫 제목행인 이동합니다. (방향키를 사용하세요.) org-mode 시작을 환영합니다 에 커서를 위치한 후에 TAB 을 눌러봅니다. 그리고 S-TAB 도 사용해봅니다. Tab 은 현재 부분을 접거나 펼 수 있습니다. 시프트 키와 함께 누르면 전체 문서를 접고 펼 수 있습니다.

브레인스토밍의 기본적인 아이디어는 항목을 목록으로 적는 것입니다. 적은 후에 항목의 순서를 중요도 순서로 다시 정렬하고 싶을 것입니다. 제목행을 위로, 또는 아래로 이동하기 위해서 제목행에서 M-up/down 을 사용할 수 있습니다. 목록을 모두 접어서 제목만 보이는 상태는 전체 개요를 파악하는데 도움됩니다. 동시에 세부적인 내용도 잃어버리지 않고 잘 보존하고 있습니다.

다음으로 제목 계층을 올리거나 낮출 수 있습니다. 예를 들어 제목행은 하나 이상의 별 문자로 시작합니다. 행을 목록 작성하기 의 부제로 만들고 싶다면 제목의 위치를 아래로 이동한 후에 M-right 으로 계층을 낮출 수 있습니다.

마지막으로 새 제목행을 추가하기 위해서는 M-RET 을 사용합니다.

목록은 순서 없는 목록과 순서 있는 목록이 있습니다. 다음을 확인하세요.

** 반지의 제왕
   가장 좋아하는 장면 (순서대로)
   1. 로히림 전투
   2. 에오윈과 마술사왕의 싸움
      + 이 내용은 이미 책에서도 가장 좋아하는 장면
      + 미란다 오토를 정말 좋아함
   3. 레골라스에게 화살 맞는 피터 잭슨
      - DVD에만 있음
      화살 맞을 때 정말 웃긴 표정이었음.
   하지만 결과적으로 각각의 장면이 아니라 영화 전체가 좋았다.
   영화에서 중요했던 배우:
   - 일라이저 우드 :: 프로도 역
   - 숀 애스틴 :: 샘 역, 프로도 친구로 나옴. 여전히 그를 구니스에서 나온 미키 월쉬로
     잘 기억하고 있음.

순서 없는 목록은 -, + 또는 \*로 시작합니다. 순서 있는 목록은 숫자와 점으로 시작합니다. 설명은 ::이 붙습니다.

더 보기: 이 스크린캐스트 에서는 일반 목록의 몇 가지 기능을 설명합니다. 이 내용은 메뉴얼 에서도 볼 수 있습니다.

기록하기

내용을 작성할 때 쓸 수 있는 몇 가지 표준적인 마크업이 있습니다. 다음과 같은 마크업을 사용할 수 있습니다.

단어에 *굵게*, /기울임꼴/, _밑줄_, =코드=, ~요약~ 등의 마크업을 쓸 수 있다. 꼭 필요한 경우 +삭제선+도 가능하다.

다음처럼 표현됩니다.

단어에 굵게, 기울임꼴, 밑줄, 코드, 요약 등의 마크업을 쓸 수 있다. 꼭 필요한 경우 ~~삭제선~~ 도 가능하다.

여기까지 봤다면 Emacs 튜토리얼을 살펴보는 것도 좋습니다. C-h t 로 Emacs에 내장되어 있는 튜토리얼을실행할 수 있습니다. 튜토리얼은 몇 가지 Emacs 단축키와 함께 어떻게 문서를 이동하는지 알려줄 것입니다.

할 일 항목 사용하기

이 챕터에서 사용하는 새 단축키입니다.

S-left/right – 워크플로를 변경
C-c C-v – 현재 문서에 있는 할 일 목록 보기

기본 할 일 기능

org-mode를 사용하는 가장 큰 이유는 할 일을 관리하는데 사용하기 위해서 입니다. 먼저 할 일 기능을 사용하기 위해서는 특별히 해야 하는 작업 없이 TODO 키워드를 제목행에 추가하면 됩니다.

** TODO 비행기 구입하기

할일 목록을 빠르게 사용하려면 다음 단축키를 사용합니다.

S-left/right

이 단축키는 TODO 에서 DONE 까지, 그리고 빈 칸을 순환하며 상태를 변경합니다.

큰 문서를 작업하고 있고 문서 곳곳에 할 일 목록이 흩어져 있는 상황에서는 C-c / t 로 현재 할 일 항목만 남기고 나머지는 모두 접을 수 있습니다.

할 일 설정하기

파일 내에서 설정하기
Org-mode 파일에서는 워크플로 상태를 파일 시작 위치에서 설정할 수 있습니다. 다음과 같이 파일 시작부에 작성합니다.
```
#+TODO: TODO IN-PROGRESS WAITING DONE
```
이 행은 파일 상단에 위치해야 하며 상단과 #+TODO 행 사이에 빈 행이 없어야 합니다.

새 워크플로를 활성화하기 위해서는 파일을 새로 열거나 파일 최상단에 #로 시작하는 행으로 이동한 다음에 C-c C-c 를 입력합니다.

워크플로를 복사해서 테스트 파일인 1.org에 붙여놓고 차이를 확인해봅시다.
Emacs 설정 파일에서
워크플로 상태를 모든 org 파일에 직접 추가하는 방법은 번거롭습니다. 어디서나 사용할 수 있도록 설정하려면 설정 파일에 추가합니다. 다음 내용은 (require 'org) 행 이후에 추가합니다.
```
(setq org-todo-keywords
  '((sequence "TODO" "IN-PROGRESS" "WAITING" "DONE")))
```
워크플로 상태를 활성화하기 위해서 Emacs를 재시작합니다.

아젠다

이 장에서 사용하는 단축키입니다.

C-c a – 아젠다
C-c [ – 아젠다 파일 목록에 문서를 추가
C-c ] – 아젠다 파일 목록에서 문서를 제거
C-c . – 일자 추가
C-u C-c . – 일자와 시각 추가
C-g – 하던 일을 멈추고 벗어남

아젠다(agenda)라는 단어의 기본적인 의미는 완료 해야 할 것 으로 라틴어인 agendum 에서 왔습니다. Org-mode는 다양한 종류의 아젠다, 일감 목록을 만들고 하나 또는 여러 org 문서에서 이런 일감을 수집하기 매우 좋습니다.

활성화된 모든 일감 목록 생성하기

1.org를 기본 아젠다 파일로 사용하고 나중에 Emacs의 설정 파일에서 어떻게 동작하는지 살펴보겠습니다.

1.org를 엽니다. C-c a 를 눌러서 아젠다를 엽니다. 아젠다는 다음처럼 나옵니다.

Press key for an agenda command
-------------------------------
a Agenda for the current week or day
t List of all TODO entries

위 내용은 일부 내용이고 실제로는 더 많은 내용이 출력될 것입니다.

아쉽게도 위 두 항목은 빈 목록을 보여줄 것입니다. (직접 눌러서 확인해볼 수 있습니다.) 그러므로 이 상태에서 C-g 를 눌러 빠져 나옵니다. 이제 1.org를 아젠다 파일로 추가하기 위해서 C-c [ 를 사용합니다. 이제 아젠다 메뉴로 가서 (C-c a) t 를 누르면 모든 할 일 항목 목록을 확인합니다.

할 일 항목 사용하기에서 설명한 방식대로 더 적절한 워크플로를 추가하는 과정을 했다면 DONE을 제외한 모든 항목이 모두 나타나는 것을 볼 수 있습니다.

이 과정은 여러 문서에서 반복할 수 있습니다. 아젠다는 할 일 전체 목록을 제공할 것입니다. 만약 문서를 아젠다 파일 목록에서 빼고 싶다면 C-c ] 를 사용하면 됩니다.

약속과 마감 일시

일반적으로 시간 설정이 필요한 일감은 달력에 표시합니다. org-mode는 이 방식도 지원합니다. 아젠다는 모든 할 일을 시간 기반 목록으로 볼 수 있습니다. 다음 내용을 참고하기 바랍니다.

1.org에 새 (부)제목을 프레드에게 전화하기 라고 추가합니다. (M-RET프레드에게 전화하기) 다 입력한 후에 C-c . 를 입력합니다. 이 명령을 입력하면 화면 밑에 일자 선택지가 표시됩니다. 직접 손으로 입력할 수도 있고 S-left/right 으로 선택할 일자를 변경할 수 있습니다. 만약 일자 외에 시간도 추가하고 싶다면 C-c . 대신에 C-u C-c . 를 입력합니다.

이제 아젠다 (C-c a)로 이동해서 a 를 누르면 아젠다 항목을 확인할 수 있습니다.

더 읽을 거리:

http://doc.norang.ca/org-mode.html#ClockingBernt Hansens extensive description Time Clocking: Usage, Customization, Workflow description
Clocking time with Emacs Org
그리고 메뉴얼도 있습니다.

Emacs 설정 파일에서 아젠다 설정하기

C-c [ 을 사용해서 아젠다 목록에 추가한 후에 Emacs의 설정 파일을 확인하면 다음 내용을확인할 수 있습니다.

(custom-set-variables
  ;; custom-set-variables was added by Custom.
  ;; If you edit it by hand, you could mess it up, so be careful.
  ;; Your init file should contain only one such instance.
  ;; If there is more than one, they won't work right.
 '(org-agenda-files (quote ("~/Documents/Projects/org4beginners/2.org"
 "~/Documents/Projects/org4beginners/1.org"))))
(custom-set-faces
  ;; custom-set-faces was added by Custom.
  ;; If you edit it by hand, you could mess it up, so be careful.
  ;; Your init file should contain only one such instance.
  ;; If there is more than one, they won't work right.
 )

Emacs lisp의 세계에 오신 것을 환영합니다. Emacs가 설정 파일을 변경한 경우에 이런 방식으로 기록됩니다. (참고: Aquamacs 에서는 customizations.el이라는 별도 파일에 저장됩니다.)

여기서 중요한 내용은 중간에 있는데 (5, 6행) org-agenda-files 내용을 확인할 수 있습니다. 아젠다 목록을 만들기 위해 사용하는 아젠다 파일의 목록이 여기에 지정되어 있습니다. 지금은 일단 그대로 둡니다. 다음에 설정 파일을 살펴볼 일이 있다면 적어도 이게 무슨 기능을 하는지 알 수 있을 것입니다.

더 읽을 거리: 사용자 정의 아젠다 명령

GTD

이 챕터에서 사용하는 단축키입니다.

C-c C-c – 태그 추가

Getting things done 은 유명한 시간 관리 방법 중 하나로 구글에서 검색하면 1억 5천 여 항목에 이릅니다. 태그를 사용하면 org mode에서도 비슷한 방식으로 할 일 관리를 할 수 있습니다.

태그는 다른 종류의 할일 목록을 조직화하는데 사용합니다. 예를 들면 전화 일정, 읽을 책 목록, 장바구니 목록을 묶기 위해 씁니다.

태그를 추가하기 위해서 다음 설정을 문서 상단에 추가합니다.

#+TAGS: { @OFFICE(o) @HOME(h) } COMPUTER(c) PHONE(p) READING(r)

문서를 다시 불러오거나 #으로 시작하는 곳에서 C-c C-c 를 입력합니다.

이제 문서 어느 행에서든 하나 또는 그 이상의 태그를 등록할 수 있습니다. C-c C-c 를 누르면 다음과 같은 팝업이 나타납니다.

Inherited:
Current:
{ [o] @OFFICE     [h] @HOME    }
  [C] COMPUTER   [p] PHONE   [r] READING

문서 서두에 정의한 태그를 사용할 수 있는 바로가기입니다. 첫 두 태그는 (OFFICE와 HOME)은 상호배타적이라 둘 중 하나만 선택할 수 있지만 나머지는 자유롭게 추가할 수 있습니다.

GTD 설정의 좋은 예제로는 이 글을 참고하세요: Emacs에 Org-mode를 사용해서 GTD 구현하기

Emacs 설정 파일에 태그 추가하기

Emacs 설정 파일에 태그를 추가하려면 다음처럼 설정에 입력합니다.

(setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l)))

설정 파일에서 상호배타적인 태그 그룹을 만들기 위해서는 메뉴얼 내용을 참고합니다.

이 설정은 문서 상단에 추가한 내용으로 덮어쓰는 것이 가능합니다. 그래서 각 문서에 개별적인 워크플로와 태그를 직접 설정해서 사용할 수 있습니다.

태그를 활발히 활용하는 예제는 여기서 확인할 수 있습니다.

내보내기

여기서 사용하는 단축키는 다음과 같습니다.

C-c C-e – 내보내기 메뉴

org-mode에서만 문서 작업을 한다면 큰 문제가 없습니다. 하지만 간혹 다른 포맷으로 문서를 내보내야 할 필요가 있습니다.

예를 들어 현재 문서를 내보내는데 html로 내보내려고 합니다. C-c C-e 를 누른 후에 h o 를 순서대로 누릅니다. 이 방법은 문서를 html로 내보낸 후, 그 내보낸 파일을 브라우저로 열게 됩니다.

더 읽을 거리: html 출판 튜토리얼을 보면 여기서 설명한 내용보다 더 상세하게 다룹니다. 이 방법으로 완전한 웹사이트를 출판하는 것도 가능합니다. 그리고 메뉴얼에서 html, latex, pdf 그리고 다른 포맷으로 내보내는 방법을 설명합니다.

org-mode에 능숙해지기

효율적인 도구를 사용해서 시간을 아끼려면 그 도구를 잘 알아야 합니다. org-mode를 잘 알기 위해서는 메뉴얼을 읽고 사용하는게 중요합니다. Org-mode는 문서화가 잘 되어 있습니다. 가장 빠르게 org-mode 문서를 Emacs에서 읽는 방법으로는 info browser를 사용할 수 있습니다.

이 창을 호출하기 위해서는 C-h i를 입력합니다. 그리고 링크 간 이동하기 위해서 TAB 키를 사용합니다.

info-browser를 이동할 때는 다음 키를 쓸 수 있습니다.

u – 위로(up)
n – 다음(next)
p – 이전(previous)

org-mode 메뉴얼 다음으로는 worg 웹사이트가 있습니다. 여러 재밌는 아이디어와 튜토리얼을 찾을 수 있습니다.

기능을 빠르게 참고할 수 있는 org-mode 치트시트와 emacs 치트시트가 있습니다. 이 두 문서는 귀찮은 단축키를 기억하는데 도움이 될 것입니다.

기초를 넘어서

Geek 유머에 "여기에 용이 있어요!"가 있습니다. 여기서부터는 org-mode를 자유롭지만 스스로 책임져야 하는 사용법을 설명합니다. 대부분 다음 내용은 실제로 정말 어렵거나 한 것은 아니지만 적어도 중요한 데이터는 백업을 해두시기 바랍니다. 만약 다음 내용에서 궁금한 부분이 있다면 메뉴얼과 질문 답변을 확인합니다. 또한 IRC (freenode의 #orgmode)에서 질문하는 것도 좋은 방법입니다.

TODO Quickly adding tasks with remember

(역주: 아직 내용이 존재하지 않는 항목입니다.)

Publishing Org-mode files to HTML

Introduction

This Tutorial describes one of many ways to publishing Org-mode files to XHTML. We use the publishing mechanism to keep the *.html files separated from our *.org files and to access them via web browser. Simply exporting the Org-mode files to HTML would leave them in ~/org/.

The XHTML files we create will work every where, on any host, with or without network access, and even when accessed through the file:/// protocol. To achieve this goal, we use

no absolute paths in HTML,
no server side scripting to navigate our output directories,
no base element (which is optional as of XHTML 1.0 strict) and
no software, but emacs, Org-mode and a web browser.

All this means, we are able to check and use the result of work immediately, everywhere.

Basics

Throughout this tutorial, let's assume that all our Org-mode files live beneath ~/org/ and we publish them to ~/public_html/.

Let's further assume you're already familiar with the note taking basics in org and able to add a little content to the Org-mode files we add to our project during this tutorial. Please add at least one headline to each of the files.

The first thing to do is to create the folder ~/org. This is where our notes files live. Inside ~/org/ we have a folder css/ for stylesheets and scripts, and a folder called img/ (guess what's in there).

The first file we add to that folder (and to subdirectories later on) is called index.org. This name was choosen, since Org will publish the files to those with the basename of the source file plus the extension .html 1. Thus ~/org/index.org will once be ~/public_html/index.html – the startpage.

Let's add another file and call it ~/org/remember.org. After adding a stylesheet, ~/org/ looks like this:

~/org/
   |- css/
   |  `- stylesheet.css
   |- img/
   |- index.org
   `- remember.org

When ever you want to add link to a file, do it the usual way. To link from index.org to remember.org, just write

[[file:remember.org][remember]]

Org will convert those links to HTML links for you on export:

<a href="./remember.html">remember</a>

Same is true for images. To add an image, put it in ~/org/img/test.jpg and refer to it by

[[file:img/test.jpg]]

You may test your links by clicking on them. To test image links you may also try to turn on iimage-mode 2 which works without problems here.

Optionally, set up the stylesheet as shown in section Special comment section. The recommended way is to use a real stylesheet though.

Publishing the org project

To publish the ~/org/ project to HTML, we'll have to setup the variable org-publish-project-alist 3. I tend to split each project in three basic components as described in the manual. We need these different components, since we want org to use two different functions to publish dynamic content (org => html) and static content like scripts, images, stylesheets or even .htaccess files (org => copy). The third component is just for convenience and tells org to execute the former ones.

org-publish-project-alist may be adjusted using customize (M-x customize-variable RET org-publish-project-alist RET), but I prefere to use an extra file to setup my projects, since there are quite a few. To follow this tutorial use the *scratch* buffer and put all the Lisp in this section in there.

First of all, enter this into the *scratch* buffer:

(require 'ox-publish)
(setq org-publish-project-alist
      '(

       ;; ... add all the components here (see below)...

      ))

Be sure to put all the components below right there where the comment line is now.

The notes component

The notes component publishes all the Org-mode files to HTML. Hence the publishing-function is set to org-publish-org-to-html. Here is an example of the notes component:

("org-notes"
 :base-directory "~/org/"
 :base-extension "org"
 :publishing-directory "~/public_html/"
 :recursive t
 :publishing-function org-html-publish-to-html
 :headline-levels 4             ; Just the default for this project.
 :auto-preamble t
 )

Note, that headline-levels may be adjusted on a per file basis to overwrite the default.

The most important settings here are:

base-directory	The components root directory.
base-extension	Filename suffix without the dot.
publishing-directory	The base directory where all our files will be published.
recursive	If t, include subdirectories - we want that. Subdirectories in :publishing-directory are created if they don't yet exist.
publishing-function	If and how org should process the files in this component. In this case: convert the Org-mode files to HTML.

The static component

The static component just copies files (and their folders) from :base-directory to :publishing-directory without changing them. Thus let's tell Org-mode to use the function org-publish-attachment:

("org-static"
 :base-directory "~/org/"
 :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf"
 :publishing-directory "~/public_html/"
 :recursive t
 :publishing-function org-publish-attachment
 )

Note that :publishing-function is set to org-publish-attachment.

The publish component

To publish all with one command, we add the publish component. For this component I usually drop the suffix and just use the basename of the project.

("org" :components ("org-notes" "org-static"))

Now M-x org-publish-project RET org RET publishes everything recursively to ~/public_html/. Target directories are created, if they don't yet exist.

Pooh - can we publish now?

The good message is yes, we can. Just one little hump. Since we've put the definition for our publishing components in the *scratch* buffer, again, make sure all the components are enclosed by the lines

(require 'ox-publish)
(setq org-publish-project-alist
      '(

       ;; ... all the components ...

      ))

Move to the end of the first line and press C-x C-e to load org-publish. Now go to the end of the last line and press C-x C-e again. Repeat the last step after every change to your org-publish-project-alist.

To publish your Org-mode files just type M-x org-publish-project RET org RET or use one of the shortcuts listed in the manual. If nothing went wrong, you should now be able to point your browser to http://localhost/~user/, if mod_userdir is set up. If not, simply navigate to file:///home/user/public_html (you might use file -> open from the file menu of your browser.

Adding directories

As we add more and more files to ~/org/, we will soon end up with filenames like 'networking-ssh-sshd-config.org' or longer. What we need is a directory structure:

~/org/
  |- css/
  |  `- stylesheet.css
  |- Emacs
  |  |- index.org
  |  |- gnus.org
  |  |- org.org
  |  `- snippets.org
  |- img/
  |- index.org
  `- remember.org

If we hadn't added

:recursive t

in the notes and static components already, we would have to do it now at the latest to export the subdirectories too.

Overwrite the defaults

The defaults set by org-publish-project-alist may be overwritten. You might want to justify the export properties for single files. Be it the level of headlines, include extry scripts or different stylesheets. Org offers ways to adjust the settings for a single file.

The export options template

The first choice is the export options template on top of the file. When in an Org-mode file, you may insert basic information using C-c C-e # (org-export-dispatch) plus "template". You will be prompted for a template choice. "default" will provide a template for common options, and "html" will provide a template for HTML-specific options.

WARNING: Do not copy lines from the sample output below into your files. The template might change from release to release. Instead, insert a template as above and delete any entries that are not applicable.

The default option inserts the following lines:

#+TITLE: filename with the extension omitted
#+DATE: <2013-06-04 Tue>
#+AUTHOR: Your name
#+EMAIL: Your email address
#+OPTIONS: ':t *:t -:t ::t <:t H:3 \n:nil ^:t arch:headline author:t c:nil
#+OPTIONS: creator:comment d:(not LOGBOOK) date:t e:t email:nil f:t inline:t
#+OPTIONS: num:t p:nil pri:nil stat:t tags:t tasks:t tex:t timestamp:t toc:t
#+OPTIONS: todo:t |:t
#+CREATOR: Emacs 24.3.50.3 (Org mode 8.0.3)
#+DESCRIPTION:
#+EXCLUDE_TAGS: noexport
#+KEYWORDS:
#+LANGUAGE: en
#+SELECT_TAGS: export

and the html option will add the following:

#+OPTIONS: html-postamble:auto html-preamble:t tex:t
#+CREATOR: Emacs 24.3.50.3 (Org mode 8.0.3)
#+HTML_CONTAINER: div
#+HTML_DOCTYPE: xhtml-strict
#+HTML_HEAD:
#+HTML_HEAD_EXTRA:
#+HTML_HTML5_FANCY:
#+HTML_INCLUDE_SCRIPTS:
#+HTML_INCLUDE_STYLE:
#+HTML_LINK_HOME:
#+HTML_LINK_UP:
#+HTML_MATHJAX:
#+INFOJS_OPT:

All we have to do now is to alter the options to match our needs. All the options are listed in the wonderful Org-mode manual. Note though, that these options are only parsed on startup (i.e., when you first open the file). To explicitly apply your new options move on any of those lines and press C-c twice.

Special comment section

Also, CSS style variables may be using a special section may be #insert/appended to Org-mode files:

* COMMENT html style specifications

# Local Variables:
# org-html-head: "<link rel=\"stylesheet\" type=\"text/css\" href=\"css/stylesheet.css\" />"
# End:

css/stylesheet.css suits the needs for a file in the root folder. Use
../css/stylesheet.css in a subfolder (first level),
../../css/stylesheet.css for a file in a sub-sub-folder.

Tired of export templates?

If you're like me, you will soon get tired of adding the same export options template to numerous files and adjust the title and paths in it. Luckily, Org-mode supports laziness and offers an additional way to set up files. All we need is a directory (e.g. ~/.emacs.d/org-templates/) and create the following files there:

level-0.org
This file contains all export options lines. The special comment section will not work for files in subdirectories. Hence we always use the export options line :#+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" /> …suitable for each file in the projects root folder (~/org/ or ~/B/ in the examples). Just drop the #+TITLE since this will be different for every file and automatically set on export (based on the filename if omitted).
level-1.org
This file contains all export options lines for the stylesheet suitable for each file in a subfolder of the projects root folder (e.g. ~/org/emacs/ or ~/org/networking/). Just drop the #+TITLE again. The options line for the stylesheet looks like this: :#+STYLE: <link rel="stylesheet" type="text/css" href="../stylesheet.css" />
Add more files for more levels.

Now remove the special comment section from the end of your Org-mode files in the project folders and change the export options template to

#+SETUPFILE: ~/.emacs.d/org-templates/level-N.org
#+TITLE: My Title

Replace N with distance to the root folder (0, 1 etc.) of your project and press C-c twice while still on this line to apply the changes. Subsequent lines still overwrite the settings for just this one file.

More level files

Also, these level-N files give us the chance to easily switch between different export setups. As an example, we could have a separate stylesheet and org-info.js setup for presentations, and put the appropriate options in a file named level-0-slides.org:

#+INFOJS_OPT: path:org-info.js
#+INFOJS_OPT: toc:nil view:slide
#+STYLE: <link rel="stylesheet" type="text/css" href="slides.css" />

Now it's as simple as typing '-slides' to change the appearance of any file in our project.

More Projects

As we get used to note taking in org, we might add an org directory to most of our projects. All those projects are published as well. Project '~/B/' is published to '~/public_html/B/', '~/C/' is published to '~/public_html/C/', and so on. This leads to the problem of common stylesheets and current JavaScripts — and to a new component.

The inherit component

Once we get tired of copying the static files from one project to another, the following configuration does the trick for us. We simply add the inherit component, that imports all the static files from our ~/org/ directory 4. From now on, it will be sufficient to edit stylesheets and scripts just there.

("B-inherit"
 :base-directory "~/org/"
 :recursive t
 :base-extension "css\\|js"
 :publishing-directory "~/public_html/B/"
 :publishing-function org-publish-attachment
)

("B-org"
:base-directory "~/B/"
:auto-index t
:index-filename "sitemap.org"
:index-title "Sitemap"
:recursive t
:base-extension "org"
:publishing-directory "~/public_html/B/"
:publishing-function org-publish-org-to-html
:headline-levels 3
:auto-preamble t
)
("B-static"
 :base-directory "~/B/"
 :recursive t
 :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf"
 :publishing-directory "~/public_html/B/"
 :publishing-function org-publish-attachment)

("B" :components ("B-inherit" "B-notes" "B-static"))

Note, that the inheritance trick works for non org directories. You might want to keep all your stylesheets and scripts in a single place, or even add more inheritance to your projects, to import sources from upstream.

Note also, that B-inherit exports directly to the web. If you want to track the changes to ~org/*.css directly in ~/B, you must ensure, that B-inherit is the first component in B since the components in B are executed in the sequence listed: first get the new stylesheet into B, then execute B-static.

One more Example

As I use org-info.js and track Worg git, I use "inherit-org-info-js" in all my org projects:

("inherit-org-info-js"
 :base-directory "~/develop/org/Worg/code/org-info-js/"
 :recursive t
 :base-extension "js"
 :publishing-directory "~/org/"
 :publishing-function org-publish-attachment)

;; ... all the rest ... ;;

("B" :components ("inherit-org-info-js" "B-inherit" "B-notes" "B-static"))
("C" :components ("inherit-org-info-js" "C-inherit" "C-notes" "C-static"))
("D" :components ("inherit-org-info-js" "D-inherit" "D-notes" "D-static"))
("E" :components ("inherit-org-info-js" "E-inherit" "E-notes" "E-static"))

…means, B C D and E use my local stylesheets and always the latest version of org-info.js.

Overview

Once there are lots of files and subdirectories, we're in the need of ways to easily navigate our notes in a browser. What we need now, is an index, an overview of all our note files.

The sitemap

Org-modes great publishing also generates a recursive sitemap. Its name defaults to sitemap.org, which get's in our way, since we have a real startpage as sitemap.html 5. Fortunately there is a configuration option to change the name of the generated sitemap. To generate the sitemap, add these lines to the notes component:

:auto-sitemap t                ; Generate sitemap.org automagically...
:sitemap-filename "sitemap.org"  ; ... call it sitemap.org (it's the default)...
:sitemap-title "Sitemap"         ; ... with title 'Sitemap'.

The sitemap will reflect the tree structure of the project. To access the sitemap easily, we could do two things:

Setup the 'UP' link of the Startpage to link to sitemap.html (see next section),
use the '#+INCLUDE: sitemap.org' directive. Most of my Org-mode files contain a chapter called "Links" at the end of the file, which contains a subsection Sitemap that in turn just consists of that diretive. For the index.org files in the root directory, I include the sitemap as the first section.

You can also change the position of folders with :sitemap-sort-folders, this can be set to last or first (default), to display folders last or first.

org-info.js

Another way to get additional links to navigate the structure is org-info.js. Let's set it up like this (either in every file, or in org-level-N.org, where N > 0):

#+HTML_LINK_UP: index.html

This makes the little UP link ('h') point to the index.html in the current directory.

The index.org in the root of the project has the index file as section 2 (which I may reach pressing 'n' then), and the same option set like this:

#+HTML_LINK_UP: sitemap.html

For an index.org in a subdirectory:

#+HTML_LINK_UP: ../index.html

The HTML_LINK_HOME always points to the same file:

#+HTML_LINK_HOME: http://localhost/~user/index.html

Please consider replacing the last one with a relative path (which will be different for every level of subdirectories).

No matter where we are, we may always press H n and we face the sitemap. No matter where we are, we may always press h to move up the tree.

Special symbols

This is a list of LaTeX symbols understood by Org-mode. You may use most of those LaTeX symbols to get the desired results (shown in the first column) when exporting to HTML. Note though, that not all symbols are translated to HTML. They are listed anyway, since they may be used for LaTeX export nonetheless. Some characters in the first column are invisible (spaces). To see them, mark the part of the table using the mouse.

You may produce special HTML characters for verbatim #+BEGIN\_HTML sections using http://www-atm.physics.ox.ac.uk/user/iwi/charmap.html (download link on the bottom of that page).

SymbolLaTeX

	\nbsp
¡	\iexcl
¢	\cent
£	\pound
¤	\curren
¥	\yen
¦	\brvbar
\|	\vert
§	\sect
¨	\uml
©	\copy
ª	\ordf
«	\laquo
¬	\not
	\shy
®	\reg
¯	\macr
°	\deg
±	\plusmn
¹	\sup1
²	\sup2
³	\sup3
´	\acute
µ	\micro
¶	\para
·	\middot
o	\odot
*	\star
¸	\cedil
º	\ordm
»	\raquo
¼	\frac14
½	\frac12
¾	\frac34
¿	\iquest
À	\Agrave
Á	\Aacute
Â	\Acirc
Ã	\Atilde
Ä	\Auml
Å	\Aring \AA
Æ	\AElig
Ç	\Ccedil
È	\Egrave
É	\Eacute
Ê	\Ecirc
Ë	\Euml
Ì	\Igrave
Í	\Iacute
Î	\Icirc
Ï	\Iuml
Ð	\ETH
Ñ	\Ntilde
Ò	\Ograve
Ó	\Oacute
Ô	\Ocirc
Õ	\Otilde
Ö	\Ouml
×	\times
Ø	\Oslash
Ù	\Ugrave
Ú	\Uacute
Û	\Ucirc
Ü	\Uuml
Ý	\Yacute
Þ	\THORN
ß	\szlig
à	\agrave
á	\aacute
â	\acirc
ã	\atilde
ä	\auml
å	\aring
æ	\aelig
ç	\ccedil
è	\egrave
é	\eacute
ê	\ecirc
ë	\euml
ì	\igrave
í	\iacute
î	\icirc
ï	\iuml
ð	\eth
ñ	\ntilde
ò	\ograve
ó	\oacute
ô	\ocirc
õ	\otilde
ö	\ouml
ø	\oslash
ù	\ugrave
ú	\uacute
û	\ucirc
ü	\uuml
ý	\yacute
þ	\thorn
ÿ	\yuml
ƒ	\fnof
Α	\Alpha
Β	\Beta
Γ	\Gamma
Δ	\Delta
Ε	\Epsilon
Ζ	\Zeta
Η	\Eta
Θ	\Theta
Ι	\Iota
Κ	\Kappa
Λ	\Lambda
Μ	\Mu
Ν	\Nu
Ξ	\Xi
Ο	\Omicron
Π	\Pi
Ρ	\Rho
Σ	\Sigma
Τ	\Tau
Υ	\Upsilon
Φ	\Phi
Χ	\Chi
Ψ	\Psi
Ω	\Omega
α	\alpha
β	\beta
γ	\gamma
δ	\delta
ε	\epsilon
ε	\varepsilon
ζ	\zeta
η	\eta
θ	\theta
ι	\iota
κ	\kappa
λ	\lambda
μ	\mu
ν	\nu
ξ	\xi
ο	\omicron
π	\pi
ρ	\rho
ς	\sigmaf \varsigma
σ	\sigma
τ	\tau
υ	\upsilon
φ	\phi
χ	\chi
ψ	\psi
ω	\omega
ϑ	\thetasym \vartheta
ϒ	\upsih
ϖ	\piv
•	\bull \bullet
…	\hellip \dots
′	\prime
″	\Prime
‾	\oline
⁄	\frasl
℘	\weierp
ℑ	\image
ℜ	\real
™	\trade
ℵ	\alefsym
←	\larr
↑	\uarr
→	\rarr
↓	\darr
↔	\harr
↵	\crarr
⇐	\lArr
⇑	\uArr
⇒	\rArr
⇓	\dArr
⇔	\hArr
∀	\forall
\part	\part
∃	\exist
∅	\empty
∇	\nabla
∈	\isin
∉	\notin
∋	\ni
∏	\prod
∑	\sum
−	\minus
∗	\lowast
√	\radic
∝	\prop
∞	\infin
∠	\ang
∩	\cap
∪	\cup
∫	\int
∴	\there4
∼	\sim
≅	\cong
≈	\asymp
≠	\ne
≡	\equiv
≤	\le
≥	\ge
⊂	\sub
⊃	\sup
⊄	\nsub
⊆	\sube
⊇	\supe
⊕	\oplus
⊗	\otimes
⊥	\perp
⋅	\sdot
⌈	\lceil
⌉	\rceil
⌊	\lfloor
⌋	\rfloor
⟨	\lang
⟩	\rang
◊	\loz
♠	\spades
♣	\clubs
♥	\hearts
♦	\diams
⌣	\smile
"	\quot
&	\amp
<	\lt
>	\gt
Œ	\OElig
œ	\oelig
Š	\Scaron
š	\scaron
Ÿ	\Yuml
ˆ	\circ
~	\tilde
	\ensp
	\emsp
	\thinsp
‌	\zwnj
‍	\zwj
‎	\lrm
‏	\rlm
–	\ndash
—	\mdash
‘	\lsquo
’	\rsquo
‚	\sbquo
“	\ldquo
”	\rdquo
„	\bdquo
†	\dagger
‡	\Dagger
‰	\permil
‹	\lsaquo
›	\rsaquo
€	\euro
arccos	\arccos
arcsin	\arcsin
arctan	\arctan
arg	\arg
cos	\cos
cosh	\cosh
cot	\cot
coth	\coth
csc	\csc
°	\deg
det	\det
dim	\dim
exp	\exp
gcd	\gcd
hom	\hom
inf	\inf
ker	\ker
lg	\lg
lim	\lim
liminf	\liminf
limsup	\limsup
ln	\ln
log	\log
max	\max
min	\min
Pr	\Pr
sec	\sec
sin	\sin
sinh	\sinh
tan	\tan
tanh	\tanh

Footnotes:

You may customize the file suffix for exported files like this: M-x customize RET org-html-extension.

…by typing M-x iimage-mode RET. iimage-mode even shows *.svg images, if librsvg was present on compile time. FIXME: is this true for emacs22 ?

All components of org-publish-projects-alist are documented in the Org Mode Manual.

Files may be copied from arbitrary src directories to any target directory desired.

This is primarily because of the behaviour of servers. When we navigate to https://orgmode.org/worg/ we will face the index.html if present.

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.

728x90

저작자표시 비영리 변경금지

Emacs > 논문 쓰기> Org-mode 기초부터 시작하기﻿

Emacs > 논문 쓰기> Org-mode 기초부터 시작하기﻿

Org-mode 기초부터 시작하기

Org-mode 기초부터 시작하기

Emacs에 대해 알아야 할, 정말 최소한의 지식

어느 버전의 Emacs를 사용해야 하나요?

설정하기

org-mode 시작하기

첫 org-mode 문서

Emacs 설정 처음으로 수정하기

목록과 노트 관리하기

목록 작업하기

기록하기

할 일 항목 사용하기

기본 할 일 기능

할 일 설정하기

아젠다

활성화된 모든 일감 목록 생성하기

약속과 마감 일시

Emacs 설정 파일에서 아젠다 설정하기

GTD

Emacs 설정 파일에 태그 추가하기

내보내기

org-mode에 능숙해지기

기초를 넘어서

TODO Quickly adding tasks with remember

최신 버전 org-mode 사용하기

Publishing Org-mode files to HTML

Introduction

Basics

Publishing the org project

The notes component

The static component

The publish component

Pooh - can we publish now?

Adding directories

Overwrite the defaults

The export options template

Special comment section

Tired of export templates?

More level files

More Projects

The inherit component

One more Example

Overview

The sitemap

org-info.js

Special symbols

Further reading

Footnotes:

Emacs > 논문 쓰기> Org-mode 기초부터 시작하기

Emacs > 논문 쓰기> Org-mode 기초부터 시작하기