# PathMX — A local-first framework for interactive websites

> Build fast, interactive websites from readable files. PathMX keeps people and agents working from the same source and grows through plugins.

## When to use this site

Use this PathMX site to read, navigate, or cite its public Sources. The listed links return the authored Markdown representation directly. Use the sitemap for the canonical HTML URL index.

If your web reader cannot read Markdown, use the HTML URLs in the sitemap. With direct HTTP access, request a listed Markdown URL or send Accept: text/markdown to an HTML page URL. Private content requires the site's authentication and permissions.

## Public pages

- [PathMX — A local-first framework for interactive websites](https://docs.pathmx.dev/index.md) — Build fast, interactive websites from readable files. PathMX keeps people and agents working from the same source and grows through plugins.
- [PathMX docs](https://docs.pathmx.dev/docs/index.md) — Build interactive websites from Markdown and HTML. Start with a page, connect it to others, then add layouts, presentations, forms, or your own Plugins.
- [Accounts and attachments](https://docs.pathmx.dev/docs/accounts/index.md) — Let readers sign in, participate as themselves, and attach files to their work.
- [Attachments](https://docs.pathmx.dev/docs/accounts/attachments.reference.md) — Let a reader upload a project file, download it later, or remove it. The @pathmx/uppy package adds the upload controls and stores an attachment record and...
- [Authentication](https://docs.pathmx.dev/docs/accounts/auth.reference.md) — Optional authentication and account UI for PathMX applications. Development mode provides local Actor switching; production supports provider-based credentials...
- [PathMX for agents](https://docs.pathmx.dev/docs/agents/index.md) — Start here when working in a PathMX repository. Identify the installed version, find the reference for your task, and verify changes using the project's own...
- [Authoring](https://docs.pathmx.dev/docs/authoring/index.md) — Write pages in Markdown, connect them with links, and divide longer material into Blocks that work in reading, Focus, and Slides. Start with Sources and...
- [Assets and scripts](https://docs.pathmx.dev/docs/authoring/assets.reference.md) — Keep images, downloadable files, CSS, and JavaScript beneath paths/.
- [Blocks](https://docs.pathmx.dev/docs/authoring/blocks.reference.md) — A Block is a meaningful section of a Source, separated by a --- line. It keeps one idea, example, or task step together and can have its own identity, data,...
- [Callouts](https://docs.pathmx.dev/docs/authoring/callouts.reference.md) — A callout is a blockquote whose first line names its type. Use one to set a note, tip, or warning apart from the flow.
- [Components](https://docs.pathmx.dev/docs/authoring/components.reference.md) — Components add reusable elements to Markdown. Define templates in a .components.md file, or contribute components from a TypeScript Plugin.
- [Embed web content](https://docs.pathmx.dev/docs/authoring/embed.reference.md) — Turn a titled Markdown link into an X post, YouTube player, or rich card for another public web page:
- [Generate Sources](https://docs.pathmx.dev/docs/authoring/generate.reference.md) — Use @pathmx/generate to turn JSON or CSV records into ordinary Markdown Sources with Knap templates.
- [Images](https://docs.pathmx.dev/docs/authoring/images.reference.md) — Image sizing, responsive variants, backgrounds, galleries, and a full-size viewer.
- [Input forms](https://docs.pathmx.dev/docs/authoring/input.reference.md) — Core Input turns authored controls into response forms. A response belongs to one Block; its saved draft and submitted response remain separate.
- [Links](https://docs.pathmx.dev/docs/authoring/links.reference.md) — A relative link to an exact file is an edge in the site graph. PathMX renders the canonical route and keeps the link working in editors and on GitHub.
- [Maps and type vocabulary](https://docs.pathmx.dev/docs/authoring/maps.reference.md) — A Map gives your Source types shared labels, descriptions, icons, and colors. Types still come from filenames such as contrast.lesson.md; a Map describes how...
- [Markdown](https://docs.pathmx.dev/docs/authoring/markdown.reference.md) — Ordinary Markdown renders as semantic HTML. Core's standard Plugins also support tables, highlighted code, MathML, task lists, definition lists, and inline...
- [Mermaid diagrams](https://docs.pathmx.dev/docs/authoring/mermaid.reference.md) — Turn a text description into a diagram that follows your site's theme. Edit the connections alongside the explanation, then present the same result in Player.
- [Queries](https://docs.pathmx.dev/docs/authoring/queries.reference.md) — A query fence renders a live list, table, or component from Sources or Blocks that match. Results respect the reader's access.
- [Reuse content](https://docs.pathmx.dev/docs/authoring/reuse-content.guide.md) — Include a complete Block when the same instructions belong in several places. Edit the owner once and its consumers update together.
- [Sound effects](https://docs.pathmx.dev/docs/authoring/sfx.reference.md) — SFX attaches audio to authored moments and ordinary browser events. A cue plays once; a loop continues until stopped. The viewer controls listening through...
- [Open Sources alongside a page](https://docs.pathmx.dev/docs/authoring/source-opening.guide.md) — Keep supporting material in a reference sidebar, or open a Source in an overlay without leaving the current page. Layouts supply the destinations; links and...
- [Sources](https://docs.pathmx.dev/docs/authoring/sources.reference.md) — A Source is one Markdown file under paths/. Its filename gives it a name, a type, and a route; frontmatter adds metadata.
- [Video](https://docs.pathmx.dev/docs/authoring/video.reference.md) — Install and activate the optional Video Plugin with bun run pmx plugins add video before using @video in your project.
- [CLI](https://docs.pathmx.dev/docs/cli.reference.md) — The pathmx command manages, serves, and inspects a project from its package.json root. pmx is the short alias.
- [Docs components](https://docs.pathmx.dev/docs/docs.components.md) — Link readers to the next useful guide. Authoring uses generated rows; Start and Extend use curated rows with summaries written for the task.
- [Documentation vocabulary](https://docs.pathmx.dev/docs/docs.map.md) — File types tell you what to expect from a page. This Map gives those types a shared label, icon, and color throughout the site.
- [Email](https://docs.pathmx.dev/docs/email.reference.md) — @pathmx/email turns authored .email.md Sources into transactional messages. It captures messages by default and uses Resend when production sending is enabled.
- [Extend PathMX](https://docs.pathmx.dev/docs/extend/index.md) — Adapt a site to your domain: render your own content, add interactions, or save personal work. Install an existing capability first, or write a Plugin when...
- [Actions](https://docs.pathmx.dev/docs/extend/actions.reference.md) — An Action defines a validated operation shared by forms and server callers. Register Actions through a plugin.
- [Agents](https://docs.pathmx.dev/docs/extend/agents.reference.md) — @pathmx/agents lets you author agents as Markdown Actors that ask models with their own permissions and talk with people in threads.
- [AI](https://docs.pathmx.dev/docs/extend/ai.reference.md) — @pathmx/ai gives Plugins named AI models, called through an admitted View.
- [Core API](https://docs.pathmx.dev/docs/extend/core.reference.md) — Use the Bun adapter to host a PathMX repository programmatically. For ordinary site authoring, the CLI supplies this setup.
- [Events](https://docs.pathmx.dev/docs/extend/events.reference.md) — Events describe Plugin activity. Core validates data and distinguishes committed Actions, server observations, and browser observations. Analytics can persist...
- [Interactions](https://docs.pathmx.dev/docs/extend/interactions.reference.md) — An interaction is what one part of a page lets someone do: its state and its actions, defined once for people and agents.
- [Durable jobs](https://docs.pathmx.dev/docs/extend/jobs.reference.md) — Plugins register jobs to handle trusted Events after the originating operation commits.
- [Plugin configuration](https://docs.pathmx.dev/docs/extend/plugin-configuration.reference.md) — Configure a reusable Plugin for each project. Package a greeting command and set its options to print Welcome.
- [Make a custom Plugin](https://docs.pathmx.dev/docs/extend/plugins.guide.md) — Add a reading-time component to your site with a small TypeScript Plugin. Start with a working PathMX project.
- [Plugin API](https://docs.pathmx.dev/docs/extend/plugins.reference.md) — Use this reference alongside Make a custom Plugin. Import the helpers and public types below from @pathmx/core. Callback types are inferred by the helpers; no...
- [React applications](https://docs.pathmx.dev/docs/extend/react.reference.md) — Use React for a region with its own interactive state, such as a filterable catalog or editor. Use a Markdown component when reusable markup and slots are...
- [Personal Sources and device settings](https://docs.pathmx.dev/docs/extend/state.reference.md) — Saved responses, progress, and other committed work belong to Sources. Device preferences and draft recovery are disposable: clearing them does not remove...
- [Contextual Views](https://docs.pathmx.dev/docs/extend/views.reference.md) — A story can let the same reader discover a memory in one conversation while keeping it undiscovered in another.
- [WebMCP](https://docs.pathmx.dev/docs/extend/webmcp.reference.md) — @pathmx/webmcp lets supported browsers discover and invoke the interactions in an open PathMX site. Enable it once; mounted Sources need no exposure...
- [Hosting](https://docs.pathmx.dev/docs/hosting/index.md) — Publish public pages as static files, or run a live site for shared accounts and writable content.
- [Analytics](https://docs.pathmx.dev/docs/hosting/analytics.reference.md) — Analytics records public content use and selected activity. Its CLI reports persisted observations and refreshes automatically in an interactive terminal....
- [Publish to Cloudflare](https://docs.pathmx.dev/docs/hosting/cloudflare.guide.md) — Publish a static PathMX build as a Cloudflare Worker with Static Assets. Supported Plugin server slices can run alongside the exported pages.
- [Server deployment](https://docs.pathmx.dev/docs/hosting/deployment.reference.md) — @pathmx/deploy updates writable PathMX sites over SSH. It adopts an existing macOS user LaunchAgent running checkout-local pmx serve.
- [Learning experiences](https://docs.pathmx.dev/docs/learning/index.md) — Turn linked Sources into lessons people can read, present, and explore. Begin with a clear sequence of Blocks, then add the tools your activity needs.
- [Assessment](https://docs.pathmx.dev/docs/learning/assessment.reference.md) — Turn Markdown question Blocks into response forms. Assessment describes the questions and evaluation; Core Input owns drafts and submissions.
- [Completion](https://docs.pathmx.dev/docs/learning/completion.reference.md) — Declare completion targets and show progress for Markdown Sources.
- [Paths](https://docs.pathmx.dev/docs/learning/path.reference.md) — A Path is an ordered set of links to activities. Each step keeps its authored label, linked Source or instance, and progress from the installed Completion...
- [Player](https://docs.pathmx.dev/docs/learning/player.reference.md) — Player turns a Source into focused reading or slides. Blocks and Beats choreograph learning: Blocks frame a topic or activity; Beats guide attention through it.
- [The PathMX methodology](https://docs.pathmx.dev/docs/methodology.md) — PathMX is a method for organizing knowledge so people and agents can read, connect, and revise it together: write Markdown, name each file's role, and link the...
- [Packages](https://docs.pathmx.dev/docs/packages.reference.md) — Core supplies the CLI and standard site-authoring features. Optional packages add learning tools, application interfaces, authentication, and deployment...
- [Shape a site](https://docs.pathmx.dev/docs/site/index.md) — Use shared layouts, navigation files, and themes to turn individual Sources into a cohesive site. Follow Build a workshop site for a complete example.
- [Feeds](https://docs.pathmx.dev/docs/site/feeds.reference.md) — Feed publishes an RSS feed from an ordinary query. Readers receive each item's full text, and pages listed in the feed advertise it to browsers and feed...
- [Graph](https://docs.pathmx.dev/docs/site/graph.reference.md) — Show local Source connections as backlinks, an inline graph, or a dialog. Install the optional Graph package:
- [Layouts](https://docs.pathmx.dev/docs/site/layouts.reference.md) — A .layout.md Source defines the HTML around a page. Place one outlet where its Blocks should appear.
- [Navigation](https://docs.pathmx.dev/docs/site/navigation.reference.md) — A .navigation.md Source defines a shared menu as a Markdown list. Import it under a name and render it with .
- [Search](https://docs.pathmx.dev/docs/site/search.reference.md) — Find pages by title or content. Site Search includes pages reachable from the homepage through Sources the current reader can access.
- [Short links](https://docs.pathmx.dev/docs/site/short.reference.md) — Short gives a page a stable URL that follows its owning Source. Use it for QR codes, slides, and printed material whose destination may change later.
- [Stylesheets](https://docs.pathmx.dev/docs/site/styles.reference.md) — Link CSS from a Source or layout to style your site. Use your own classes for your elements and the shared tokens from Themes and Typography for appearance.
- [Theme a site](https://docs.pathmx.dev/docs/site/theme-a-site.guide.md) — Give a site its own colors, typeface and type scale, then style one kind of page.
- [Themes](https://docs.pathmx.dev/docs/site/themes.reference.md) — A theme sets a site's shared colors, type and shapes through tokens. Start from a preset or the plain foundation, then adjust tokens in frontmatter or CSS.
- [Typography](https://docs.pathmx.dev/docs/site/typography.reference.md) — Typefaces, body text and headings come from a few tokens. Set them in a theme stylesheet or in theme: frontmatter; see Themes.
- [Shared UI](https://docs.pathmx.dev/docs/site/ui.reference.md) — Give readers familiar controls with clear labels, keyboard focus, and predictable opening and closing behavior.
- [Start](https://docs.pathmx.dev/docs/start/index.md) — Ready to make something? Create a site, watch your edits appear, and build a complete workshop before choosing how to publish it. Start with Install if Bun is...
- [Build a workshop site](https://docs.pathmx.dev/docs/start/build-a-site.guide.md) — Turn the two pages from Quickstart into a small workshop with shared navigation, a theme, and a reusable lesson card. Keep bun run dev running as you edit.
- [Quickstart](https://docs.pathmx.dev/docs/start/first-site.guide.md) — Create a site with the CLI, then use its package scripts for everyday work. Each repo owns its dependencies, commands, and Plugin activation in package.json.
- [Install](https://docs.pathmx.dev/docs/start/install.guide.md) — PathMX runs on Bun. Each site installs and pins Core in its own package.json.
- [Upgrade to PathMX 0.7](https://docs.pathmx.dev/docs/start/migrate-070.guide.md) — Upgrade an existing project to 0.7.0 while preserving authored content, saved responses, and access rules. Use the checklist yourself, or copy the agent prompt...
- [Project structure](https://docs.pathmx.dev/docs/start/project-structure.guide.md) — Filenames carry meaning. A file's name gives its route, and its last dotted segment gives its type, so a directory listing already explains the site.
- [Publish](https://docs.pathmx.dev/docs/start/publish.guide.md) — A site ships either as static files from pmx export or as a live server from pmx serve. Both build the same pages through the same access rules.
- [How PathMX runs](https://docs.pathmx.dev/docs/start/runs.guide.md) — Publish public content as static files, or run a live server for accounts, private content, and shared saved work. Browser-hosted apps can also save personal...
- [Examples](https://docs.pathmx.dev/examples/index.md) — A small collection of places to read, explore, and learn. Follow your curiosity, then open the Markdown to see how each one is made.
- [Block Layouts](https://docs.pathmx.dev/examples/block-layouts.demo.md) — Reusable Block composition belongs to the Source and remains intact in the normal document, Focus mode, and Slides mode.
- [A bookcase from Markdown](https://docs.pathmx.dev/examples/bookcase/index.demo.md) — Turn a folder of book notes into a reading shelf with reusable cards and a query.
- [Educated](https://docs.pathmx.dev/examples/bookcase/books/educated.book.md) — By Tara Westover · 2018
- [Hyperion](https://docs.pathmx.dev/examples/bookcase/books/hyperion.book.md) — By Dan Simmons · 1989
- [The Left Hand of Darkness](https://docs.pathmx.dev/examples/bookcase/books/left-hand-of-darkness.book.md) — By Ursula K. Le Guin
- [Moby-Dick](https://docs.pathmx.dev/examples/bookcase/books/moby-dick.book.md) — By Herman Melville
- [Neuromancer](https://docs.pathmx.dev/examples/bookcase/books/neuromancer.book.md) — By William Gibson · 1984
- [Pride and Prejudice](https://docs.pathmx.dev/examples/bookcase/books/pride-and-prejudice.book.md) — By Jane Austen
- [Reading shelf components](https://docs.pathmx.dev/examples/bookcase/shelf.components.md) — Build a small library with covers you can browse and shelves you can fill. Four components work together: a wooden bookcase, rows of shelves, books that open...
- [Callouts](https://docs.pathmx.dev/examples/callouts.demo.md) — Callouts use Obsidian-compatible blockquote syntax and keep normal Markdown available inside their bodies.
- [Chess Components](https://docs.pathmx.dev/examples/chess/chess.components.md) — Study the Opera Game · Play a game
- [A night at the opera](https://docs.pathmx.dev/examples/chess/opera-game.demo.md) — Follow Paul Morphy’s 17-move masterpiece, one position at a time.
- [Play a game of chess](https://docs.pathmx.dev/examples/chess/play.demo.md) — A local two-player chessboard with legal moves, promotion, and undo.
- [Code Highlight Demo](https://docs.pathmx.dev/examples/code-highlight.demo.md) — This is a demo of the code highlight component.
- [A color in context](https://docs.pathmx.dev/examples/color-context.components.md) — A native checkbox changes the backgrounds of two identical color samples. The squares keep the same color, size, and position throughout. No JavaScript or...
- [Can you trust this color?](https://docs.pathmx.dev/examples/color-context.demo.md) — Make a prediction, remove the surroundings, and discover how one color can look like two.
- [Datatype diagrams](https://docs.pathmx.dev/examples/datatype.demo.md) — Datatype expressions stay readable in Markdown and render as inline charts (the Datatype plugin is part of the default plugin set):
- [Embed web content](https://docs.pathmx.dev/examples/embed.demo.md) — The same directive chooses a deliberate presentation for three kinds of public web destination.
- [Example cards](https://docs.pathmx.dev/examples/example.components.md) — The Examples collection uses one card for each working Source: a recognizable preview, a short invitation, and a way into both the experience and its Markdown.
- [Form controls](https://docs.pathmx.dev/examples/form-controls.demo.md) — Native HTML fields follow the site's theme. Labels, hints, and errors stay beside the field they describe. These examples are for trying the controls; they do...
- [One mountain, three points of view](https://docs.pathmx.dev/examples/images.demo.md) — Look closely at three Hokusai prints. A small lesson in composition, made with images, captions, and a gallery.
- [Math Demo](https://docs.pathmx.dev/examples/math.demo.md) — Temml renders $…$ and $$…$$ to native MathML. The samples below are the notation the discrete-math labs use.
- [An orbital playground](https://docs.pathmx.dev/examples/orbit/orbit.components.md) — Play the lesson. A local Three.js scene makes gravity visible; ordinary HTML controls make each experiment usable with a keyboard or touch.
- [Falling around the world](https://docs.pathmx.dev/examples/orbit/orbit.demo.md) — Launch a satellite, follow the forces, and discover what makes an orbit.
- [A Source's Journey Through PathMX](https://docs.pathmx.dev/examples/pathmx-source-journey.demo.md) — A worked, browser-readable tour from authored Markdown to a live, cacheable PathMX page.
- [Play presentation](https://docs.pathmx.dev/examples/play-deck.demo.md) — Presentation mode should give the active Block a deliberate stage rather than showing a tall document with snap points.
- [Play Layout Demo Components](https://docs.pathmx.dev/examples/play-layout.components.md)
- [Deckset-style Lecture Fixture](https://docs.pathmx.dev/examples/play-lecture.demo.md) — Programming is the process of writing instructions for computers to follow.
- [Play reading](https://docs.pathmx.dev/examples/play-reading.demo.md) — This example is deliberately longer than one viewport. It shows keyboard ownership after activating the link above, stable Beat placement, free scroll...
- [Document Play Prototype](https://docs.pathmx.dev/examples/play.demo.md) — Play turns an ordinary document into focused reading or a slide presentation without changing its built output.
- [Example artwork](https://docs.pathmx.dev/examples/previews/preview.components.md) — The homepage and Examples collection share these fragments. Their surrounding layout, introductions, and next actions stay on each page.
- [Links with useful context](https://docs.pathmx.dev/examples/references/index.demo.md) — Meet @link.person-badge Ada, then explore the project below. The name comes from this link; the avatar and biography live in Ada's Source.
- [Ada](https://docs.pathmx.dev/examples/references/ada.badge.md) — Ada helps teams make interfaces work with a keyboard.
- [Accessible interfaces](https://docs.pathmx.dev/examples/references/practice.project.md) — Explore keyboard navigation and readable labels.
- [Reference components](https://docs.pathmx.dev/examples/references/reference.components.md) — These components work with individual rich links and query results. Both supply the target's canonical source, navigable href, and visible label.
- [Scroll story components](https://docs.pathmx.dev/examples/scroll-story/story.components.md) — Read the story · More examples
- [One file. A world of possibility.](https://docs.pathmx.dev/examples/scroll-story/story.demo.md) — Start with an idea. Give it a place to grow. Then connect it to the next useful thing.
- [A sound button](https://docs.pathmx.dev/examples/sfx/sounds.components.md) — Each instance selects and triggers its own cue. The audio path resolves beside this component Source. This works in reading, Focus, and Slides.
- [Hear the moment](https://docs.pathmx.dev/examples/sfx/sounds.demo.md) — Advance to hear a short cue, then a low repeating tone. Return to reading at any time with Escape. Adjust sound in site Settings. Audio adds emphasis; all...
- [An independent Source inside a lesson](https://docs.pathmx.dev/examples/source-embed.demo.md) — An embed gives another Source its own page, styles, scrolling, and interactions. Use the note below, then follow its link. Navigation stays inside the example.
- [Opening Sources alongside a lesson](https://docs.pathmx.dev/examples/source-opening.demo.md) — Keep references beside a lesson, or open a book without leaving it.
- [Looking Slowly](https://docs.pathmx.dev/examples/source-opening/book.book.md) — A short example book about noticing everyday details.
- [Composition](https://docs.pathmx.dev/examples/source-opening/composition.page.md) — Trace the path your eye takes through a photograph. A face, a line, a patch of color, and an empty area can each change where you look next.
- [Light and shadow](https://docs.pathmx.dev/examples/source-opening/light.page.md) — Look for the brightest area of a photograph. Does it attract your eye because it is bright, or because it makes something else easier to see?
- [Find a photograph](https://docs.pathmx.dev/examples/source-opening/next.page.md) — Choose a photograph you know well. Spend a minute looking at it with your references open. Add something new to each note field.
- [Responsive tables](https://docs.pathmx.dev/examples/tables.demo.md) — PathMX tables scroll horizontally when their columns no longer fit. On narrow screens, the first column stays in view so each row keeps its context while the...
- [Submission checklist](https://docs.pathmx.dev/examples/task-1.task.md) — Use this checklist before turning in the project.
- [Task Lists](https://docs.pathmx.dev/examples/tasks.demo.md) — PathMX task lists stay flush with the document edge, preserve rich inline content, and indent only when tasks are nested.
- [Theme Gallery](https://docs.pathmx.dev/examples/theme-gallery.demo.md) — PathMX ships four built-in themes. A Source selects one with theme: in frontmatter, any URL can override it with ?theme= , and the Player's Theme select...
- [Bauhaus theme](https://docs.pathmx.dev/examples/themes/bauhaus.md)
- [Recursion, or how to think in smaller problems](https://docs.pathmx.dev/examples/themes/gauntlet.md) — A function that calls itself is not a trick. It is a way of describing a problem by what remains after you take one step.
- [Glass theme](https://docs.pathmx.dev/examples/themes/glass.md)
- [Paper theme](https://docs.pathmx.dev/examples/themes/paper.md)
- [Studio theme](https://docs.pathmx.dev/examples/themes/studio.md)
- [Synthwave theme](https://docs.pathmx.dev/examples/themes/synthwave.md)
- [Terminal theme](https://docs.pathmx.dev/examples/themes/terminal.md)
- [Watch the timing](https://docs.pathmx.dev/examples/video-focus.demo.md) — Notice how each movement begins, travels, and comes to rest.
- [Video](https://docs.pathmx.dev/examples/video.demo.md) — A video stays alongside the explanation it supports. Press Play to load it.
- [Releases](https://docs.pathmx.dev/releases/releases.changelog.md) — What's new in PathMX. All releases are currently beta.

- [XML sitemap](https://docs.pathmx.dev/sitemap.xml)