---
title:             Markdown Guide
description:       "How to write Berean Archive articles in Markdown: frontmatter, footnotes, tables, callouts, images, and the custom syntax."
theme:             common/themes/berean2/theme.php
---

# 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](/contribute). 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](https://parsedown.org/)). Edits show up on the next page load; you never build anything by hand. [Typora](https://www.typora.io/) is a good free editor and previews most of this correctly.

You can read this page's own source at [markdown-guide.md](/contribute/markdown-guide.md).

## Cheat sheet

| You write | You get |
| --- | --- |
| `# Title` | The big page heading, laid in white over the header photo |
| `[^smith-2020]` | A numbered footnote reference |
| `[^smith-2020]: …` | Its citation (collected under `## Sources`) |
| `^text^` | Superscript (`x^2^` → x²) |
| `~text~` | Subscript (`H~2~O`) |
| `~~text~~` | ~~strikethrough~~ |
| `==text==` | ==highlighted== text |
| `++term++` | A glossary term, the short form of `<dfn>term</dfn>` |
| `<dfn>term</dfn>` | Glossary term with a pop-up definition |
| `<img src="pic.jpg?w=230" class="lightbox">` | A click-to-zoom, auto-resized image |
| `> [!NOTE]` | A callout box (note / info / tip / important / warning / caution) |
| a table, then `{: .ruled cols="25%"}` | Styles the table on the line above |
| `<!-- note -->` | An author note that is removed from the page |
{: .ruled cols="33%"}

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:

```text
---
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`.

| Key | What it does |
| --- | --- |
| `title` | The page's own name, with no site suffix — the theme appends ` | Berean Archive` for the browser tab and the social card. **Not** the visible heading, which comes from your `#` line. |
| `description` | The `<meta name="description">` and social-card description. 12-60 words, stating the article's conclusions. |
| `theme` | Always `common/themes/berean2/theme.php`. Without it you get bare, unstyled HTML. |
| `section` | The site section the article belongs to (`Biology`, `History`, `Sociology` or `Tools`), or a list running from the section down through its headings, e.g. `["Biology", "Junk DNA and Genome Function"]`. It is the breadcrumb over the title, and it lists a published article on the home page. |
| `photo` | The header photo behind the title, usually `header-wide.jpg`. Without one the header is a plain dark band. |
| `photoCaption` | The photo's caption or credit, at the right of the strip under the photo. May contain HTML (e.g. a credit link). |
| `socialImage` | The image used **only** for link-preview cards (Facebook / X / etc.) and the article's card on the home page, usually `header-square.jpg`. |
| `author` | Shown first in the strip under the photo, as "By …". |
| `published`, `updated` | Dates for the strip:  `"2017-05"` prints "May 2017" and `"2024-02-09"` prints "Feb 9, 2024".  Quote them. |
| `status` | `draft` prints the published date as "Draft:  …". |
| `layout` | `article` (the default:  contents on the left, citations in the right margin) or `wide` (one wide column, for tools and lists of articles). |
| `toc` | `false` hides the table of contents;  `true` adds one to a wide page. |
| `css` | CSS for this page only.  To frame the header photo:  `".hero-img { object-position: 50% 30% }"`. |
{: .ruled cols="25%"}

### Frontmatter is YAML

The block is parsed as real [YAML](https://yaml.org/), 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:

   ```text
   title: "Shroud of Turin:  1988 Carbon Dating"
   ```
3. An apostrophe is fine unquoted (`title: Paul's Letters`). A list, if you ever need one:

   ```text
   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:

| Syntax | Renders | Notes |
| --- | --- | --- |
| `^text^` | superscript | No spaces inside. Good for exponents and ordinals: `10^20^`, `2^nd^`, `cm^2^`. |
| `~text~` | subscript | No spaces inside: `H~2~O`. |
| `~~text~~` | ~~strikethrough~~ | |
| `==text==` | ==highlight== | Yellow `<mark>` highlight. |
| `++term++` | glossary term | No `+` inside. The same as `<dfn>term</dfn>`;  see below. |
{: .ruled cols="20% 20%"}

House style (from the [Contributing Guidelines](/contribute)) 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](/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:

```text
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.

```text
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:

```text
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](/contribute) for what goes inside a citation (linked titles, page numbers, archive mirrors, etc.). A typical definition with mirrors:

```text
[^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:

```text
> 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>`:

```text
<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:

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

> [!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:

```text
> [!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>`:

```text
> [!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](#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):

```text
| 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

| Class | Effect |
| --- | --- |
| `.ruled` | Ruled rows with a hairline under each, and small uppercase column labels. The style for data tables. |
| `.small` | Smaller type, for a table that lays out an image beside its explanation. |
| `.quotes` | One row per speaker:  a portrait in the first column, then the name, role and a `<blockquote>`.  An empty header row is hidden. |
| `.wide` | Lets the table reach into the right margin on wide screens. |
{: .ruled cols="20%"}

### Column widths — `cols="…"`

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

```text
{: .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:

```text
{: .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:

```text
<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

| Class | Effect |
| --- | --- |
| `lightbox` | Click to see the whole image, as large as the window allows.  Also works on a link around an image, `<a class="lightbox" href="big.png"><img src="big.png?w=300"></a>`, which opens the link's file. |
| `inverted` | Flips colors in dark mode. Put it on **line-art and charts** (black-on-white diagrams) so they stay readable — never on photos. |
| `wide` | Lets a detailed chart reach into the right margin on wide screens.  It is never enlarged past its own size. |
| `left`, `right` | A small image floated beside the text. |
{: .ruled cols="20%"}

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:

```html
<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](/unpublished-ai/ark-logistics/#appendix-browse-the-species-mass-dataset).  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[^hoehner-1978:a] [^hoehner-1978:b] so you can see how the lettered children nest under their base entry in the list below.

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