TOCflow

Support & docs · Download (free) · Report a bug

A lightweight, server-rendered Table of Contents block for the WordPress block editor. Drop it into a post and it automatically builds a clean, linked outline from your headings — fast, SEO-friendly, and accessible out of the box.

TOCflow is the free core of a freemium product. See CLAUDE.md for the architecture notes and the Pro roadmap.

---

Why TOCflow

• Zero config — add the block; the outline builds itself from your headings.
• Server-rendered — the list is in the initial HTML, so search engines and screen readers see it immediately (no JavaScript required on the front end).
• Accurate anchors — matching ids are injected into your headings automatically, so every link scrolls to the right place.
• Accessible — output is a proper <nav> landmark.
• Focused — one block done well, not a bloated block library.

Features (v0.1.0)

• Auto-generates the TOC from H2 / H3 / H4 headings
• Toggle which heading levels are included
• Numbered or bulleted list
• Color, spacing, and typography controls via standard block settings

---

Standard Operating Procedure

This README is written as an SOP. Follow the section that matches what you're doing.

SOP A — Install & use (site owners)

1. Get the plugin. Download tocflow.zip from the Releases page.
2. Install. In WordPress admin: Plugins → Add New → Upload Plugin, choose the ZIP, click Install Now, then Activate.
3. Add the block. Edit a post that has Heading blocks. Click +, search “Table of Contents,” and insert it (usually right after your intro).
4. Customize (optional). With the block selected, open the Settings sidebar to set the title, choose which heading levels appear (H2/H3/H4), and switch between a numbered or bulleted list.
5. Verify. Preview the post and click a TOC link — it should jump to the matching heading.

Full walkthrough, troubleshooting, and FAQ: docs/USER_SOP.md.

SOP B — Develop locally (contributors)

# 1. Fork on GitHub, then clone your fork:
git clone https://github.com/<your-username>/tocflow.git
cd tocflow

# 2. Install build tooling:
npm install

# 3. Build in watch mode while you work:
npm run start
# ...or a one-off production build:
npm run build

Make the plugin visible to a local WordPress site (e.g. wp-env, Local, or by copying this folder into wp-content/plugins/tocflow), then activate it and test.

The compiled build/ directory is git-ignored — you must build at least once before the plugin runs.

Full setup, coding standards, testing checklist, and release steps: docs/DEVELOPER_SOP.md.

SOP C — Contribute a change

1. Branch off main (feat/…, fix/…, docs/…).
2. Make your change; run npm run lint:js, npm run lint:css, npm run build.
3. Confirm the block inserts, renders, and links scroll correctly.
4. Open a Pull Request against main and fill in the template.

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

SOP D — Cut a release (maintainers)

1. Bump the version in all four places so they match: tocflow.php, package.json, src/block.json, and readme.txt (Stable tag).
2. Add a dated entry to CHANGELOG.md and readme.txt.
3. npm run build then npm run plugin-zip to produce tocflow.zip.
4. Commit, tag (git tag vX.Y.Z && git push --tags), and publish a GitHub Release with the ZIP attached.

---

Project layout

tocflow.php            Plugin header + PHP helpers + heading-id filter
src/
  block.json           Block metadata, attributes, supports
  index.js             Block registration
  edit.js              Editor UI
  render.php           Server-side front-end render
  style.scss           Front-end styles
  editor.scss          Editor-only styles
build/                 Compiled output (generated by npm run build)
docs/                  USER_SOP.md, DEVELOPER_SOP.md

Documentation index

• User SOP — install, use, troubleshoot
• Developer SOP — build, branch, test, release
• Contributing · Code of Conduct · Changelog
• CLAUDE.md — architecture + roadmap

License

GPL-2.0-or-later