Hyday Markdown

Hyday Markdown Skill

First time in this conversation? Run Step 0 from hyday-vault-layout to find the vault root. This skill assumes you already know where the user's Hyday folder lives on disk. Resolve it from ~/Library/Application Support/Hyday/settings.json (macOS) or %APPDATA%\Hyday\settings.json (Windows) — journalPath field. Don't guess, don't write to ~/Documents/Hyday, and don't ask the user unless the config file lookup fails.

Hyday stores every note as a plain .md file on disk. The app picks up changes automatically — write the file, and the note appears in Hyday next time it scans. This skill covers Hyday's extensions on top of standard Markdown.

Assumed knowledge: CommonMark + GFM (headings, lists, tables, code blocks, task lists - [ ]). Only Hyday-specific syntax is documented here.

Workflow: Creating a Hyday Note

1. Survey existing tags and entities first (once per conversation, cache the result). Grep $VAULT_ROOT for the user's existing #tag and @(entity) set so you can reuse them instead of inventing new ones. See "Reuse existing tags and entities" below for the grep commands and the matching rules.
2. Pick the right file name. Notes use any descriptive filename ending in .md. Avoid names that look like a date (YYYY-MM-DD.md, YYYY.MM.DD.md) unless the file is meant to be a [[journal entry]] — Hyday auto-detects those as the journal type. See hyday-vault-layout for where the file goes.
3. Write frontmatter at the top of the file using YAML between --- fences. Required fields: title / type / createdAt / lastModified. Always double-quote string values; use YAML list form (- "tag" per line) for tags, never inline [a, b].
4. Pick a type from article | card | img | link | video. Default is article if omitted. Journal files do not use type — Hyday infers journal from the filename. Do NOT write note, text, or any value outside the five.
5. Write the body in Markdown. Add #tag, @(Label), and [[note-id]] inline as needed — using the existing set surveyed in step 1.
6. Save the file. Hyday reindexes within a few seconds.

Frontmatter

---
title: "Reading notes — Atomic Habits"
type: "article"
createdAt: "2026-05-17 09:30:00"
lastModified: "2026-05-17 09:30:00"
tags:
  - "books"
  - "habits"
pinned: true
---

Always write createdAt and lastModified. Use the current real-world time when the agent creates the note. On a brand-new note both fields hold the same value; on edits, bump only lastModified. Skipping them means Hyday has no reliable creation time for sorting / display and the note will look orphaned in the timeline.

Supported fields

Quoting rules

• Always wrap string values in double quotes — Hyday's frontmatter parser is conservative and unquoted values with :, #, -, or other YAML-special characters will break.
• Escape " inside strings as \". Example: title: "She said \"hello\"".
• Tag list items use the dashed form, each quoted: - "books".

Note types — when to use which

Inline Tags

#reading                 Single tag
#books/non-fiction       Nested tag (slash creates hierarchy)
#project-alpha           Hyphens and letters allowed

Rules:

• Must start with a letter (not a digit) after #.
• Can contain letters, digits, _, -, /.
• Tags inside fenced code blocks (```) or inline code (`) are not parsed — useful when documenting #hex colors or shell prompts.
• Tags can also be set in frontmatter (tags: list). The displayed tag set is the union of both.

Inline Entities

Entities are people, places, projects — anything you want to track separately from a free-form tag. They render as a styled chip.

Met with @(Aaron) about the launch.
Project @(Alpha Launch) is on track.

Syntax: @(Label) — parentheses, label can contain spaces and most characters except ).

Legacy syntax: @{Label} is still accepted and will be migrated to @(Label) on next save. Always write new content in the parenthesis form.

Boundary rule: @(...) must follow whitespace, CJK punctuation, or be at the start of a line. email@(domain) won't be parsed as an entity because email is right next to @.

Reuse existing tags and entities — don't invent new ones casually

Before adding #tag or @(entity) to a new note, survey what the user already uses and prefer those. Inventing #book-notes when the user already uses #books fragments the tag system and makes the notes harder to find later.

Workflow when creating any new note

1. Survey before writing. Grep the vault root for existing tags and entities once at the start of the conversation (cache the result for follow-up notes in the same session — don't re-grep on every note).

2. Match by intent. For each tag / entity you'd want to add to this note, scan the existing list:

   • Exact match → use it
   • Close match (singular vs plural, synonym, variation) → use the existing one, even if your candidate sounds slightly better
   • No reasonable match → only then create a new one

3. When unsure, ask. If the user's content could fit two existing tags, briefly ask: "你習慣用 #books 還是 #reading-notes?" — better than guessing and creating a third.

Grep commands

These are cheap (a few hundred tokens of metadata, much less than reading note contents):

# Frontmatter tags — each "- value" line under a `tags:` block in any .md
grep -rh '^  - "' "$VAULT_ROOT"/*.md "$VAULT_ROOT"/**/*.md 2>/dev/null | sort -u

# Inline tags — every #tag occurrence across all notes
grep -rho '#[a-zA-Z一-鿿][a-zA-Z0-9_一-鿿/-]*' "$VAULT_ROOT" 2>/dev/null | sort -u

# Existing entities — every @(Label) across all notes
grep -rho '@([^)]\+)' "$VAULT_ROOT" 2>/dev/null | sort -u

Replace $VAULT_ROOT with the path you resolved in Step 0 (hyday-vault-layout).

Cost estimate

For a vault of 500 notes the entire tag + entity inventory is typically under 2 KB (800 tokens) — negligible compared to reading any single note's content. Do this once per conversation, not per note.

Don't

• Don't add #tag for every keyword in the body. Tags are for the user's manual organization system, not for keyword indexing. 2-4 tags per note is typical.
• Don't create @(...) for one-off mentions of public figures or companies the user has never tracked before. Entities are for recurring people / projects / places.
• Don't translate existing tags (#讀書 and #books are different — pick whichever the user already uses, don't auto-normalize).

Backlinks (Wikilinks)

[[2026-05-17]]                      Link to a journal entry by date
[[Reading notes — Atomic Habits]]   Link to a note by title or id
[[note-id|Display Text]]            Custom display text

How they resolve:

• Hyday matches against note title first, then filename (without .md).
• For journal entries, use the date in YYYY-MM-DD form.
• If multiple notes match, the most recently modified wins — disambiguate by using a more specific title.

No heading or block anchors — unlike Obsidian, Hyday does not support [[Note#Heading]] or [[Note#^block-id]].

Standard Markdown — Hyday-supported features

Hyday's editor (Plate.js) supports:

• GFM: tables, task lists (- [ ]), strikethrough, fenced code blocks
• Math: inline $e^{i\pi}+1=0$ and block $$ ... $$
• Mermaid diagrams: ```mermaid fenced blocks
• Callouts (same syntax as Obsidian/GitHub):

> [!note]
> Basic callout.

> [!warning] Custom title
> Callout body.

> [!tip]- Collapsed callout
> Click to expand.

Common callout types: note, tip, warning, info, important, caution, success, failure, question, example, quote, todo.

Code blocks

Fenced code blocks render with syntax highlighting:

```typescript
const greeting = "hello";
```

#tags, @(entities), and life log marks inside code blocks are not parsed — code stays literal.

Complete Example

---
title: "Atomic Habits — Chapter 3 notes"
type: "article"
tags:
  - "books"
  - "habits"
pinned: false
---

# Atomic Habits — Chapter 3

Reading session on 2026-05-17 with @(Aaron). Tracked under #books/non-fiction.

## Key idea

Identity-based habits > outcome-based habits. See [[Reading notes — Atomic Habits]] for the full overview.

> [!tip] Quote
> "You do not rise to the level of your goals. You fall to the level of your systems."

## Open questions

- [ ] How does this apply to writing routines?
- [ ] Compare with [[Deep Work]] approach.

## Diagram

```mermaid
graph LR
    Cue --> Craving --> Response --> Reward

## Validation checklist

After writing or editing a `.md` file, verify:

1. Frontmatter is wrapped in `---` fences with valid YAML inside.
2. All string values are double-quoted.
3. **`title` is set** (don't rely on filename — Hyday displays this).
4. **`type` is set** to one of: `article`, `card`, `img`, `link`, `video`. Do **not** set `type: "journal"`, `note`, `text` — let the filename do it for journals, and use one of the five enum values for everything else.
5. **`createdAt` AND `lastModified` are both set** in `YYYY-MM-DD HH:mm:ss` 24-hour format. On a new note they should be equal. Skipping them means the note has no reliable timestamp and looks orphaned in Hyday's UI.
6. Tags follow the rules (start with a letter after `#`, no spaces).
7. Entities use `@(Label)` form; convert any legacy `@{Label}` if you spot them.
8. Backlinks reference notes that exist (or that the user intends to create).
9. Filenames for journal entries match `YYYY-MM-DD.md` or `YYYY.MM.DD.md`; everything else is a regular note.

## References

- Hyday vault layout: see `hyday-vault-layout` skill
- Journal-specific syntax: see `hyday-lifelog` skill
- Whiteboard cards: see `hyday-whiteboard` skill