[@layout]: ./docs.layout.md

# The PathMX methodology

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 files into meaningful paths.

The method works with a folder, a text editor, and ordinary file tools. The
PathMX framework builds on those conventions to publish interactive sites.

---

## 1. Markdown-first

Keep the authored content in readable Markdown files. Use headings, paragraphs,
lists, code, and links to express the material directly. Add metadata when it
helps describe or organize the content.

Keep the files in version control so authors can review changes, compare
versions, and recover earlier work. People and agents work on the same source.

Within a page, group related explanations and activities into meaningful
[Blocks](./authoring/blocks.reference.md).

---

## 2. Explicit file types

Name a file for both its subject and its role. A directory listing should help
readers decide what to open before they read the contents.

```text
workshop/
├── index.md
├── color.lesson.md
├── contrast.lab.md
└── contrast.rubric.md
```

Here, `lesson`, `lab`, and `rubric` describe roles in a workshop. Another project
might use `session`, `speaker`, and `venue`. Choose a vocabulary that fits the
domain and use it consistently.

The framework reads the last dotted segment before `.md` as the
[Source type](./authoring/sources.reference.md). A filename such as `index.md`
uses the default page type.

---

## 3. Hyperlinked paths

Link related documents where the relationship matters. Links let readers follow
a sequence, find background, or choose a different route through the material.
They also give an agent context for the document it is editing.

For example, `color.lesson.md` can end with:

```md
Practice with the [contrast lab](./contrast.lab.md).
Use the [rubric](./contrast.rubric.md) to check your work.
```

A workshop overview can link these same files in a recommended order. An
experienced reader can go straight to the lab. The links support several paths
through shared material.

Use descriptive link text and relative paths to exact files. See
[Links](./authoring/links.reference.md) for the framework's link syntax.

---

## Put the method to work

Start with a small set of files that expresses the purpose of the project.
Write down its goals, conventions, and a useful example. As the collection grows,
keep related context connected through links.

When working with an agent, point it to those goals and examples, ask for a
specific change, and review the result in the source. In a course, that could
mean adapting a lab to a learner's interests while preserving its outcomes and
rubric. The author guides the work and decides what to publish.

This approach was pioneered by [Mark Johnson](https://x.com/wmdmark) through
his classroom teaching at Furman University. Read more about its classroom
use in [Toward True Differentiated Instruction with PathMX and Curriculum as
Code](https://dl.acm.org/doi/10.5555/3820586.3820601), coauthored with Chris Alvin.

[Read the PDF](https://pathmx.dev/files/pathmx-paper.pdf).

---

## Build with the framework

The framework turns these files into pages, indexes their types and links, and
adds capabilities through Plugins. Blocks organize a page; Player offers Focus
and Slides; components add reusable interfaces. These tools work with the same
authored files.

- [Create a first site](./start/first-site.guide.md).
- [Learn the authoring conventions](./authoring/index.md).
- [Work with agents](./agents/index.md).