Dynamic blocks

:scope file reads the whole file, :maxlevel 3 shows headings down to level 3 (deeper levels are added to their parent).

Try: change :maxlevel 3 to :maxlevel 2 and press <C-c><C-c> on the #+BEGIN: line.

Expect: the level-3 rows (Design mockups, Build the pages, Launch checklist, Weekly review, Email) disappear; Website relaunch still shows 7:40 and Admin 1:45: the time of the hidden children is still counted in their parents.

:block keeps only clocked time inside a period: today, yesterday, thisweek, lastweek, thismonth, lastmonth, thisyear, a fixed day 2026-09-23, a week 2026-W39, a month 2026-09, a quarter 2026-Q3 or a year 2026. The this... forms and today take an offset: thisweek-1 is last week.

:tstart and :tend give any range (:tend is exclusive). They also accept <today>, <now>, <-2d> (two days ago), <+1w>, <-3h>.

Try: put the cursor on the #+BEGIN: line of the 2026-09-23 table and press <S-Right>.

Expect: the line now reads :block 2026-09-24 and the table is updated: *Total time* *0:40*, all in Build the pages (the 0:40 of "Contact form", a level-4 entry). <S-Left> twice goes back to 2026-09-22 (Design mockups 1:15). On :block thisweek the keys give thisweek+1 / thisweek-1.

:step day (or week, semimonth, month, quarter, year) splits the :block or :tstart / :tend range into periods and writes one table per period. :stepskip0 t leaves out the periods without time.

Daily report: [2026-09-21 Mon]

Daily report: [2026-09-22 Tue]

Daily report: [2026-09-23 Wed]

Daily report: [2026-09-24 Thu]

Daily report: [2026-09-25 Fri]

Try: remove :stepskip0 t and update the block.

Expect: seven daily tables, Monday to Sunday; the tables of Saturday 2026-09-26 and Sunday 2026-09-27 only have the row | *Total time* | *0:00* |.

:match takes a tags/property match (the same syntax as the agenda's match views, :h org-match-syntax).

:scope says which entries are read:

Try: on the #+BEGIN: line of "The basic table" change :scope file to :scope agenda and update it.

Expect: with examples/minimal_init.lua the table covers every examples/*.org file. A File column comes first; the total row reads ALL *Total time*, and every file gets a *File time* row (*0:00* for files without clocks) followed by its headings. The 18-dynamic-blocks.org part shows the same 9:25 as before. Change it back to :scope file.

Try: add :link t to the block above and update it.

Expect: every heading in the table becomes a link to the entry: a file: link with the full path of this file and ::*Design mockups (like Emacs, which also writes the absolute file name). The link shows as its description, Design mockups; <C-c><C-c> on it jumps to the entry.

:formula "..." adds a #+TBLFM: line to the table. A #+TBLFM: line you write yourself right under the table is kept on every update and re-applied. Here :tcolumns 1 puts all times in one column and a formula converts them into hours as a decimal number (;t reads H:MM as hours):

Try: update the block above twice.

Expect: the #+TBLFM: $3=$2;t line is still there after each update, and the third column shows the hours as decimals: 9.42 for 9:25, 7.67 for 7:40, 1.75 for 1:45.

Try: change the Effort of "Blog" (in "The sample data") from 4:00 to 2:00 with <prefix>xe or by editing the drawer, then update the block above.

Expect: the Blog row shows 2:00, Build the pages goes from 9:00 to 7:00 and Website relaunch from 14:00 to 12:00.

With :id local (or no :id at all) the block captures the subtree it is written in: this heading and its children. The format comes from this heading's own COLUMNS property. %Pages{+} sums the pages, %Rating{mean} averages the ratings.

:maxlevel N stops at level N. :hlines t puts a separator before every entry; :hlines N only before entries of level N or less.

• :skip-empty-rows t drops rows where every column but ITEM is empty.
• :match "..." keeps the entries that match a tags/property match.
• :exclude-tags (tag ...) drops entries with one of these tags (inherited tags count).

:indent t indents the ITEM column by level (\_ like the clock table). :link t turns each item into a link to its heading.

Try: add :link t to the block above and update it. Then press <C-c><C-c> on the Contact form link.

Expect: the items become file: links (the full path of this file, then ::*Contact form), shown as their titles; following one jumps to that heading.

:format overrides the COLUMNS format. Keywords above the table (like #+NAME:) and a #+TBLFM: line under it are kept when the block is updated, and the formula is applied again, so a column view can feed a computed column. Here the format has a fourth column, Left, for a property no entry has (so it starts empty), and the formula fills it with the effort minus the clocked time (;U writes the result as HH:MM):

Try: change the Effort of "Contact form" (in "The sample data") from 2:00 to 3:00 and update the block above.

Expect: the #+NAME: and #+TBLFM: lines are still there, and the Contact form row shows 3:00, 0:40 and 02:20 left; Build the pages goes to 10:00 and 06:35, Website relaunch to 15:00 and 07:20.

require("org.dblock").register("greeting", function(params)
  local who = params.name or "world"
  local times = params.times or 1
  local lines = {}
  for i = 1, times do
    lines[#lines + 1] = string.format("%d. Hello, %s!", i, who)
  end
  return lines
end)

Try: first update the greeting block: <C-c><C-c> on its #+BEGIN: line.

Expect: a warning "No writer for dynamic block: greeting": nothing is registered yet.

Try: now put the cursor in the Lua block above, press <C-c><C-c> (and answer y), then update the greeting block again.

Expect: three lines: 1. Hello, Ada!, 2. Hello, Ada! and 3. Hello, Ada!. Change :times 3 to :times 1 and :name "Ada" to :name "Linus", update again: one line, 1. Hello, Linus!.

Writers can read the buffer. This one lists the headings of the file up to :maxlevel as links, like a table of contents.

require("org.dblock").register("toc", function(params, ctx)
  local max = params.maxlevel or 1
  local out = {}
  for _, hl in ipairs(require("org.files").get_buffer(ctx.bufnr).headlines) do
    if hl.level <= max then
      local title = hl:plain_title()
      out[#out + 1] = string.rep("  ", hl.level - 1)
        .. "- [[*" .. title .. "][" .. title .. "]]"
    end
  end
  return out
end)

Try: run the Lua block above, then update the toc block. Then change :maxlevel 1 to :maxlevel 2 and update it again.

Expect: first a list with one link per top-level heading of this file (How to use this file, The sample data, …). With :maxlevel 2 the second-level headings appear as indented sub-items.

The writer can return any Org text, for example a table:

require("org.dblock").register("todo-summary", function(params, ctx)
  local counts = {}
  for _, hl in ipairs(require("org.files").get_buffer(ctx.bufnr).headlines) do
    if hl.todo then
      counts[hl.todo] = (counts[hl.todo] or 0) + 1
    end
  end
  local lines = { "| State | Count |", "|-------+-------|" }
  for _, state in ipairs({ "TODO", "NEXT", "DONE" }) do
    lines[#lines + 1] = string.format("| %s | %d |", state, counts[state] or 0)
  end
  return lines
end)

Try: run the Lua block, update the todo-summary block, then mark "Contact form" (in "The sample data") DONE: on its heading press <prefix>S then d. Come back and update the block again.

Expect: first TODO 3, NEXT 1, DONE 2 (the table is not aligned: the writer did not pad it; press <C-c><C-c> inside it to align). After the change: TODO 2, DONE 3.

A columnview block can hand its rows to your own Lua function instead of writing a table: :formatter NAME names a global Lua function NAME(rows, params) that returns the lines. rows[1] holds the column titles, rows[2] is the string "hline", and each following row is a table with the cells (row[1], row[2], …) and row.level (the heading level). The option columns_dblock_formatter sets a formatter for every columnview block.

function _G.effort_list(rows, params)
  local out = {}
  for i = 3, #rows do
    local r = rows[i]
    local line = string.rep("  ", r.level - 2) .. "- " .. r[1] .. ": "
      .. (r[2] ~= "" and r[2] or "no estimate")
    if r[3] ~= "" then
      line = line .. " (" .. r[3] .. ")"
    end
    out[#out + 1] = line
  end
  return out
end

Try: run the Lua block above, then update the columnview block below it.

Expect: a nested list instead of a table: - Website relaunch: 14:00, then indented items such as - Design mockups: 4:00 (Ana) and, one level deeper, - Home page: 3:00 (Ben). Before the Lua block has run, updating gives an error that ends in "unknown :formatter effort_list".

:Org insert_dblock (Emacs C-c C-x x) asks for a block type among the registered writers (clocktable, columnview and yours), inserts #+BEGIN: NAME / #+END: below the cursor line and fills it.

Try: on the empty line below, run :Org insert_dblock and choose greeting (after registering it above).

Expect: a #+BEGIN: greeting block with the content 1. Hello, world! (no parameters: the defaults of the writer).