krz/orgo
Lightning fast org-mode static site generator.
clone: git clone https://gitbay.org/krz/orgo.git
1//! User-facing build configuration (`orgo.toml`).
2//!
3//! Everything here was once a constant in the source: the page layout, the nav rule, the
4//! highlighting theme. That made the generator produce exactly one kind of site — a
5//! reasonable place to start from, and a dead end for anyone whose site is not that one.
6//!
7//! Two properties matter beyond the settings themselves:
8//!
9//! 1. **Absent config is a valid config.** Every field has a default, so a directory of
10//! `.org` files with no `orgo.toml` still builds. Configuration is how you change
11//! the output, never how you make it work at all.
12//! 2. **Config is a hash input** (spec §4.1). [`Config`] serializes deterministically and
13//! its hash is folded into every page's render key, so editing `orgo.toml` re-renders
14//! exactly the pages it affects — which for most settings is all of them.
15
16use anyhow::{Context, Result};
17use camino::{Utf8Path, Utf8PathBuf};
18use serde::{Deserialize, Serialize};
19
20/// The config file's name, looked for in the source directory.
21pub const CONFIG_FILE: &str = "orgo.toml";
22
23/// Resolved build configuration. Serialized into the config hash, so field order and
24/// defaults are part of the cache contract.
25#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
26#[serde(default, deny_unknown_fields)]
27pub struct Config {
28 pub site: Site,
29 pub nav: Nav,
30 pub templates: Templates,
31 pub highlight: Highlight,
32 pub html: HtmlOutput,
33 pub build: Build,
34 /// Generated listing pages. Each produces one output file that has no source `.org`
35 /// file behind it — a blog index, an archive, a feed.
36 pub collections: Vec<Collection>,
37 /// Which layout authored pages render through, by source path. Pages matching no
38 /// rule use `base.html`.
39 pub pages: Vec<PageRule>,
40}
41
42/// One layout rule: the pages under `match` render through `template`.
43///
44/// Sections usually want one layout — every blog post carries the same byline and reply
45/// footer — and asking an author to repeat `#+TEMPLATE:` in each of 200 files is asking
46/// them to maintain the same fact 200 times. A rule states it once for the directory; a
47/// page that differs still says so itself with `#+TEMPLATE:`, which wins.
48#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
49#[serde(default, deny_unknown_fields)]
50pub struct PageRule {
51 /// A source path: a directory, matching every page beneath it, or one `.org` file.
52 /// Relative to the source root, like `nav.pages`.
53 #[serde(rename = "match")]
54 pub pattern: Utf8PathBuf,
55 /// Template file name, as it appears in the templates directory.
56 pub template: String,
57}
58
59impl PageRule {
60 /// Does this rule cover `source`? Matching is by path component, so a directory rule
61 /// covers everything beneath it however deep — `blog` matches `blog/2026/post.org`,
62 /// because a section's layout is a property of the section and not of how its files
63 /// happen to be filed — while `blo` matches nothing. An empty `match` covers the
64 /// whole site, which is how you change the default layout's name.
65 pub fn covers(&self, source: &Utf8Path) -> bool {
66 source.starts_with(&self.pattern)
67 }
68
69 /// How specific this rule is, for picking between two that both match. Longer paths
70 /// are more specific, so `blog/notes` beats `blog`.
71 fn specificity(&self) -> usize {
72 self.pattern.components().count()
73 }
74}
75
76/// Which template an authored page renders through: its own `#+TEMPLATE:` if it names
77/// one, else the most specific `[[pages]]` rule covering it, else `base.html`.
78///
79/// A page's own declaration wins because it is the more local statement — the one written
80/// with that page in view.
81pub fn page_template(config: &Config, source: &Utf8Path, keywords: &crate::model::Keywords) -> String {
82 let declared = keywords
83 .entries
84 .iter()
85 .find(|(k, _)| k.eq_ignore_ascii_case("TEMPLATE"))
86 .map(|(_, v)| v.trim())
87 .filter(|v| !v.is_empty());
88 if let Some(name) = declared {
89 return name.to_string();
90 }
91 config
92 .pages
93 .iter()
94 .filter(|rule| rule.covers(source))
95 .max_by_key(|rule| rule.specificity())
96 .map(|rule| rule.template.clone())
97 .unwrap_or_else(|| crate::template::BASE_TEMPLATE_NAME.to_string())
98}
99
100/// A generated page that lists other pages.
101///
102/// This is the one output that is not a translation of some input: a blog index exists
103/// because a set of posts exists, not because someone wrote `index.org`. Keeping it
104/// declarative — a directory in, a file out, through a template — means a feed is the
105/// same mechanism with an XML template rather than a second feature.
106#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
107#[serde(default, deny_unknown_fields)]
108pub struct Collection {
109 /// Directory of source pages to list, relative to the source root. Empty means every
110 /// page in the site.
111 pub source: Utf8PathBuf,
112 /// Where to write the generated page, relative to the output root.
113 pub output: Utf8PathBuf,
114 /// Template file name, as it appears in the templates directory.
115 pub template: String,
116 /// Title for the generated page, available to the template as `page.title`.
117 pub title: String,
118 /// Split the collection into groups and emit one page per group.
119 ///
120 /// `"tags"` groups by `#+FILETAGS:`, where a page belongs to every tag it carries.
121 /// Any other value names a `#+KEYWORD:` and groups by its value, so `"category"`
122 /// buckets pages by `#+CATEGORY:`. Empty means one page for the whole collection.
123 ///
124 /// When set, `output` and `title` may contain `{tag}`, replaced by the group — and
125 /// `output` must, or every group would write to the same file.
126 pub group_by: String,
127 /// Where to write a page listing the groups themselves — a tag index. Empty means
128 /// no such page. Only meaningful with `group_by`.
129 pub index_output: Utf8PathBuf,
130 /// Template for the group-index page. It receives `groups` rather than `pages`.
131 pub index_template: String,
132 pub index_title: String,
133 pub sort: SortKey,
134 pub order: SortOrder,
135 /// Entries per page. `0` means no pagination — the whole collection on one page.
136 ///
137 /// Page 1 stays at `output`, so the canonical URL of a section never moves when the
138 /// number of pages changes. Pages 2 and up go to `paginate_output`.
139 pub paginate: usize,
140 /// Where pages 2..N are written. Must contain `{n}`, the 1-based page number, and
141 /// `{tag}` as well when the collection is grouped — otherwise page 2 of one group
142 /// would overwrite page 2 of another.
143 pub paginate_output: Utf8PathBuf,
144 /// Give the template each entry's rendered HTML as `entry.content`.
145 ///
146 /// Off by default, and only worth turning on for a feed: it renders every listed
147 /// page's body whenever the listing is rebuilt. A reader subscribed to a
148 /// full-content feed and then handed excerpts has lost something, which is the one
149 /// case where that cost is the right trade.
150 pub include_content: bool,
151 /// Add this listing page to the site navigation. This is how a section landing page
152 /// — `/blog/`, `/notes/` — gets into a nav built from top-level pages.
153 pub nav: bool,
154}
155
156impl Default for Collection {
157 fn default() -> Self {
158 Collection {
159 source: Utf8PathBuf::new(),
160 output: Utf8PathBuf::from("index.html"),
161 template: "list.html".to_string(),
162 title: "Index".to_string(),
163 group_by: String::new(),
164 index_output: Utf8PathBuf::new(),
165 index_template: "tags.html".to_string(),
166 index_title: "Tags".to_string(),
167 sort: SortKey::default(),
168 order: SortOrder::default(),
169 paginate: 0,
170 paginate_output: Utf8PathBuf::new(),
171 include_content: false,
172 nav: false,
173 }
174 }
175}
176
177/// The `{tag}` placeholder in a grouped collection's `output` and `title`.
178pub const GROUP_PLACEHOLDER: &str = "{tag}";
179/// The page-number placeholder in `paginate_output`.
180pub const PAGE_PLACEHOLDER: &str = "{n}";
181
182#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
183#[serde(rename_all = "kebab-case")]
184pub enum SortKey {
185 /// By `#+DATE:`, newest first by default. Pages with no parseable date sort last,
186 /// keeping undated drafts out of the way of a dated archive.
187 #[default]
188 Date,
189 Title,
190 /// Output path — stable and predictable when dates are absent or unreliable.
191 Path,
192}
193
194#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
195#[serde(rename_all = "kebab-case")]
196pub enum SortOrder {
197 /// Newest or last first — the useful default for a blog.
198 #[default]
199 Desc,
200 Asc,
201}
202
203#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
204#[serde(default, deny_unknown_fields)]
205pub struct Build {
206 /// Include pages marked `#+DRAFT:` in the build.
207 ///
208 /// Off by default, because the point of marking something a draft is that it is not
209 /// ready to be read. `--drafts` turns it on for a session, which is what you want
210 /// under `watch` while writing one.
211 pub drafts: bool,
212 /// Extra directories whose contents are copied to the *site root*, on top of the
213 /// non-`.org` files found in the source directory. Relative to the source root, and
214 /// allowed to point outside it.
215 ///
216 /// This exists because a site's static files do not always live where its writing
217 /// does: weblorg publishes `theme/static/` to `/`, and a repository migrating from it
218 /// should not have to move `robots.txt` next to its blog posts to keep the URL.
219 pub assets: Vec<Utf8PathBuf>,
220}
221
222#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
223#[serde(default, deny_unknown_fields)]
224pub struct HtmlOutput {
225 /// How far to push heading levels down: a level-1 org heading becomes
226 /// `<h{1 + heading_offset}>`.
227 ///
228 /// Defaults to 1, matching Emacs' own `org-html-toplevel-hlevel`, because the page
229 /// layout supplies the `<h1>` — the document's title — and section headings sit
230 /// beneath it. Set to 0 if your template renders no title of its own, so the
231 /// document does not start at `<h2>` with nothing above it.
232 pub heading_offset: u8,
233 /// Make each page's table of contents available to templates as `page.toc`.
234 ///
235 /// On by default: it is *data*, and whether it appears is the template's business.
236 /// A document turns it off for itself with org's own `#+OPTIONS: toc:nil`, which is
237 /// how ~2% of the reference corpus does it.
238 pub toc: bool,
239 /// Number headings, `1.`, `1.1.`, and so on.
240 ///
241 /// Off by default, which differs from Emacs — `org-export-with-section-numbers` is
242 /// on there, and the reference site inherits numbered headings from it. Most sites
243 /// do not want them, so the default is the taste rather than the inheritance;
244 /// `#+OPTIONS: num:t` or `section_numbers = true` gets Emacs' behaviour back.
245 pub section_numbers: bool,
246 /// Convert org's special strings in prose: `--` to an en dash, `---` to an em dash,
247 /// `...` to an ellipsis.
248 ///
249 /// On, as in Emacs. A document turns it off for itself with `#+OPTIONS: -:nil`.
250 /// Never applied inside verbatim, code, or a source block.
251 pub special_strings: bool,
252 /// Whether `x^2` and `H_{2}O` become `<sup>`/`<sub>`.
253 ///
254 /// `"yes"` (the default, and Emacs') also treats the braceless `a_b` as a subscript,
255 /// which is what makes `snake_case` in prose render as `snake<sub>case</sub>` —
256 /// surprising, but what Emacs does with the same file. `"braces"` limits it to the
257 /// explicit `a_{b}` form, and `"no"` leaves both alone. A document chooses for itself
258 /// with `#+OPTIONS: ^:nil` or `^:{}`.
259 pub sub_superscript: SubSuperscript,
260 /// Whether `\alpha` and the rest of org's entity table become their characters.
261 ///
262 /// On, as in Emacs. A name org does not know is left as the literal text that was
263 /// typed. A document turns the whole thing off with `#+OPTIONS: e:nil`.
264 pub entities: bool,
265}
266
267/// How `_` and `^` are treated in prose. Mirrors org's `^:` export option.
268#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
269#[serde(rename_all = "kebab-case")]
270pub enum SubSuperscript {
271 /// `a_b` and `a_{b}` both convert.
272 #[default]
273 Yes,
274 /// Only the braced `a_{b}` converts.
275 Braces,
276 /// Neither converts.
277 No,
278}
279
280impl SubSuperscript {
281 /// Read org's `^:` option value: `nil` is off, `{}` is braces-only, anything else on.
282 pub fn from_option(value: &str) -> SubSuperscript {
283 match value.trim() {
284 "nil" | "false" | "no" | "off" => SubSuperscript::No,
285 "{}" => SubSuperscript::Braces,
286 _ => SubSuperscript::Yes,
287 }
288 }
289}
290
291impl Default for HtmlOutput {
292 fn default() -> Self {
293 HtmlOutput {
294 heading_offset: 1,
295 toc: true,
296 section_numbers: false,
297 special_strings: true,
298 sub_superscript: SubSuperscript::Yes,
299 entities: true,
300 }
301 }
302}
303
304/// Site-wide metadata, exposed to templates as `site`.
305#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
306#[serde(default, deny_unknown_fields)]
307pub struct Site {
308 /// Shown in the default layout's header and available as `site.title`.
309 pub title: String,
310 /// Absolute base URL (no trailing slash), for feeds and canonical links. Empty means
311 /// the site is built with relative URLs only, which is the portable default.
312 pub base_url: String,
313 /// Free-form description, available as `site.description`.
314 pub description: String,
315 /// `<html lang="…">` in the default layout.
316 pub language: String,
317}
318
319impl Default for Site {
320 fn default() -> Self {
321 Site {
322 title: "orgo site".to_string(),
323 base_url: String::new(),
324 description: String::new(),
325 language: "en".to_string(),
326 }
327 }
328}
329
330/// Which pages appear in the shared navigation.
331#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
332#[serde(rename_all = "kebab-case")]
333pub enum NavMode {
334 /// Pages at the site root. A nav is a map of the top level, not an index of the
335 /// whole site, and this keeps nav size independent of how many pages exist.
336 #[default]
337 TopLevel,
338 /// Every page. Fine for a small site; note that it makes total output quadratic in
339 /// page count, since each of `n` pages then carries `n` nav links.
340 All,
341 /// Only the pages listed in `nav.pages`, in that order.
342 Explicit,
343 /// No navigation at all.
344 None,
345}
346
347#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
348#[serde(default, deny_unknown_fields)]
349pub struct Nav {
350 pub mode: NavMode,
351 /// Source paths (relative to the source root, e.g. `about.org`) used when
352 /// `mode = "explicit"`. Order is preserved, so this doubles as nav ordering.
353 pub pages: Vec<Utf8PathBuf>,
354}
355
356#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
357#[serde(default, deny_unknown_fields)]
358pub struct Templates {
359 /// Directory of `.html` templates, relative to the source root. Each file is
360 /// registered under its stem, so `base.html` overrides the built-in layout and
361 /// anything else is available to `{% include %}`/`{% extends %}`.
362 pub dir: Utf8PathBuf,
363 /// Give templates a `pages` list of every page's metadata, so a template can build
364 /// an index or archive.
365 ///
366 /// Off by default because it is not free: if any page can read every page's
367 /// metadata, then adding one page can change any page's output, so the whole site
368 /// must re-render on every add, rename or retitle. Turning this on trades that
369 /// incremental precision for the ability to write listing pages.
370 pub expose_page_list: bool,
371}
372
373impl Default for Templates {
374 fn default() -> Self {
375 Templates {
376 dir: Utf8PathBuf::from("templates"),
377 expose_page_list: false,
378 }
379 }
380}
381
382#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
383#[serde(default, deny_unknown_fields)]
384pub struct Highlight {
385 /// Directory of extra `.sublime-syntax` files, relative to the source root.
386 ///
387 /// syntect bundles a long list of languages and this crate adds TOML and Org, but a
388 /// missing language should not need a new release — drop a definition here and it is
389 /// picked up. A file that fails to parse is reported and skipped.
390 pub syntaxes_dir: Utf8PathBuf,
391 /// A syntect built-in theme name — `InspiredGitHub`, `Solarized (dark)`,
392 /// `base16-ocean.dark`, `base16-eighties.dark`, `base16-mocha.dark`,
393 /// `base16-ocean.light`. Highlighting emits CSS classes, and this theme is what the
394 /// generated `syntax.css` colours them with.
395 pub theme: String,
396}
397
398impl Default for Highlight {
399 fn default() -> Self {
400 Highlight {
401 syntaxes_dir: Utf8PathBuf::from("syntaxes"),
402 theme: "InspiredGitHub".to_string(),
403 }
404 }
405}
406
407impl Config {
408 /// Load `orgo.toml` from `dir`, or return defaults if there is none.
409 ///
410 /// A *missing* config is normal and silent. A *malformed* one is an error: someone
411 /// who wrote a config meant it, and silently building the default site would hide
412 /// their typo behind plausible-looking output.
413 pub fn load(dir: &Utf8Path) -> Result<Config> {
414 Self::load_file(&dir.join(CONFIG_FILE))
415 }
416
417 /// Load a config from an explicit path. Missing is still fine; malformed is not.
418 pub fn load_file(path: &Utf8Path) -> Result<Config> {
419 let text = match std::fs::read_to_string(path) {
420 Ok(text) => text,
421 Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Config::default()),
422 Err(e) => return Err(e).with_context(|| format!("reading {path}")),
423 };
424 toml::from_str(&text).with_context(|| format!("parsing {path}"))
425 }
426
427 /// Validate settings that only make sense in combination. Catching these up front
428 /// beats emitting a site with a silently empty nav.
429 pub fn validate(&self) -> Result<()> {
430 if self.nav.mode == NavMode::Explicit && self.nav.pages.is_empty() {
431 anyhow::bail!(
432 "nav.mode is \"explicit\" but nav.pages is empty: list the pages to \
433 include, or use mode = \"top-level\"/\"all\"/\"none\""
434 );
435 }
436 if self.nav.mode != NavMode::Explicit && !self.nav.pages.is_empty() {
437 anyhow::bail!(
438 "nav.pages is set but nav.mode is \"{}\", so it would be ignored; set \
439 mode = \"explicit\" to use it",
440 toml::to_string(&self.nav.mode)
441 .unwrap_or_default()
442 .trim()
443 .trim_matches('"')
444 );
445 }
446 let mut seen: Vec<&Utf8PathBuf> = Vec::new();
447 for collection in &self.collections {
448 let grouped = !collection.group_by.is_empty();
449 if collection.output.as_str().is_empty() && collection.index_output.as_str().is_empty()
450 {
451 anyhow::bail!("a collection has no `output`; it needs a file to write");
452 }
453 if grouped
454 && !collection.output.as_str().is_empty()
455 && !collection.output.as_str().contains(GROUP_PLACEHOLDER)
456 {
457 anyhow::bail!(
458 "collection output {} groups by \"{}\" but has no {GROUP_PLACEHOLDER} in \
459 its path, so every group would overwrite the same file",
460 collection.output,
461 collection.group_by
462 );
463 }
464 if !grouped && collection.output.as_str().contains(GROUP_PLACEHOLDER) {
465 anyhow::bail!(
466 "collection output {} uses {GROUP_PLACEHOLDER} but sets no `group_by`",
467 collection.output
468 );
469 }
470 if !grouped && !collection.index_output.as_str().is_empty() {
471 anyhow::bail!(
472 "collection writes an `index_output` of {} but sets no `group_by`; \
473 there are no groups to index",
474 collection.index_output
475 );
476 }
477 if collection.paginate > 0 {
478 let pattern = collection.paginate_output.as_str();
479 if pattern.is_empty() {
480 anyhow::bail!(
481 "collection output {} sets `paginate` but no `paginate_output`; pages 2 and up need somewhere to go, e.g. \"blog/page/{PAGE_PLACEHOLDER}.html\"",
482 collection.output
483 );
484 }
485 if !pattern.contains(PAGE_PLACEHOLDER) {
486 anyhow::bail!(
487 "collection `paginate_output` {pattern} has no {PAGE_PLACEHOLDER}, so every page after the first would overwrite the same file"
488 );
489 }
490 if grouped && !pattern.contains(GROUP_PLACEHOLDER) {
491 anyhow::bail!(
492 "collection `paginate_output` {pattern} groups by \"{}\" but has no {GROUP_PLACEHOLDER}, so page 2 of one group would overwrite page 2 of another",
493 collection.group_by
494 );
495 }
496 }
497 if collection.paginate == 0 && !collection.paginate_output.as_str().is_empty() {
498 anyhow::bail!(
499 "collection sets `paginate_output` {} but `paginate` is 0, so it would never be used; set `paginate` to a page size",
500 collection.paginate_output
501 );
502 }
503 for path in [&collection.output, &collection.index_output] {
504 if path.as_str().is_empty() || path.as_str().contains(GROUP_PLACEHOLDER) {
505 continue;
506 }
507 if seen.contains(&path) {
508 anyhow::bail!(
509 "two collections both write to {path}; give them different \
510 `output` paths"
511 );
512 }
513 seen.push(path);
514 }
515 }
516 for rule in &self.pages {
517 if rule.template.trim().is_empty() {
518 anyhow::bail!(
519 "the [[pages]] rule matching {:?} names no `template`; it has nothing \
520 to select",
521 rule.pattern.as_str()
522 );
523 }
524 }
525 if !self.site.base_url.is_empty() && self.site.base_url.ends_with('/') {
526 anyhow::bail!(
527 "site.base_url must not end with a slash (got {:?}) — URLs are joined \
528 with an explicit separator",
529 self.site.base_url
530 );
531 }
532 Ok(())
533 }
534}
535
536/// The starter config written by `orgo init`, and the documentation of record for
537/// what is configurable. Every value shown is the default, so deleting any line is safe.
538pub const STARTER_CONFIG: &str = r#"# orgo configuration. Every setting here is optional and shown at its default,
539# so you can delete any line you do not need — or the whole file.
540
541[site]
542title = "orgo site"
543# Absolute base URL, no trailing slash. Needed for feeds and canonical links, which
544# cannot be relative — set it and uncomment the [[collections]] feed block below.
545base_url = ""
546description = ""
547language = "en"
548
549[nav]
550# Which pages appear in the shared navigation:
551# "top-level" — pages at the site root (default; keeps nav size independent of site size)
552# "all" — every page (fine when small; output grows quadratically with page count)
553# "explicit" — only nav.pages, in the order listed
554# "none" — no navigation
555mode = "top-level"
556# pages = ["index.org", "about.org"]
557
558[templates]
559# Directory of .html templates, relative to this file. `base.html` replaces the built-in
560# layout; any other file can be pulled in with {% include %} or {% extends %}.
561dir = "templates"
562# Give templates a `pages` list of every page's metadata, so you can build an index or
563# archive. Costs incremental precision: with this on, adding a page re-renders the site.
564expose_page_list = false
565
566# Which layout a page renders through. Without a rule, every page uses base.html.
567# `match` is a source path — a directory (covering everything beneath it) or one .org
568# file — and the most specific rule wins. A page overrides any rule with `#+TEMPLATE:`.
569# [[pages]]
570# match = "blog"
571# template = "post.html"
572
573[highlight]
574# A syntect theme name: InspiredGitHub, Solarized (dark), base16-ocean.dark,
575# base16-eighties.dark, base16-mocha.dark, base16-ocean.light.
576theme = "InspiredGitHub"
577# Extra .sublime-syntax files for languages neither syntect nor orgo bundles.
578syntaxes_dir = "syntaxes"
579
580[build]
581# Include pages marked `#+DRAFT:`. Off by default — the point of marking a draft is that
582# it is not ready to be read. `--drafts` turns it on for one run, handy under `watch`.
583drafts = false
584# Extra directories copied to the site root, for static files that live outside the
585# source directory. `assets = ["../theme/static"]` publishes that directory's contents at
586# `/`, not at `/static/`.
587assets = []
588
589[html]
590# How far to push heading levels down: a level-1 org heading becomes <h(1 + offset)>.
591# The default of 1 matches Emacs, and assumes your layout renders the page title as the
592# <h1>. Set to 0 if your template renders no title of its own.
593heading_offset = 1
594# Make page.toc available to templates. A document opts out with `#+OPTIONS: toc:nil`.
595toc = true
596# Number headings (1., 1.1., …). Emacs defaults this on; most sites do not.
597# A document overrides with `#+OPTIONS: num:t`.
598section_numbers = false
599# Convert `--` to an en dash, `---` to an em dash and `...` to an ellipsis in prose, as
600# Emacs does. Never inside code. A document overrides with `#+OPTIONS: -:nil`.
601special_strings = true
602# Whether `x^2` and `H_{2}O` become <sup>/<sub>: "yes" (as Emacs, and so `snake_case`
603# becomes snake<sub>case</sub>), "braces" for the `a_{b}` form only, or "no".
604# A document overrides with `#+OPTIONS: ^:nil` or `^:{}`.
605sub_superscript = "yes"
606# Convert `\alpha` and the rest of org's entity table. An unknown name stays literal.
607# A document overrides with `#+OPTIONS: e:nil`.
608entities = true
609
610# Generated listing pages: output files with no source .org behind them. Repeat the
611# [[collections]] block for each one. A feed is the same thing with an XML template.
612[[collections]]
613source = "blog" # directory to list; empty means every page
614output = "blog/index.html" # where to write it
615template = "list.html" # template file name
616title = "Blog"
617sort = "date" # date | title | path
618order = "desc" # desc | asc
619nav = true # put this listing page in the site nav
620# paginate = 10 # entries per page; page 1 stays at `output`
621# paginate_output = "blog/page/{n}.html" # where pages 2..N go; needs {n}
622
623# An RSS feed is a listing page with an XML template. It needs site.base_url above,
624# because a feed is read away from the site that served it and relative links break.
625# [[collections]]
626# source = "blog"
627# output = "feed.xml"
628# template = "feed.xml"
629# title = "Feed"
630
631# One page per tag, plus an index of all tags. `{tag}` in `output`/`title` is replaced
632# by each tag; the index gets `groups` instead of `pages`.
633[[collections]]
634source = "blog"
635group_by = "tags" # "tags", or any #+KEYWORD: name to group by its value
636output = "tags/{tag}.html"
637template = "list.html"
638title = "Tagged: {tag}"
639index_output = "tags/index.html"
640index_template = "tags.html"
641index_title = "Tags"
642nav = true # adds the tag *index*, not every tag
643"#;