What gets cut

$ ./build/bin/pulpmesh build ~/Sites/notes --out=/tmp/site
wrote 12 pages

What actually happened was a typo, a missing directory, a rebuild, and then
that. Nobody wants the first three, so out they go. Fine. But two habits keep
the edit honest.

Habit one: paste real output

$ ./build/bin/pulpmesh build ~/Sites/notes --out=/tmp/site
pulpmesh: no base_url in _readme.md; skipping rss.xml
wrote 12 pages

The warning is real, it is what a reader will see, and cutting it means the
first thing they experience is a surprise.

Habit two: show the failure too

$ ./build/bin/pulpmesh build ~/Sites/notes
pulpmesh: two files publish to frontier-model.html
  0010-frontier-model.md
  2026-06-20-frontier-model.md
$ echo $?
1

An error message with an exit code is more useful than three paragraphs about
what could go wrong.

Habit three: mark the elisions

$ ls _site | head -4
404.html
index.html
frontier-model.html
rss.xml
...

head and a trailing ... are honest. Silently deleting the middle of a
listing is not.

The one I break

I still align output columns by hand when the paste comes out ragged. I have
made my peace with it.

The rule

A run of n backticks opens a code span, and it closes on the next run of
exactly n. So a single backtick inside a span needs a double-backtick fence:
` . Two backticks inside need three: `` .

Nothing is markup inside a span

Inside a span, *this* is asterisks, _that_ is underscores, [a](b) is a
link that never happens, and <b> is an angle bracket, a letter and another
angle bracket. That is the whole point of a span.

Padding

A span whose content begins or ends with a backtick needs a space of padding
so the fences do not run together. The space is part of the syntax, not the
content: `code` renders without the outer spaces.

Where it goes wrong

The failure mode is an unclosed run. `three ``` opens a run of one and
finds a run of three, which does not match, so the backtick stays literal text
and the rest of the paragraph reads normally. That is the behaviour you want:
a typo degrades to text, never to a swallowed paragraph.

In fences

Inside a fenced block none of this applies. A fence ends on a line whose first
non-space characters are the closing run, so a lone backtick in the middle of
a line is just a character:

$ echo "a ` b"
a ` b

TOML

[package]
name = "pulpmesh"
version = "0.4.0"

[build]
target = "wasm32-wasi"
flags = ["-Os", "--strip"]

An .ini file

[core]
	editor = vim
	pager = less -FRX

[alias]
	lg = log --graph --oneline

Something invented on the spot

site  slab-and-serif
posts 12
draft 3
feed  rss.xml

Plain, with no tag at all

Every character in here is literal.
Even *this*, and `this`, and <this>.

Why this matters

An unknown language must not become a parse error, a swallowed block, or a
paragraph. It becomes a <pre> with a class naming the language, so a
stylesheet or a future highlighter can pick it up later without the content
having to change.

Yield

def each_pair
  yield :name, "pulpmesh"
  yield :kind, "generator"
end

each_pair { |key, value| puts "#{key}=#{value}" }

No parameter in the signature, no allocation, and block_given? tells you
whether anyone passed one.

The captured block

def with_retries(attempts, &block)
  tries = 0
  begin
    tries += 1
    block.call(tries)
  rescue StandardError
    retry if tries < attempts
    raise
  end
end

The ampersand converts the block into a Proc so it can be stored, passed on,
or called later. That conversion is the cost.

Passing it through

def each_post(&block)
  posts.each(&block)
end

Capturing only to hand it straight on is the one case where a plain yield
inside posts.each { |post| yield post } is both faster and clearer.

Return, break, next

[1, 2, 3].each do |number|
  next if number.even?
  break number if number > 2
end

• next ends this iteration
• break ends the method that yielded
• return inside a block returns from the enclosing method, which is why a
  return inside a Proc created at the top level raises

Arity is looser than you think

pair = [1, 2]
[pair].each { |a, b| puts "#{a} #{b}" }   # 1 2
[pair].each { |a| puts a.inspect }        # [1, 2]

Blocks destructure. Lambdas do not. If an arity mismatch should be an error,
you wanted a lambda.

Files by name, under one directory

$ find lib -name '*.rb'
lib/pulpmesh.rb
lib/pulpmesh/post.rb
lib/pulpmesh/site.rb

Quote the pattern. Unquoted, the shell expands *.rb against the current
directory first and find receives whatever that happened to match.

Files newer than a reference

$ touch -d '2026-01-01' /tmp/cutoff
$ find src -type f -newer /tmp/cutoff
src/parser.c
src/parser.h

There is no -newerthan '2026-01-01'. A reference file is the interface.

Prune a subtree

$ find . -name node_modules -prune -o -name '*.json' -print
./package.json
./config/tsconfig.json

The -o is doing real work. Without -print on the right side, the default
print applies to both branches and the prune is decorative.

Hand the results to something else

$ find . -name '*.log' -print0 | xargs -0 wc -l
   1204 ./build.log
    318 ./serve.log
   1522 total

-print0 and -xargs -0 travel together. Any pipeline that omits them is one
filename with a space away from doing something surprising.

What I still look up

Every single time: -mindepth, -maxdepth, and which order they have to
appear in relative to the tests. The answer is that they are options, not
tests, so put them first.