日本語版: README.ja.md
fmfm is a file format and a toolchain for hiking (and similar outdoor) logs that live on your own site. A log is an ordinary Markdown file — readable in any renderer — with two small, optional layers of structure: YAML front matter for the whole hike, and ::: directives for the places in the story that matter to other hikers: waypoints, hazards, trail conditions.
---
format: fmfm
format_version: "0.1"
title: Kumotori-yama traverse from Mitsumine
started_at: 2026-07-10T06:20:00+09:00
ended_at: 2026-07-10T17:40:00+09:00
track:
url: ./track.gpx
stats:
distance_m: 21300
ascent_m: 1780
tags: [okutama, kumotori]
---
# Kumotori-yama traverse
Left the Mitsumine shrine at 06:20 …
:::hazard{severity="warning" latitude="35.87" longitude="138.94"}
A fallen tree blocks the trail just below Shiraiwa hut. Pass on the right.
:::The canonical copy stays with the author. Tools validate it, turn it into JSON for indexers and map services, and render it to semantic HTML. There is no central service and no lock-in: GPX tracks are referenced, not embedded, and anything a tool does not understand is preserved.
Status: pre-release (v0.1 in progress). The format is a draft and may still change incompatibly before 1.0.
Hiking records in Japan tend to end up in a few centralised apps. This project takes the opposite stance: write the log once, in Markdown, on your blog or in a git repository, and let any number of services read it. The design goals, in order:
- The file must read as normal Markdown without any tooling.
- Only the parts worth structuring are structured, and with the smallest possible syntax.
- Existing open formats do the heavy lifting: CommonMark, YAML, GPX (later GeoJSON, Atom/GeoRSS, OSM and Wikidata identifiers).
- Every consumer works from one typed model, not from HTML.
- docs/spec/format.md — the normative draft (front matter fields, directive grammar,
waypoint/hazard/trail-condition, data types, diagnostics, JSON and HTML export contracts). - docs/spec/format.ja.md — 日本語訳.
- Design rationale: docs/knowledge/adr/; undecided points: docs/knowledge/architecture/open-questions.md.
The reference implementation is written in MoonBit (module hanamizuno/fmfm). It is a library first and a CLI second, and it never converts Markdown straight to HTML:
source → syntax (front matter + directives) → semantic (typed Document + diagnostics)
→ exporters: JSON · HTML · (GeoJSON, feeds … later)
Packages: diagnostic, syntax, frontmatter, ast, semantic, json, html, and the root facade. See docs/knowledge/architecture/pipeline-and-packages.md.
fmfm validate hike.md # diagnostics as file:line:col: level[code]: message; exit 1 on errors
fmfm render hike.md -o hike.html # semantic HTML with the default stylesheet
fmfm export hike.md --format json
fmfm dump hike.md # full AST with positions and diagnostics (debugging)| Area | State |
|---|---|
| Directive scanner, attribute grammar, front matter split | done, snapshot-tested |
| Typed AST, RFC 3339 date-times, number lexing | done |
| Semantic validation (all diagnostic codes in the spec) | done |
| JSON export / dump | done |
HTML renderer (semantic sections, data-*, escaping) |
done; takes any Markdown→HTML function |
CommonMark rendering via moonbit-community/cmark |
adapter pending (dependency not yet fetched) |
YAML front matter via moonbit-community/yaml |
reader pending (dependency not yet fetched) |
CLI, default CSS, examples/ golden tests |
pending |
| GPX validation, GeoJSON, feeds | after v0.1 |
Install the MoonBit toolchain and just, then:
moon update # registry index, once
just # check + test (js target)
just ci-all # formatting, generated interfaces, js + native tests — same as CIOther recipes: just fmt, just test-update (refresh snapshots), just info (regenerate pkg.generated.mbti), just target=native test. Contributor guidelines for humans and AI agents are in AGENTS.md.
Docker and Docker Sandboxes (sbx) set-ups are inherited from the project template; see .sandbox/README.md and the runbook.
Issues and pull requests are welcome, in English or Japanese. The format itself is the main thing under discussion right now: if you keep hiking logs and something in the spec does not fit how you write them, say so in an issue.
MIT — see LICENSE. The specification text is under the same license; logs you write with it are, of course, yours.