Markdown Guide

This is the syntax reference for writing Berean Archive articles in Markdown. For the article rules — layout, writing style, and the Berean Modified MLA citation format — see Contributing Guidelines. This page only covers how to type things.

Every .md file is compiled to HTML on request by admin/common/tools/markdown.php (an extended Parsedown). Edits show up on the next page load; you never build anything by hand. Typora is a good free editor and previews most of this correctly.

You can read this page's own source at markdown-guide.md.

Cheat sheet

The rest of this page explains each of these, plus the gotchas.

Page skeleton

Start every article with a frontmatter block between two --- lines, then a single # title:

---
title:             Radiometric Dating
description:       A survey of isochron methods and their assumptions.
theme:             common/themes/berean2/theme.php
section:           Biology
photo:             header-wide.jpg
photoCaption:      Photo credit, shown in the strip under the photo.
socialImage:       header-square.jpg
published:         "2026-10"
---

# Radiometric Dating

## Summary
…

Frontmatter keys

All keys are optional, but real articles set at least title, description and theme.

Frontmatter is YAML

The block is parsed as real YAML, so standard YAML rules apply:

1. key: value pairs. Values may be strings, numbers, true/false, or lists — and # starts a comment.

2. Quote a value that contains a colon-followed-by-space or starts with a YAML indicator (> | @ \ % & * ! [ {`). A title with a subtitle needs quotes:

   title: "Shroud of Turin:  1988 Carbon Dating"

3. An apostrophe is fine unquoted (title: Paul's Letters). A list, if you ever need one:

   tags:
     - creation
     - genetics

Because there's no fallback parser, a YAML syntax error in your frontmatter will break the page — quote anything ambiguous.

Headings, anchors, and the table of contents

• Your first # heading is the article title; the theme lays it in white over the header photo. You may put a <br> in it to control the line break, e.g. # Shroud of Turin:<br>1988 Carbon Dating.
• ## and ### structure the body. A navigable table of contents is built automatically from your headings and shown in a column on the left (a Contents bar on narrower screens) — you do not write it. (The [toc] token from other Markdown flavors does nothing here.)
• Every heading gets an id you can link to. The id is the heading text, lowercased, with each run of non-letters/digits turned into a single -. So ### Daniel's 70 Weeks is reachable at #daniel-s-70-weeks, and you link to it with [see below](#daniel-s-70-weeks).

Text and inline formatting

Standard Markdown works: **bold**, *italic*, `code`, [link](https://example.com), lists, and > blockquotes. On top of that:

House style (from the Contributing Guidelines) is two spaces after every period. The renderer deliberately preserves those extra spaces, so don't be surprised to see them honored on the page.

Glossary terms

Wrap a term in <dfn>…</dfn> to give it a dotted underline and a pop-up definition, shown on hover, on keyboard focus, or on a tap.  The definition text is pulled from common/includes/definitions.md, so add the term there once and it works everywhere.  Matching ignores case and a plural or verb ending (codons finds codon).  A term with no entry shows as plain text, with a warning in the browser console:

The <dfn>selvage</dfn> edge frayed over the centuries.

++term++ is the short way to write <dfn>term</dfn>:  the site's Markdown settings ('insert' => 'dfn' in env.php) make it produce a <dfn>.

Footnotes and citations

Footnotes are how every claim gets its source. Put a reference in the text and its definition anywhere below (by convention, under a final ## Sources heading). They are renumbered into reading order automatically, so source order doesn't matter.

The image is not painted.[^fanti-2010]

## Sources

[^fanti-2010]: Fanti, Giulio.  "[Analysis of Shroud Fibres](https://example.com)."  2010.

The :letter convention (important)

One published source usually backs several different claims. Rather than repeat the citation, give the source a base footnote and hang lettered children off it, one per specific quote or page:

Tiberius' fifteenth year ran from fall 28 to spring 30 AD.[^hoehner-1978:a]
Nobody in the ancient world counted his reign from a coregency.[^hoehner-1978:b]

## Sources

[^hoehner-1978]: Hoehner, Harold W.  "Chronological Aspects of the Life of Christ."  1978.
[^hoehner-1978:a]: Page 24:  "…the normal Roman method of reckoning…"
[^hoehner-1978:b]: Page 85:  "There is no evidence… that Tiberius' reign was reckoned from his coregency."

The engine treats the part before the second colon (hoehner-1978) as the parent and tucks the children (:a, :b, …) underneath it as a nested list. Define the base footnote ([^hoehner-1978]:) or the children won't nest. Anything after the colon is just a label — letters :a, :b, :c are the convention.

Two more things worth knowing:

• Cite the same footnote in several places and it grows several back-arrows, one per use.
• A reference with no definition renders as its raw name and logs a warning to the browser console — handy for catching typos.

Follow the Berean Modified MLA rules for what goes inside a citation (linked titles, page numbers, archive mirrors, etc.). A typical definition with mirrors:

[^maier-1968]: Maier, Paul.  "[Sejanus, Pilate, and the Date of the Crucifixion](https://example.com)."  Church History.  1968.<small>Mirrors:  [Archive.org](https://example.com), [JSTOR](https://example.com).</small>

Blockquotes

Use > for quoted sources. Nest with > > for a quote inside a quote:

> Phlegon writes:
>
> > In the fourth year of the 202^nd^ Olympiad, an eclipse of the sun happened…

For a short italic pull-quote in the flow of your own text (not a boxed source quote), use <q>…</q>:

<q>"There have been no serious challenges to the carbon dating." — Dominic Selwood</q>

Callout boxes

Callouts use the GitHub/Obsidian standard: a blockquote whose first line is [!TYPE]. Put a blank > line after the marker, then the body:

> [!WARNING]
>
> The 1988 carbon date came from a repaired corner, not the original cloth.

The types are GitHub's five — note, tip, important, warning, caution — plus info (from Obsidian), each with its own color. Add a title after the marker to override the default one:

> [!NOTE] Estimating Minimum Functional DNA
>
> 85% transcribed × 80% localized ≈ **68%** of the genome in functional elements.

A callout is just a styled blockquote, so it can hold anything — lists, bold, links, and images. For an image beside the text, add class="left" (or right) to the <img>:

> [!NOTE] With a figure
>
> <img src="diagram.jpg?w=150" class="left">
> Text flows to the right of the floated image.

(For a note that floats out in the margin rather than a boxed callout, use <aside markdown="1">…</aside> — see Embedding HTML.)

Tables

Write ordinary Markdown pipe tables. To style one, put a {: …} line immediately after it (kramdown's "inline attribute list" — it attaches the attributes to the table above it):

| Lab     | Result          |
| ------- | --------------- |
| Oxford  | 1090 to 1220 AD |
| Zürich  | 1156 to 1278 AD |
{: .ruled cols="25%"}

Each .word is a class; the classes below control the look.  A table with no class is left unstyled, since some tables carry their own styles for diagrams.

Table classes

Column widths — cols="…"

Add a cols attribute listing each column's width, left to right, usually with .ruled:

{: .ruled cols="5% 20%"}

→ column 1 is 5% wide, column 2 is 20%, the rest share what's left.

• Any unit works (25%, 120px, 2fr); a bare number is treated as a percent (cols="25 20" = 25% 20%).
• Use auto (or just leave the list short) for a column that should size itself: cols="5% auto 25%" sets columns 1 and 3 and lets column 2 flex.
• It emits a standard HTML <colgroup> under the hood.

More than classes

The {: …} list also takes an #id and any key="value" attribute, not just classes:

{: .ruled #results style="max-width:600px"}

This is the standard kramdown block-IAL syntax. Keep it on its own line directly after the block you're styling. (It works on any block — a table, list, blockquote, or paragraph — attaching to whatever is immediately above it.)

Images

Raw <img> is the norm here because it takes classes and sizing. Images live in the same folder as the article's index.md (or use a site-absolute path like /common/img/…).

Add ?w= to the filename to auto-resize; the resizer caches the result:

<img src="header-square.jpg?w=230" class="lightbox">

Conventions in existing articles: ?w=150 for a portrait thumbnail, ?w=230 for a standard inline figure. Display width inside a sized table cell is set with style="width: 100%".

Image classes

Combine them: class="lightbox inverted", class="wide inverted".

Markdown image syntax ![alt](pic.jpg?w=230) also works and also honors ?w=, but you can't add classes to it — that's why articles prefer <img>.

Embedding HTML

Raw HTML passes straight through, so you can drop in a <table>, <iframe>, or a custom <div> when Markdown isn't enough. Two rules:

1. To use Markdown inside a block-level HTML element, add markdown="1" to it. Inline tags like <b>, <span>, <sup> don't need it. This is how <aside markdown="1">…</aside> (a right-margin note) gets formatted content.
2. Keep your HTML well-formed — the page is re-serialized through an HTML parser, which will "correct" broken tags in surprising ways.

You can even embed raw PHP and it runs when the page is served — reserve that for genuine need. (The engine swaps PHP tags in and out before it parses Markdown, which is why this guide can't print a literal PHP open-tag, even inside code.)

Interactive data tables from CSV/TSV files

Any public .tsv or .csv under the site can be shown as a sortable, filterable, pageable table with a SQL query editor — no setup beyond the two lines below.  The table name is the file's site-relative path minus its extension (the server imports the file into a throwaway SQLite cache and refreshes it whenever the file changes; visitors get it read-only).  Keep the whole element on one line inside a <div> so the Markdown parser passes it through raw:

<script type="module" crossorigin="use-credentials">import '/admin/common/js/common.bundle.js';</script>
<div><data-table endpoint="/admin/api.php?vsql" database-name="csv" schema-name="main" table-name="unpublished-ai/ark-logistics/research/species_masses" display="search download paging count aggregateFooter queryButton colMenu.sort colMenu.hide colMenu.search colMenu.commonValues" style="height: 600px; width: 100%"></data-table></div>

Live example at the bottom of Noah's Ark: The Logistics.  Column headers sort; each column's menu filters; the SQL button runs ad-hoc queries (SELECT … FROM "path/without/extension" — quote the table name, it contains slashes).  Full options: /admin/docs/code/DataTable.md.

Author notes that don't render

Wrap draft notes in an HTML comment — <!-- TODO: verify this date -->. Comments are stripped from the output entirely (they don't even ship in the page source), so they're the right tool for scaffolding. A comment shown literally in a code span, like the one in this sentence, is left alone.

Do not use ==double-equals== for notes — that now renders as a visible highlight (see the formatting table above).

What's turned off

These common Markdown extensions are not enabled, and typing them yields literal text: task list checkboxes (- [ ]), math ($$…$$), Mermaid/chart diagrams, [[Ctrl]] key styling, "smart" typography, and the [toc] token. Fenced code blocks are on and get automatic syntax highlighting.

Previewing and cache

Just reload the page — a .md edit is detected by file time and recompiled. If you change the theme or a shared include and the page looks stale, append ?cache=0 to force a rebuild.

Rough edges (notes for maintainers)

Honest list of things still worth improving:

1. Every image repeats style="width: 100%". A default #content img { max-width: 100% } (or a .full utility) would delete hundreds of inline styles — a cleaner answer than inline styling per image.

Sources

The :letter convention below is live: this sentence cites two pages of one source^{1 1} so you can see how the lettered children nest under their base entry in the list below.