Tome

Settings

Colour theme

Export brand

Export

Include contents page in Markdown export

Document metadata

The first non-empty lines before any heading are treated as metadata. Tome looks for:

The first line of text becomes the document title (shown in the sidebar and browser tab)
A line matching VE.# is captured as the document version

Heading hierarchy

Markdown	Tome uses it as
`# Heading 1`	Navigation group (collapsible section header)
`## Heading 2`	Page — each H2 becomes a separately viewable page
`### – #####`	In-page headings (auto-generates a table of contents)

Supported content

All standard Markdown: tables, code blocks, images, links, lists, blockquotes
HTML passthrough is enabled — you can embed raw HTML if needed
Deep links use the URL hash: #section-heading-page-title

Callouts

Blockquotes with a special tag on the first line are rendered as styled callout boxes. The tag is stripped from the output.

Syntax	Type	Appearance
`> [!WARNING] text`	Warning	Yellow accent, ⚠ icon
`> [!INFO] text`	Info	Blue accent, ℹ icon
`> [!TIP] text`	Tip	Green accent, ✎ icon
`> [!DANGER] text`	Danger	Red accent, ✕ icon
`> [!NOTE] text`	Note	Purple accent, ✱ icon

Multi-line callouts work normally — just keep the > prefix on each line. The tag only needs to appear on the first line.

Every book Tome knows about is declared in one central file: Books/books.json. It is an ordered array; the first entry is the default book on first load and entries appear in the sidebar dropdown in order.

Where everything lives

Books/
  books.json               <-- the one file you edit to add/remove books
  my-monolithic-book.md    <-- a monolithic book (one .md file)
  my-directory-book/       <-- a directory book (folder of files)
    Section One/
      page-1.md
      page-2.md
    Diagrams/
      chart.png

Adding a monolithic book

A monolithic book is a single markdown file. Drop the .md into Books/ (or a sub-folder) and add one entry:

{
  "file":  "Books/my-book.md",
  "title": "My Book"
}

Adding a directory book

A directory book is a folder of markdown files organised into sub-folders. Declare it inline in books.json with directory, title, and sections:

{
  "directory": "Books/my-directory-book",
  "title":     "My Directory Book",
  "sections": [
    {
      "title": "Section One",
      "pages": [
        "page-1.md",
        "page-2.md"
      ]
    },
    {
      "title": "Section Two",
      "pages": [
        { "file": "intro.md", "title": "Introduction" },
        "details.md"
      ]
    }
  ]
}

See the Directory-Format Books section for the full manifest schema (folder overrides, page title overrides, optional metadata, etc.).

Removing a book

Delete its entry from books.json. The book’s files on disk are left alone — removing the entry just hides it from the viewer. Delete the files too if you no longer need them.

Reordering books

The order of entries in books.json is the order shown in the sidebar dropdown. Reorder the array to reorder the list. The first entry is loaded by default when a new user visits for the first time.

Changing the default book

Tome opens whichever book was loaded last (per-browser, via localStorage). On first visit, or after clearing site data, it loads the first entry in books.json. To change the default for new users, move that entry to position 0.

Complete example

[
  {
    "file":  "Books/quick-start.md",
    "title": "Quick Start Guide"
  },
  {
    "directory": "Books/Governance",
    "title":     "Helpdesk Operations Manual - Governance",
    "sections": [
      {
        "title": "Overview",
        "pages": [ "intro.md", "scope.md" ]
      },
      {
        "title": "Policies",
        "pages": [ "policy-1.md", "policy-2.md" ]
      }
    ]
  }
]

After editing books.json, refresh the page in the browser. There is no build step.

A book can live either as a single monolithic .md file or as a folder of files. Both formats are fully supported and mix freely in the same Books/books.json (see Managing Books for add/remove instructions).

When to use which

Format	Good for
Monolithic `.md`	Small books, single-author documents, when you want one file to edit and ship
Directory	Large manuals, multi-author content, when sections/pages are worked on independently

Folder structure

The root folder is the book. Each sub-folder you list in the manifest is a section (equivalent to an H1 in a monolithic book). Each .md file inside a section folder is a page (equivalent to an H2 in a monolithic book). Asset folders (like Diagrams/) are ignored unless referenced by a page.

Books/
  my-book/
    Section One/
      page-1.md
      page-2.md
    Section Two/
      overview.md
      details.md
    Diagrams/
      flowchart.png

Page markdown

Inside each page file, author the body as you would any markdown document:

The first # heading in the file becomes the page title in the sidebar. The original H1 is stripped from the rendered view and replaced by the title.
Remaining headings are demoted one level when assembled into the book (so a page’s ## subsections render as H3 inside the page — they stay in the page, they do not become new pages).
All standard content (tables, code blocks, images, callouts, etc.) works exactly as in monolithic books.

Manifest schema

Every directory book is declared with a manifest. The recommended place is inline in Books/books.json (edit one file to manage everything). Tome also accepts a book.json at the directory root as a fallback, which is useful when distributing a book as a portable self-contained folder.

{
  "directory": "Books/my-book",     // only at the books.json level
  "title": "My Book",               // optional; defaults to folder name
  "version": "1.0",                 // optional metadata
  "date": "2026-04-21",             // optional
  "classification": "Internal",     // optional
  "sections": [
    {
      "title": "Section One",       // shown as the section header
      "folder": "Section One",      // optional; defaults to title; use "" for book root
      "pages": [
        "page-1.md",                // shorthand - title taken from file's first H1
        "page-2.md",
        { "file": "page-3.md", "title": "Explicit Page Title" }
      ]
    },
    {
      "title": "Section Two",
      "pages": [ "overview.md", "details.md" ]
    }
  ]
}

Images & cross-references

Relative image paths resolve against the page’s section folder, so ![diagram](chart.png) in a page in Section One/ loads Section One/chart.png.
Use ../ to reference files in sibling folders (e.g. ../Diagrams/flow.png).
Markdown or HTML links that target another .md file inside the same book are rewritten automatically to navigate within the viewer — clicking jumps to that page, it does not download the raw file.

You can link from any page in one book to a specific page in another book. When clicked, Tome switches to the target book and shows a floating “Back to …” button so the reader can return to where they were.

Syntax

Use an HTML anchor with the tome:// protocol:

<a href="tome://book-folder#policy-slug">Link text</a>

How to find the values

Part	Where to find it
`book-folder`	The folder name inside `Books/` that contains the target book’s `.md` file (e.g. `operationsmanual-governance-ve16`)
`policy-slug`	Navigate to the target page in Tome and copy the text after `#` in the browser URL bar

Behaviour

Works between any two books listed in Books/books.json, in any direction
On click, Tome saves your current position, switches to the target book, and navigates to the target page
A floating “← Back to …” button appears at the bottom of the screen
Clicking the back button returns you to the exact book and page you came from
If the target book or page is not found, an alert is shown and no navigation occurs

Example

<a href="tome://operationsmanual-governance-ve16#non-critical-ticket-handling-escalation-policy">Escalation Policy</a>

All branding is configured through tome.json. No source code changes are needed.

Sidebar & browser tab

Key	What it controls
`branding.defaultTitle`	The title shown in the sidebar and browser tab before a book loads (or as a fallback if the markdown has no title)
`branding.classification`	The label beneath the title, e.g. “Internal Use Only” or “Confidential”
`branding.favicon`	Path to the browser tab icon (SVG, PNG, or ICO)

Splash screen

On load, Tome shows a full-screen splash with the “TOME” wordmark. Control how long it stays visible:

Key	What it controls
`splash.minDurationMs`	Minimum splash duration in milliseconds (default: 2000)

The splash always waits for the book manifest to load. If loading takes longer than the minimum, the splash stays until loading completes.

PDF letterhead

PDF export branding is configured through brand profiles in export-branding/. See the Export Branding section for details.

For backwards compatibility, tome.json still supports pdf.logo and pdf.footer as a fallback when no brand profiles are configured.

Example

{
  "branding": {
    "defaultTitle": "Company Handbook",
    "classification": "Internal Use Only",
    "favicon": "brand-icon.svg"
  },
  "pdf": {
    "logo": "company-logo.png",
    "footer": [
      "example.com | hello@example.com | 01onal 123 456",
      "Example Ltd, 1 High Street, London, EC1A 1BB",
      "Registered in England 12345678"
    ]
  },
  "splash": {
    "minDurationMs": 2500
  }
}

Books/books.json

The single source of truth for which books appear in the viewer. An ordered array — the first entry is loaded by default on first visit, and entries appear in the sidebar dropdown in order. A file entry is a monolithic book; a directory entry with a sections array is a directory-format book declared inline. See Managing Books for step-by-step add/remove instructions.

[
  {
    "file":  "Books/my-guide.md",
    "title": "My Guide"
  },
  {
    "directory": "Books/my-directory-book",
    "title":     "Multi-File Book",
    "sections": [
      { "title": "Intro",    "pages": [ "01-welcome.md", "02-setup.md" ] },
      { "title": "Policies", "pages": [ "p1.md", "p2.md" ] }
    ]
  }
]

tome.json

Controls platform branding and behaviour. All fields are optional.

{
  "branding": {
    "defaultTitle": "My Documentation",
    "classification": "Internal Use Only",
    "favicon": "my-icon.svg"
  },
  "pdf": {
    "logo": "logo.png",
    "footer": ["Line 1", "Line 2", "Line 3"]
  },
  "splash": {
    "minDurationMs": 2000
  }
}

Key	Purpose
`branding.defaultTitle`	Fallback title if the markdown has none
`branding.classification`	Label shown below the title
`branding.favicon`	Path to the browser tab icon
`pdf.logo`	Fallback letterhead image (used when no brand profiles exist)
`pdf.footer`	Fallback footer text (used when no brand profiles exist)
`splash.minDurationMs`	Minimum splash screen duration in milliseconds

PDF exports use brand profiles stored in export-branding/. Each brand has its own directory with a configuration file and media assets.

Directory structure

export-branding/
  brands.json
  default/
    brand.json
    media/
      letterhead_logo.png
  client-a/
    brand.json
    media/
      logo.png
      watermark.png

brands.json

An array of brand directory names. The first entry is the default.

["default", "client-a"]

brand.json

Each brand’s configuration file. All fields are optional and fall back to sensible defaults.

{
  "label": "Client A Branded",
  "pageSize": "a4",
  "orientation": "portrait",
  "margins": {
    "top": 20, "right": 10,
    "bottom": 15, "left": 10
  },
  "header": {
    "logo": "media/logo.png",
    "logoWidth": 40,
    "logoAspect": 4.04,
    "x": 15, "y": 8
  },
  "footer": {
    "lines": [
      "Client A Corp",
      "123 Main Street",
      "Confidential"
    ],
    "fontSize": 9,
    "color": 80
  },
  "coverPage": true,
  "coverTitle": "Operations Manual"
}

Key	Purpose
`label`	Display name in the brand picker dropdown
`pageSize`	PDF page size: `a4`, `letter`, or `legal`
`orientation`	`portrait` or `landscape`
`margins`	Page margins in mm (top, right, bottom, left)
`header.logo`	Path to logo image, relative to the brand directory
`header.logoWidth`	Logo width in mm (default: 40)
`header.logoAspect`	Logo width-to-height ratio (default: 4.04)
`header.x` / `header.y`	Logo position in mm from the top-left corner
`footer.lines`	Array of up to 3 strings, centred at the bottom of each page
`footer.fontSize`	Footer text size in points (default: 9)
`footer.color`	Footer text colour as a greyscale value 0–255 (default: 80)
`coverPage`	Whether to include a cover page in full-manual export (default: true)
`coverTitle`	Override the cover page title (defaults to the document title)

Multiple brands

When two or more brands are defined in brands.json, a dropdown appears in the Settings → Export section. Select a brand before exporting to apply its letterhead, footer, and page settings.

Fallback

If export-branding/brands.json is missing or fails to load, Tome falls back to the PDF settings in tome.json (the pdf.logo and pdf.footer keys).

Key	Action
`/`	Focus the search box
`n`	Go to the next page
`p`	Go to the previous page
`Escape`	Clear search / close settings panel

Tome

Tome
markdown-it
markdown-it-anchor
html2pdf.js
html2canvas

Proprietary software. Unauthorised use, copying, or distribution is prohibited.

Changelog

v2.9.0

In-page table of contents moved into a dedicated right-side nav pane that mirrors the left sidebar’s width and theme, so both navigation surfaces frame the main content symmetrically
Scroll-spy highlighting: the right-pane entry for the heading currently in view is highlighted and updates live as the reader scrolls through the page
Clicking any right-pane entry smooth-scrolls the main pane to that heading
Right pane is collapsible — chevron inside the pane hides it, hamburger at the top-right reopens it, state persisted to localStorage (mirrors the left sidebar)
Right pane auto-hides on pages with fewer than three sub-headings so short pages keep the full content width
Right pane is hidden below 980px (mobile) to preserve the existing single-column layout
Settings tab relocated from the top-right edge to the bottom-right edge (same pill-tab aesthetic, now pokes up from the bottom) so the top-right corner is free for the right pane’s reopen hamburger
Back-to-top button nudged inward on desktop so it no longer overlaps the repositioned settings tab
Removed the inline “In this page” card that previously rendered at the top of the content area

v2.8.0

Directory-format books — a book can now live as a folder of markdown files instead of a single monolithic .md. The root folder is the book, each sub-folder is a section (H1 equivalent), and each .md file within a section is a page (H2 equivalent)
All book configuration is now centralised in Books/books.json: directory books declare their sections and pages inline alongside monolithic books, so there is one file to edit to add, remove, or reorder any book
New books.json schema: monolithic entries use file, directory entries use directory + sections. Existing file-only entries (including paths without .md) keep working for backwards compatibility
A directory can still carry its own book.json at the root as a fallback — useful for distributing a book as a portable self-contained folder — but it’s no longer required
Each page’s first H1 becomes its sidebar title; remaining headings in the file are demoted one level when the book is assembled, so in-page subsections never collide with page or section boundaries
Relative image paths in a directory-book page resolve against the page’s section folder, with ../ supported for cross-folder asset references
Markdown and HTML links that target another .md file within the same directory book are rewritten automatically to navigate within the viewer instead of fetching the raw file
Added “Managing Books” and “Directory-Format Books” sections to Settings → Guide covering add/remove/reorder workflow and the full manifest schema

v2.7.0

Deferred PDF export libraries (html2pdf, html2canvas) so they no longer block initial page render
Switched all fetch calls from cache: "no-store" to cache: "default" for faster navigation
Images in rendered markdown now use lazy loading and are centred in the content area
Added content width toggle — three responsive presets (narrow 60%, medium 80%, wide 100%) pinned above the document area, persisted to localStorage
Collapsible sidebar — chevron button at the top of the sidebar collapses it entirely; hamburger button fixed top-left to reopen; state persisted to localStorage
Callout blocks — blockquotes with [!WARNING], [!INFO], [!TIP], [!DANGER], or [!NOTE] tags render as styled callout boxes with coloured accents and icons (compatible with GitHub alert syntax)
Cross-book links — tome:// protocol allows linking between books with automatic “Back to…” return button; return button pulses every 20s and has a dismiss option
Selected book now persisted to localStorage — refreshing the page returns to the same book and policy instead of defaulting to the first book
New colour theme: Terminal (green-on-black with monospace font)
Cross-book return button and pulse animation now respect the active colour theme
Added guide sections for Callouts and Cross-Book Links in the Settings > Guide tab

v2.5.2

Improved PDF export page breaks: headings (H2–H5) now stay with their following content instead of being stranded at the bottom of a page
H1 group headers start on a new page and flow directly into their first policy
Full manual export renders each group as a single continuous block for smarter page slicing
PDF page break rules moved entirely to CSS — removed conflicting avoid-all mode from html2pdf config

v2.5.1

Platform version now loaded from version.json at startup — single source of truth, no more duplicate version strings
Fixed book picker dropdown showing blank instead of the loaded book title on startup

v2.5.0

Welcome screen shown when no books are configured, with getting-started instructions
Platform update scripts: update.sh (bash) and update.ps1 (PowerShell) for one-click updates from GitHub
Moved books.json manifest into the Books/ directory alongside user content
Added README.md with project documentation, quick start, and configuration reference
Removed external branding from platform defaults — all branding fully user-configurable

v2.4.1

Fixed issue with relative path resolution for images and links

v2.4.0

Migrated Tome to its own dedicated GitHub repository (tome.md)
Flattened project structure: removed nested TOME md/ directory so all files live at the repository root
Updated version check URL to point to the new canonical location at super-gill.github.io/tome.md/

v2.3.0

Export branding profiles: PDF exports now use pluggable brand configurations stored in export-branding/
Each brand has its own directory with a brand.json config and a media/ folder for logos and assets
Brand profiles control page size, orientation, margins, header logo, footer text, cover page, and cover title
When multiple brands are configured, a dropdown appears in Settings → Export to select the active brand
Falls back to tome.json PDF settings when no brand profiles are present (backwards compatible)
Added Export Branding section to the Guide tab with full configuration reference

v2.2.0

Automatic update check: on load, Tome fetches version.json from the canonical published URL and compares it to the running version
If a newer version is available, a dismissible banner appears at the bottom of the screen showing the current and latest versions
Update check is non-blocking and fails silently — no impact on offline or air-gapped deployments
Added version.json to the platform project for deployed instances to check against

v2.1.0

Settings button redesigned as a fixed pill-shaped tab in the top-right corner, rotated 90° so the tube extends off the top edge of the screen — always visible while scrolling
Settings button uses theme heading colour as background for contrast across all themes
Gear icon rendered via CSS pseudo-element with counter-rotation to stay upright
Code blocks (pre) now use theme tokens (--bg, --text, --border) instead of hardcoded colours
Inline code now uses theme tokens (--h1bg, --border) instead of hardcoded colours
Blockquote background switched from hardcoded colour to --h1bg theme token
Added .doc blockquote base style: left border in heading colour, tinted background, rounded right corners
Added .doc ol base style to match existing ul margin and spacing
Fixed indentation for tables and ordered lists: uses margin-left instead of padding-left to preserve borders and number gutters
Fixed indentation for code blocks (pre): margin-left override so padding: 12px no longer silently cancels the indent
Fixed indentation for horizontal rules (hr): switched to margin-left since padding has no effect on void elements
Fixed indentation for blockquotes: uses margin-left to shift the entire element (including left border) to the indent position

v2.0.0

Named the platform Tome with branded splash screen, wordmark, and loading overlay
Settings panel (slide-out) with three tabs: Settings, Guide, About
Guide tab with accordion-style expandable sections: Authoring, Branding, Media & Images, Configuration, PDF Export, Keyboard Shortcuts
About page showing platform and library versions, copyright, and proprietary notice
Changelog accessible from About tab via “View changelog” button
Colour themes: Dark, Light, Midnight, Ember, Forest, Sand, plus System auto-detect
Theme picker dropdown with data-tone system for clean light/dark CSS overrides
Export options (PDF and Markdown) for single page or full manual, accessible from settings
PDF export progress overlay with live page counter
Mobile responsive: hamburger menu with slide-out nav drawer (replaces 50/50 split)
Collapsible nav sections with expand/collapse all toggle, collapsed by default
Back to top button on scroll
Keyboard navigation: / to search, n/p to move between pages
In-page table of contents auto-generated from H3/H4/H5 headings
Copy link icon on page headings for deep-linking
Broken hash fallback with branded message
tome.json configuration file for branding, PDF settings, favicon, and splash duration
Self-hosted libraries (markdown-it, markdown-it-anchor, html2pdf, html2canvas) — no CDN dependency
Automatic image path resolution relative to book directory — images live alongside their markdown files
Restructured Books directory: each book in its own subfolder with co-located images
Print stylesheet hides all chrome, prints document content only
Cache-busting via version query strings on JS and CSS
Removed all external branding from platform code — all branding now configurable via tome.json
Genericised all user-facing language from “policy” to “page”
Copyright and proprietary software notice
Settings button moved to meta bar (top-right) for spatial proximity to panel
Default book loaded from first entry in books.json rather than hardcoded filename

v1.4.0

Multi-book support: books.json manifest with dropdown book picker
Dynamic book loading — first entry in manifest is the default
Sidebar branding updates dynamically from loaded book metadata
Platform versioning system introduced

v1.3.1

Rewrote PDF export engine using jsPDF bootstrap approach
H2 title retained in single-page PDF exports
Fixed canvas rendering issues in full-manual export

v1.3.0

Full-manual PDF export: all pages stitched into a single branded document
Canvas-slicing approach for accurate A4 page breaks
Letterhead header and footer stamped on every PDF page
SVG favicon support

v1.2.0

Single-page PDF export with branded letterhead
Collision-proof heading IDs (H1+H2 composite slugs)
Meta bar with breadcrumb navigation

v1.1.0

Separated code into three files: index.html, index.js, styles.css
Dynamic document metadata extraction (title, version from markdown)
Indent system for nested content rendering
CSS custom properties for theming groundwork

v1.0.0

Initial release: single-file application
Markdown rendering via markdown-it with anchor plugin
Sidebar navigation built from H1/H2 heading structure
Hash-based routing for deep-linking to individual pages
Full-text search with highlighted results
Dark theme by default with system light preference support

Document metadata

Heading hierarchy

Supported content

Callouts

Where everything lives

Adding a monolithic book

Adding a directory book

Removing a book

Reordering books

Changing the default book

Complete example

When to use which

Folder structure

Page markdown

Manifest schema

Images & cross-references

Syntax

How to find the values

Behaviour

Example

Sidebar & browser tab

Splash screen

PDF letterhead

Example

Recommended structure

Referencing images

How it works

Books in the root directory

Books/books.json

tome.json

Single page export

Full manual export

Markdown export

Directory structure

brands.json

brand.json

Multiple brands

Fallback

Changelog

v2.9.0

v2.8.0

v2.7.0

v2.5.2

v2.5.1

v2.5.0

v2.4.1

v2.4.0

v2.3.0

v2.2.0

v2.1.0

v2.0.0

v1.4.0

v1.3.1

v1.3.0

v1.2.0

v1.1.0

v1.0.0