Markdown bookmark format

Shiori stores Markdown bookmarks as plain text files in a folder you choose. You can read and edit them in any text editor. Shiori picks up changes automatically.

Files

Bookmarks are grouped by the year they were saved: 2026.md.
After 200 bookmarks or 1 MB, Shiori starts a new part: 2026-part-02.md, 2026-part-03.md, and so on.
Don’t rename these files. Other files in the folder are ignored.
Shiori keeps the previous versions of files it changes in the hidden .shiori-recovery folder.

Each file starts with this header. Only shiori_format_version: 1 is required; the title is optional.

---
shiori_format_version: 1
---
# Bookmarks

Bookmarks

Each bookmark is a level-two heading linking to the page, followed by a metadata block and optional notes:

## [A useful article](<https://example.com/article>)

```yaml shiori
tags: ["reading", "software"]
created: "2026-09-27T00:30:00Z"
private: true
read_later: false
```

Notes about the article. Any Markdown works here.

### Follow-up

- Try the example.

The heading’s link text is the title, and its link is the URL. Each URL can appear only once in the folder.

Metadata

Field	Meaning
`tags`	List of tags. Tags can contain spaces.
`created`	Required. When the bookmark was saved, as an ISO 8601 date and time with a time zone.
`updated`	Optional. When Shiori last changed the bookmark.
`private`	`true` or `false`. If missing, the bookmark is private.
`read_later`	`true` or `false`. If missing, `false`.

Shiori keeps any other fields you add.

Notes

Everything after the metadata block, up to the next bookmark, is the bookmark’s notes. A line starting with ## always begins a new bookmark, so use ### or deeper for headings in notes. To keep a line that starts with ## in notes, put a backslash in front of it. Shiori does this automatically.

Problems

If a bookmark can’t be read, or the same URL appears twice, Shiori leaves it out of search. The source shows Needs attention in Preferences → Sources; click it for details. Fix the file in a text editor and Shiori reloads it.