OpenMarioMarkupLanguage

**OpenMarioMarkupLanguage（OML）**は、OpenMarioWikiで記事を執筆・公開するための文書仕様である。OML-1.0は、VitePressが解釈するMarkdownを基礎に、OpenMarioWiki固有のフロントマター、Wikiリンク、Obsidian互換画像埋め込み、百科事典向けHTML部品を定義する。

OMLは別のMarkdown処理系を新しく実装する名称ではない。VitePress Markdownを基礎文法とし、ここで定義する拡張と編集規則を加えた公開プロファイルである。したがって、OMLに準拠する記事は、リポジトリの docs/ をVitePressでビルドした結果と同じ表示になることを目標とする。

仕様の状態: OML-1.0 / OpenMarioWiki実装済み

対象: docs/articles/*.md と docs/index.md

文字コード: UTF-8

1. 文書モデル

OML文書は、次の順序で構成する。

1. YAMLフロントマター（記事のメタデータ）
2. Markdown本文
3. 必要に応じたWikiリンク、HTML表、記事用コンポーネント

ファイル名は記事の正規識別子になる。本文の最初の見出しや title と異なるファイル名を採用する場合は、リンクの解決に影響するため、既存記事との重複を確認する。

---
title: 記事のタイトル
date: 2026-07-24
tags:
  - 分類
categories:
  - カテゴリ
---

本文を書く。

2. フロントマター

フロントマターは、ファイル先頭の --- で囲んだYAMLブロックである。YAMLとして正しく解析できない値は、ビルド時にメタデータや記事一覧へ反映されない。

2.1 標準フィールド

フィールド	型	必須	意味
title	文字列	推奨	ページタイトル、記事一覧の表示名。省略時はVitePressの解決結果に従う。
date	YYYY-MM-DD または日時	任意	記事一覧の公開日時。記事一覧では新しい順に並ぶ。
tags	文字列配列	任意	検索・分類用のタグ。
categories	文字列配列	任意	記事下部に表示するカテゴリ。
layout	文字列	任意	VitePressまたはOpenMarioWikiテーマのレイアウト指定。
sidebar	真偽値または文字列	任意	テーマ側のサイドバー表示制御。
version	文字列	任意	仕様書など、記事固有の版番号。サイトの公開版とは別である。

日付だけを示す場合は、タイムゾーンをまたぐ曖昧さを避けるため YYYY-MM-DD を使う。タグ名・カテゴリ名は日本語を使用できるが、同じ概念に複数の表記を作らない。

2.2 メタデータの原則

• 記事の主題を title に入れ、本文のタイトルと一致させる。
• 年記事には 年別記事、年表、星環暦 を付ける。
• 既存の分類を変更する場合は、関連する索引記事も更新する。
• 本文に表示したい説明をフロントマターへ詰め込まず、本文に書く。

3. 基本文法

OMLの基本文法は、VitePressが提供するMarkdown（CommonMark系の段落・強調・リスト・引用・コードフェンス・表）に従う。

3.1 見出し・段落・強調

ATX見出しを使用する。ページの主見出しはテーマが表示するため、通常の記事本文では ## から始める。見出しは内容の階層を表し、装飾目的で飛ばさない。

## 概要

通常の段落。**重要な語**、*補助的な強調*、`短いコード` が使える。

### できごと

3.2 リスト・引用・コード

順序なしリスト、番号付きリスト、チェックリスト、引用、フェンス付きコードブロックを使用できる。コード中の文字列はWikiリンクとして解釈させない。

- 関連資料を読む
- 出典を照合する

1. 記録する
2. 保留する
3. 引き継ぐ

> 出典にない情報を推測で補わない。

```ts
const articleKey = 'articles/星環885年.md'

チェックリストは執筆メモや計画記事に限り使用する。公開済みの歴史記述を、未完了タスクのように表現する目的では使わない。

### 3.3 表

パイプ表を使用できる。先頭行の区切りと列数を揃え、セル内のパイプは `\|` でエスケープする。

```markdown
| 年 | 出来事 | 関連世界 |
| --- | --- | --- |
| 星環885年 | 記録継承式 | 統合史 |

大きな表には、列の意味を明記し、日付が不明な場合は 不詳 と書く。推測で月日を補完しない。

4. OpenMarioWiki拡張

4.1 Wikiリンク

OMLのWikiリンクは、ページ名を二重角括弧で囲む。

記法	意味
[[星環暦]]	ファイル名または記事タイトルが「星環暦」の記事へリンクする。
[[星環暦|星環暦の解説]]	リンク先は「星環暦」、表示文字列は「星環暦の解説」。
[[星環暦#星環暦の意義]]	ページ内見出しへリンクする。アンカーは小文字化・空白のハイフン化を行う。
[[ページ名|表示|にパイプ]]	最初の区切りをリンク先とし、残りを表示文字列として扱う。通常はパイプを一つにする。

OML実装は、まずファイル名・title の完全一致を探し、見つからなければアンダースコア区切りの末尾一致、部分一致の順で解決する。解決できないリンクも入力時点ではエラーにせず、/articles/ページ名 へのフォールバックを生成する（cleanUrls 有効のため拡張子は付けない）。公開前にリンク切れを確認すること。

表のセルなど、通常のMarkdownがパイプを先に処理する場所では \| を使う。

4.2 Obsidian互換画像埋め込み

画像は、docs/public/images/ に置いたファイルを次の記法で埋め込める。

![[logo.png]]

これは /images/logo.png の画像として出力され、代替テキストにはファイル名が入る。ファイル名に秘密情報や利用許諾のない素材を含めない。通常のMarkdown画像も使用できるが、サイト内画像は埋め込み記法を優先する。

4.3 HTML部品

VitePressのHTML許可を利用し、百科事典に必要な表やナビゲーションを記述できる。現在の標準クラスは次のとおり。

クラス	用途
infobox	記事の要点を示す右寄せ情報表。見出しセルには scope="row" を付ける。
wikitable	本文の比較・一覧表。
year-infobox	星環年記事の年・前年・翌年を示す情報表。
year-navbox	年記事間の前後移動。role="navigation" と aria-label を付ける。

<table class="infobox" aria-label="記事の基本情報">
  <tbody>
    <tr><th scope="row">分類</th><td>統合史</td></tr>
  </tbody>
</table>

HTMLを使う場合も、キーボード操作・スクリーンリーダー・モバイル幅を損なわない。装飾だけの <div> を増やさず、意味のあるMarkdownを先に検討する。script、iframe、外部広告など、記事本文から任意コードを実行する記述はOMLの対象外とする。

5. リンク・資産・ファイル名

• サイト内記事はWikiリンクを優先する。
• 外部リンクは通常のMarkdownリンク [表示](https://example.com) を使い、リンク先の目的を表示文字列から分かるようにする。
• 画像・音声などの公開資産は docs/public/ 以下へ置く。
• 記事ファイルは docs/articles/ 直下の .md とする。
• ファイル名には、既存記事と区別できる日本語または英数字を使用する。タイトルだけを変更する場合も、リンクの解決対象となるファイル名を確認する。
• 他記事への相対ファイルパスを直接埋め込まず、Wikiリンクで解決させる。

記事評価APIが扱う記事キーは articles/ファイル名.md である。これは公開記事ファイルに実在するキーだけが受け付けられ、.. などのパス移動は許可されない。

6. 記述上の編集規則

OMLは構文だけでなく、OpenMarioWikiで読める記事にするための編集規則を含む。

1. 出典と解釈を分ける。 年表の事実、作品内の設定、後世の評価を同じ文で断定しない。
2. 不詳を消さない。 日付・人物・場所が確認できない場合は 不詳、未詳、保留 を使い、推測で埋めない。
3. 年記事を孤立させない。 概要、できごと、影響、史料と論点、前後の年、関連項目を必要に応じて設ける。
4. 地域差を残す。 翻訳、通称、地域暦などに差がある場合、正規化して一つに潰さず、出典とともに併記する。
5. リンクを入口にする。 関連項目は記事の終点ではなく、個別資料へ戻る導線として設計する。
6. 更新時に索引も確認する。 年記事を追加・改稿したら、星環年別記事一覧、グローバル年表、必要なら 星環暦 を更新する。

7. 適合性

OML-1.0の適合記事は、次を満たす。

• UTF-8で保存され、必要なフロントマターがYAMLとして解析できる。
• VitePressビルドが成功する。
• Wikiリンクのページ名と表示文字列を正しく分けている。
• 表内のパイプ、コード、HTML属性を適切にエスケープしている。
• 画像・外部リンク・HTML部品が公開環境で安全に解決できる。
• 主張の粒度と不確実性が、本文および「史料と論点」に反映されている。

OMLの更新では、互換性を壊す変更をマイナーバージョンへ混ぜない。新しい記法は、既存記事を壊さないこと、VitePressビルドで検証できること、アクセシビリティ上の代替手段があることを確認してから追加する。

8. 実装対応表

OML機能	OpenMarioWikiでの実装
YAMLフロントマター	VitePressが解析し、テーマと記事一覧が利用する。
Wikiリンク	docs/.vitepress/config.mts のリンク解決プラグインが処理する。
画像埋め込み	markdown-it-regexp による ![[...]] 拡張が処理する。
HTML表・ナビゲーション	VitePress MarkdownのHTML出力とテーマCSSが処理する。
記事評価	ArticleRating.vue と server/ratings-server.mjs が5段階評価と集計を提供する。
個人メモ	ArticleNotes.vue がブラウザの localStorage に保存する。

関連項目

• サイト内ナビゲーション
• 星環年別記事一覧
• 星環暦
• 全創作物統合マスター
• VitePress公式ドキュメント