Org模式是Emacs中一种强大的纯文本标记语言，它不仅能管理待办事项、表格和代码块，还内置了完整的HTML导出引擎。在Ubuntu系统上，不需要额外安装复杂的工具链，只需要配置好Emacs和Org模式，再把自定义的CSS样式注入到导出流程中，就能把.org源文件转换成风格统一、结构清晰的静态网页。这种工作流特别适合技术写作者、开发者以及需要维护内部文档库的团队。完成基础配置后，一条命令或一组快捷键就能完成从源文件到成品网页的全部过程。
Ubuntu下的Emacs与Org模式安装检查
在Ubuntu的官方软件仓库中，Emacs和Org模式通常可以一次性安装到位。使用apt包管理器安装Emacs时，Org模式会作为核心组件被一并放入。如果之前已经安装过Emacs但不确定Org模式是否可用，可以在Emacs中执行M-x org-version查看当前版本。一般来说，Emacs 26及以上版本内置的Org模式已经足够完成绝大多数HTML导出任务，不需要从源码单独编译。
安装Emacs的命令非常简单。打开终端执行下面的命令，系统会自动处理依赖关系。安装完成后，建议先在用户主目录下创建或编辑Emacs配置文件，这个文件通常位于~/.emacs.d/init.el。该文件是后续所有Org模式定制和CSS注入配置的入口。
sudo apt update sudo apt install emacs
如果你使用的是较新的Ubuntu LTS版本，官方仓库中的Emacs包已经足够稳定。对于有特殊需求、希望使用更新版本的用户，也可以考虑通过snap安装，命令为sudo snap install emacs --classic。不过snap版本在访问本地文件系统时有时会遇到权限限制，如果只是用来编辑和导出HTML，官方apt版本是更省心的选择。安装完成后，在终端输入emacs即可启动图形界面，输入emacs -nw则可以在终端中运行。
验证Org模式是否正常加载，可以在Emacs里新建一个扩展名为.org的文件，输入一行标题和正文，然后尝试使用快捷键C-c C-e h h。如果看到导出的HTML文件出现在同一目录下，说明基础环境已经就绪。若提示找不到命令或函数，可以检查init.el中是否误删了必要的加载语句，通常不需要额外require，Org模式默认自动加载。
Org文件结构与HTML导出基础操作
一个Org文件由标题、段落、列表、表格、代码块、链接等多种元素组成。标题使用星号表示层级，一颗星是一级标题，两颗星是二级标题，依此类推。导出HTML时，这些标题会自动转换为<h1>到<h6>标签。段落之间空一行即可分隔，无需添加额外标记。列表可以使用-、+或数字加点号，导出后会变成无序列表或有序列表。
表格是Org模式的强项之一。在Org文件中，表格由竖线和横线组成，单元格内容直接写在竖线之间。导出HTML时，表格会转换为标准的<table>结构，配合CSS可以美化边框和背景色。代码块也是技术文档中频繁出现的元素，使用#+BEGIN_SRC和#+END_SRC包围代码，并在#+BEGIN_SRC后面指定语言类型，例如python、bash、css。导出时Org模式会自动调用相应的语法高亮工具，生成带颜色标注的代码区域。
下面的例子展示了一个典型的Org文件结构，包含标题、段落、列表、代码块和表格。你可以把这段内容保存到demo.org中，然后执行导出命令C-c C-e h h，观察生成的HTML效果。
#+TITLE: Org导出HTML示例 #+AUTHOR: 技术文档小组 #+OPTIONS: toc:t num:t * 项目说明 这是一个用于演示Org模式导出能力的项目文档。 * 功能列表 - 支持标题层级自动转换 - 支持表格与代码块 - 可以注入自定义CSS * 示例代码 #+BEGIN_SRC bash echo "Hello, Org Mode" #+END_SRC * 配置项 | 参数名 | 默认值 | 说明 | |--------+--------+------| | toc | t | 是否生成目录 | | num | t | 是否给标题编号 |
导出时，Org模式会把#+TITLE和#+AUTHOR等元数据写入HTML的<head>区域。如果希望在导出后立即在浏览器中预览，可以使用快捷键C-c C-e h o，它会在导出后用系统默认浏览器打开结果文件。如果要导出到指定目录，可以在Org文件头部设置#+EXPORT_FILE_NAME: output/index.html，或者在导出时通过交互提示选择路径。
HTML导出的默认样式比较朴素，几乎没有视觉美化。这正是很多用户感到困惑的地方：明明内容结构都正确，但生成的网页看起来像上世纪九十年代的文档。实际上，Org模式的设计思想是把内容和样式分离，默认只输出最基础的HTML结构，所有视觉美化都交给CSS完成。只要理解了这一点，下一步就是学会如何把自定义CSS注入到导出流程中。
自定义CSS样式与HTML模板配置
Org模式提供了多种注入CSS的途径，最简单的方法是在Org文件头部使用#+HTML_HEAD关键字。这个关键字后面可以跟任意HTML片段，导出时会被原样插入到生成文档的<head>区域。例如要引入一个外部的style.css文件，可以这样写：
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style.css" />
如果不想在每个Org文件里重复添加这一行，可以在Emacs配置文件中全局设置。打开~/.emacs.d/init.el，加入下面的Lisp代码。这段代码会把org-html-head-extra变量设置为一段固定的HTML片段，这样所有Org文件导出时都会自动带上这个样式链接。
(require 'org)
(setq org-html-doctype "html5")
(setq org-html-head-extra
"<link rel=\"stylesheet\" type=\"text/css\" href=\"style.css\" />")
需要注意的是，href属性中的路径是相对于生成的HTML文件所在目录而言的。如果HTML文件输出到子目录，而CSS文件在项目根目录，则需要使用相对路径如../style.css。这与普通网页开发中的路径规则完全一致。对于希望完全掌控HTML结构的用户，Org模式还支持自定义导出模板，通过设置org-html-head和org-html-preamble等变量，可以替换默认的头部和页眉内容。
下面给出一个常用的style.css示例。这个样式表设置了字体、标题颜色、代码块背景、表格边框以及响应式布局，可以让导出的HTML文档看起来更加现代和专业。将这段CSS保存为style.css，并放在与HTML输出同一目录下，然后重新导出即可看到效果。
body {
font-family: "Noto Sans", "Helvetica Neue", sans-serif;
line-height: 1.7;
max-width: 860px;
margin: 0 auto;
padding: 2rem 1.5rem;
color: #333;
}
h1, h2, h3 {
color: #1a5fb4;
line-height: 1.3;
}
pre.src {
background-color: #f6f8fa;
border: 1px solid #d0d7de;
border-radius: 6px;
padding: 1rem;
overflow-x: auto;
}
table {
border-collapse: collapse;
width: 100%;
margin: 1.2rem 0;
}
th, td {
border: 1px solid #d0d7de;
padding: 0.5rem 0.8rem;
text-align: left;
}
th {
background-color: #f0f3f6;
}
@media (max-width: 600px) {
body {
padding: 1rem 0.8rem;
}
table {
font-size: 0.9rem;
}
}
Org模式导出的HTML代码中，源代码块会被赋予pre.src这样的class，因此上面的CSS选择器可以直接命中代码块。表格、标题等元素也会带有相应的class或标签，可以通过浏览器开发者工具查看具体结构，再针对性地编写样式。如果希望使用更复杂的主题，还可以搜索现成的Org HTML主题，下载其CSS文件并按照同样方式引入。
批量发布与自动化文档生成
当需要维护多个Org文件并统一导出到同一个网站目录时，逐个手动导出效率很低。Org模式内置了发布系统，可以通过org-publish-project-alist变量定义项目。一个项目可以包含多个Org源文件，也可以包含静态资源如CSS和图片。发布系统会按照配置自动完成转换、复制和目录整理工作，非常适合搭建个人知识库或项目文档站。
下面是一段Emacs Lisp配置，定义了一个名为my-docs的发布项目。它把~/org-docs目录下的所有.org文件导出到~/public_html目录，同时把CSS文件从资源目录复制过去。把这段代码放进init.el后，在Emacs中执行M-x org-publish-all即可完成全部导出。
(require 'ox-publish)
(setq org-publish-project-alist
'(
("my-docs"
:base-directory "~/org-docs"
:publishing-directory "~/public_html"
:recursive t
:publishing-function org-html-publish-to-html
:headline-levels 4
:section-numbers t
:with-toc t
:html-head-extra "<link rel=\"stylesheet\" type=\"text/css\" href=\"style.css\" />"
:html-preamble "<nav><a href=\"/index.html\">首页</a></nav>")
("my-docs-static"
:base-directory "~/org-docs/assets"
:publishing-directory "~/public_html/assets"
:base-extension "css\\|js\\|png\\|jpg"
:publishing-function org-publish-attachment)
("my-docs-all"
:components ("my-docs" "my-docs-static"))
))
经过这样的配置，每次修改源文件后只需在Emacs里按M-x org-publish-all，系统就会自动导出所有变化的内容。如果想在终端里完成自动化，也可以使用Emacs的批处理模式。下面的命令可以在不打开图形界面的情况下导出指定的Org文件：
emacs --batch --eval "(require 'org)" --visit=demo.org --funcall org-html-export-to-html
把这段命令放入shell脚本或Makefile中，配合git提交钩子或定时任务，就能实现文档保存即发布的效果。对于团队协作环境，还可以将org-publish-project-alist的配置放在版本控制中，让每个成员使用相同的导出规则，避免因为个人配置差异导致输出不一致。自动化发布是Org模式从个人工具走向团队工作流的关键一步。
常见问题与优化建议
在Ubuntu下使用Org模式导出HTML时，最常见的问题之一是代码块没有语法高亮。这通常是因为系统中缺少HTMLize工具。Org模式进行代码高亮时依赖htmlize.el这个Emacs包，它能把代码转换成带颜色样式的HTML。如果导出后的代码块只有黑白文本，可以在Emacs中通过包管理器安装htmlize，安装后重新导出即可看到彩色代码。
另一个容易被忽略的细节是图片路径。Org文件中使用[[file:images/photo.png]]语法插入图片，导出时Org模式会把图片复制到HTML输出目录下的images文件夹里，并自动调整<img>标签的src属性。但如果图片文件不在源文件所在目录下，或者使用了绝对路径，导出后的网页可能会出现图片无法显示的情况。建议把所有图片统一放在与Org源文件同级的images目录中，并使用相对路径引用。对于需要缩放或居中的图片，可以在Org文件头部设置#+ATTR_HTML: :width 600px :align center。
响应式布局方面，默认的Org HTML导出结果在移动设备上并不友好，表格和代码块容易溢出屏幕。解决思路主要是在CSS中加入max-width、overflow-x: auto和媒体查询，这些技巧在前面的CSS示例中已经体现。如果希望在手机上也能舒适阅读，建议把正文字号设置为16px以上，并给代码块设置white-space: pre-wrap或配合横向滚动条。对于表格，可以考虑使用display: block配合overflow-x: auto，避免表格撑破页面宽度。
最后，Org模式还支持导出时生成目录、设置标题编号、指定语言环境等选项。这些选项既可以在Org文件头部通过#+OPTIONS设置，也可以在发布项目配置中统一指定。例如#+OPTIONS: toc:2 num:t表示目录显示到二级标题，并且所有标题都自动编号。熟悉这些细粒度控制后，你可以让Org模式的HTML导出完全符合自己的文档规范，同时保持源文件的纯粹和可读性。
Emacs Org模式HTML导出CSS样式修改时间：2026-10-02 15:17:51