Your content folder

Pressmark does not ask you to move your work. It reads the folder where your articles already live and works out where the posts and their details are.

Three ways in#

• Point at my folder. For Markdown files, an Obsidian vault, a Git repo or a static-site folder. Pressmark detects the layout, shows a preview, and you confirm.
• Create a content folder. For a fresh start. Pressmark makes a folder with a README, templates, writing rules and instructions for your AI assistant (AGENTS.md and CLAUDE.md).
• Import from Substack. Writes one Markdown file per post from Substack's export or your public archive. This comes in a later version.

All three end on the Sources page with a confirmed mapping.

What detection looks for#

Detection runs on your Mac, offline, in seconds.

1. It looks for known layouts: a pressmark.yaml, an Obsidian vault, Jekyll, Hugo, Astro, Eleventy, a Substack export, a Ghost export or a Notion export.
2. If none fits, it looks at the files: one folder per post, or one file per post, and extra files repeated in every post folder (sidecars).
3. It matches your front matter keys to Pressmark fields such as title, subtitle, status and publish date.

Nothing is sent to a model to do this.

The mapping preview#

Before anything is saved you see how many posts were found, where each field comes from, which fields are missing, how your status words map, and any problems (missing titles, duplicate slugs, broken image paths). Change anything, then confirm. Below the preview is an opt-in checkbox, "Also save this mapping as pressmark.yaml in the folder". It is off by default. If the folder already has a pressmark.yaml, Pressmark never overwrites it and tells you so.

One file that cannot be read, or is over 2 MB, shows as a problem on that post. The rest are read as usual.

The manifest#

pressmark.yaml lives at the root of your folder. If it exists, Pressmark uses it and does not guess.

version: 1
publication: yourname.substack.com
layout: folder-per-post          # or file-per-post
posts: posts
post_file: post.md
assets: assets
fields:                          # front matter key: Pressmark field
  title: title
  subtitle: subtitle
  status: status
  publish_at: publish_at
statuses:
  idea: [idea]
  drafting: [draft, review]
  ready: [ready]
write_back: false

Sidecar files#

Some writers keep extra details in a second file beside each post. A sidecar names the file, a parser and the fields to read from it.

sidecars:
  - file: publish-sheet.md
    parser: labelled-blocks
    fields:
      "SEO title": seo_title
      "SEO description": seo_description
      "Tags": tags
  - file: STATE.md
    parser: key-value
    fields: { stage: status }

The labelled-blocks parser reads a bold label followed by a fenced block:

**SEO title**
```
How I plan a year of posts
```

The key-value parser reads plain key: value lines, one per line, such as stage: final in STATE.md. Other parsers are front-matter, yaml, json and headings.

Statuses#

statuses maps your own words to Pressmark's states. In the example, a post marked draft or review counts as drafting. Words that are not listed are flagged in the preview.

The quality gate#

If you have a script that decides whether a post is final, set it under quality_gate. Pressmark runs it only when you click Run gate on a post, never automatically, because some gates write files. The gate runs only on a confirmed source. Before it runs, the dialog shows the exact command in full, and if no gate is set it says so and offers no Run button. Exit code 0 means pass. Changed files are listed as paths from the content folder.

quality_gate:
  command: ["python3", "-I", "scripts/final_gate.py", "{post_folder}"]

Read-only#

Pressmark only reads your folder. Writing status back to your files is not built yet. The one thing it can write is the pressmark.yaml you ask for on confirm, and a gate you run yourself may change files in the post folder.

On the command line#

Two commands for writers who use a terminal:

• pressmark init <folder> creates a content folder with the templates.
• pressmark check <path> checks a post or folder: front matter, lengths, links, images and your writing rules. It works offline and needs no model.