【参考】このブログで使える投稿記事の記法・仕様

このブログの記事で利用できるMarkdown・MDXの記法と，記事ごとの設定項目をまとめました。もともと自分用のページとして非公開にしておりましたが，基本的な文章の装飾から，画像，外部コンテンツの埋め込み，コールアウト，商品カードまで，記事を追加・更新するときのリファレンスとして随時更新・公開していく予定です。

本記事は一般的なMarkdown・MDXのすべてを解説するものではなく，このブログの現在の実装に沿った仕様を扱っています。

記事ファイルの基本
最小構成
フロントマター
見出し
基本的な本文記法
画像
- 最適化する画像
- 最適化しない画像
リンク
商品カード
外部コンテンツの埋め込み
- 単独URLによる自動埋め込み
- コンポーネントによる埋め込み
コードブロック
- ファイル名
- 行・単語・差分の強調
コールアウト
引用
- 通常の引用
- 引用元
脚注
記事ページで自動的に表示されるもの

記事ファイルの基本

このブログの記事は，src/data/blog/に置いたMarkdown（.md）またはMDX（.mdx）ファイルとして作成する。通常の記事では，画像の最適化や外部コンテンツの埋め込みを利用できるMDXを推奨する。

記事タイトルのh1はフロントマターのtitleから自動で表示されるため，本文の見出しは##（h2）から始める。

## 目次という見出しを置くと，この位置にh2とh3から構成される目次が自動挿入される。

これとは別に，PC表示では画面左端にホバー式のサイド目次が自動表示される。サイド目次もh2とh3が対象で，現在読んでいるセクションが強調される。スマートフォンなどの小さい画面では表示されない。

最小構成

新しい記事は，次の形から始める。

---
pubDatetime: 2026-08-12T03:00:00Z
title: 記事のタイトル
tags:
  - Blogging
description: 記事一覧や検索結果に表示する記事の説明
---
## 最初の見出し

ここから本文を書く。example-article.mdx

フロントマター

フロントマターはファイルの先頭で---に挟んで記述する。

---
author: OKUYAMA Leo
pubDatetime: 2026-08-12T03:00:00Z
modDatetime: 2026-08-15T06:30:00Z
title: 投稿記事の例
featured: false
draft: false
tags:
  - Blogging
  - Astro
description: このブログの記事機能を紹介するサンプル記事
thumbnailImage: ../../assets/images/HERO_create-blog.jpg
titleColor: black
heroDim: 0.4
ogImage: ../../assets/images/article-specification.jpg
canonicalURL: https://okuyamaleo.com/posts/example-article/
hideEditPost: false
timezone: Asia/Tokyo
---example-article.mdx

Property	説明	必須・既定値
`title`	記事タイトル。記事ページの`h1`，一覧，OGPなどに使われる	必須
`description`	記事の説明。記事一覧，メタディスクリプション，OGPなどに使われる	必須
`pubDatetime`	公開日時。ISO 8601形式で指定する	必須
`modDatetime`	更新日時。記事を更新した場合だけ指定する	任意
`author`	SEOメタデータ上の著者名	`SITE.author`
`featured`	`true`の場合，トップページの注目記事欄にも表示する	`false`相当
`draft`	`true`の場合，記事ページを生成しない	`false`相当
`tags`	記事に関連するタグ。複数指定できる	`others`
`thumbnailImage`	記事上部のヒーロー画像，一覧サムネイル，自動生成OG画像の素材	任意
`titleColor`	ヒーロー上の文字色。`white`または`black`	`white`
`heroDim`	ヒーロー画像に重ねるスクリムの不透明度。`0`〜`1`	`0.4`
`ogImage`	自動生成画像を使わず，任意のOG画像を使用する場合に指定	任意
`canonicalURL`	記事の正規URL。別媒体にも同じ記事がある場合などに指定する	現在の記事URL
`hideEditPost`	記事の編集リンクを非表示にする	`false`相当
`timezone`	日付表示に使うIANAタイムゾーン	`SITE.timezone`

URL（スラッグ）

記事URLはファイル名から自動生成される。例えば，src/data/blog/my-first-post.mdxのURLは/posts/my-first-post/になる。

現在の実装ではフロントマターのslugには対応していない。URLを変更したい場合はファイル名を変更する。ファイル名には半角英数字とハイフンを使用する。

公開日時と更新日時

日時はISO 8601形式で指定する。ZはUTCを意味する。

2026-08-12T03:00:00Zは，日本時間の2026年8月12日12:00
日本時間を直接表す場合は2026-08-12T12:00:00+09:00とも書ける
modDatetimeがpubDatetimeより新しい場合，記事上では公開日ではなく更新日とUpdated:が表示される
timezoneを省略した場合，サイト既定のAsia/Tokyoで表示される

予約日時を未来にした記事は，一覧・RSS・関連記事などから公開時刻の15分前まで除外される。ただし，draft: falseの記事ページ自体はビルド時に生成されるため，URLを知っていれば公開時刻前でも直接アクセスできる。時刻まで厳密に非公開にしたい記事は，公開するデプロイまでdraft: trueにする。

下書きと注目記事

draft: true：記事ページを生成せず，一覧・検索・RSSなどにも掲載しない
draft: falseまたは省略：公開対象にする
featured: true：通常の記事一覧に加えて，トップページの注目記事欄にも掲載する
featured: falseまたは省略：通常の記事一覧だけに掲載する

ヒーロー画像

thumbnailImageを指定すると，記事冒頭に画像を画面幅いっぱいに表示し，その上へタイトル，タグ，日付，読了時間を重ねる。指定しない場合は，画像のない通常のタイトル表示になる。

thumbnailImage: ../../assets/images/Hero_article-specification.jpg
titleColor: black
heroDim: 0.4

thumbnailImageには記事ファイルから見たローカル画像の相対パスを指定する
横長画像を推奨するが，異なる比率でもobject-coverでトリミングされる
titleColor: whiteは暗い画像，titleColor: blackは明るい画像に向いている
heroDimを大きくすると画像上の文字を読みやすくできる
titleColorとheroDimは，ヘッダーと自動生成OG画像にも反映される

OG画像

ogImageを省略すると，記事ごとの1200×630ピクセルのOG画像がビルド時に自動生成される。

thumbnailImageがある場合：画像を1200×630に切り抜き，タグ・タイトル・日付を重ねる
thumbnailImageがない場合：テキスト中心のOG画像を生成する
ogImageがある場合：指定した画像を優先し，自動生成しない

ローカル画像とリモートURLのどちらもogImageに指定できる。

# ローカル画像
ogImage: ../../assets/images/Hero_article-specification.jpg

# またはリモート画像
ogImage: https://example.com/images/og-image.jpg

canonicalURLと編集リンク

同じ内容の記事を別媒体にも掲載している場合は，検索エンジンに正規ページを伝えるためcanonicalURLを指定する。

canonicalURL: https://okuyamaleo.com/posts/example-article/

hideEditPostは記事ごとに編集リンクを隠す項目だが，現在はサイト全体で編集リンクが無効になっているため，指定しても表示は変わらない。

見出し

記事タイトルは自動でh1になるため，本文ではh2から使う。

## 大見出し

### 中見出し

#### 小見出し

##### より小さい見出し

###### 最小の見出し

h2〜h6にはURLで直接参照できるアンカーが自動的に付き，PCでは見出しへマウスを重ねると#リンクが表示される。インライン目次とサイド目次に表示されるのはh2とh3だけである。

基本的な本文記法

文字装飾

**太字**

_斜体_

~~取り消し線~~

文章中の`インラインコード`

<u>下線</u>

キーボードの<kbd>Command</kbd> + <kbd>C</kbd>

注記<sup>*</sup>

太字はこのように，斜体はこのように，取り消し線は~~このように~~表示される。MDXでは<u>，<kbd>，<sup>などのHTML要素も記述できる。

箇条書きと番号付きリスト

- 1階層目
  - 2階層目
    - 3階層目

1. 最初の手順
2. 次の手順
3. 最後の手順

1階層目
- 2階層目
  - 3階層目

最初の手順
次の手順
最後の手順

表

| 項目 | 内容       |
| ---- | ---------- |
| 形式 | MDX        |
| 画像 | 最適化対応 |

項目	内容
形式	MDX
画像	最適化対応

水平線

---を単独の行に置くと区切り線になる。

本文の前半

---

本文の後半

画像

最適化する画像

src/assets/images/に画像を置き，@/assets/images/から参照する。Astroが画像を最適化し，レスポンシブ画像として出力する。

![木製テーブルの上にMacBookが載っている画像](@/assets/images/Hero_article-specification.jpg)

Markdown画像ではAltテキストがアクセシビリティ用の代替テキストとして使われると同時に，画像下のキャプションにも表示される。

記事本文のMarkdown画像は，クリックまたはタップするとモーダルで拡大表示される。拡大表示は閉じるボタン，モーダルの背景部分，またはEscキーで終了できる。既存の画像記法に追加の指定は必要ない。

最適化しない画像

最適化しない画像はpublic/に置き，URLではpublicを含めずルートから指定する。

ファイル：public/assets/images/example.jpg
記法　　：![説明](/assets/images/example.jpg)

リモート画像も通常のMarkdown画像として表示できるが，サイト側では最適化されない。

![説明](https://example.com/images/example.jpg)

リンク

リンク先にはhttps://を含む完全なURLを指定する。

[Googleを開く](https://www.google.com/?hl=ja)

Googleを開く

リンクテキストを付けずにURLだけを書くと，対応しているサービスでは埋め込みへ自動変換される。通常のテキストリンクとして確実に表示したい場合は，[リンクテキスト](URL)の形を使う。

Apple apple.com

革新に満ちたAppleの世界へようこそ。AppleのウェブサイトではiPhoneからiPad、Apple Watch、Mac、Apple TVまで、すべての製品の購入ができます。アクセサリやエンターテインメントを探す時も、専任スペシャリストによるデバイスのサポートが必要な時もこのサイトでどうぞ。

商品カード

ガジェットや日用品の紹介では，メーカー，商品名，型番，購入情報，公式サイトなどをProductCardにまとめて表示できる。brandとnameだけが必須で，それ以外は商品ごとに省略できる。

import ProductCard from "@/components/ProductCard.astro";
import productImage from "@/assets/images/product.jpg";

<ProductCard
  brand="SONY"
  name="WF-1000XM6"
  model="WF-1000XM6/SZ"
  variant="プラチナシルバー"
  price="44,550円"
  retailer="Sony Store"
  officialUrl="https://www.sony.jp/headphone/products/WF-1000XM6/"
  fallbackImage={productImage}
  purchaseLinks={[
    { label: "Amazonで見る", href: "https://amzn.asia/d/example" },
  ]}
  features={[
    "8.4mmドライバーユニット",
    "最大8時間再生（ノイズキャンセリング使用時）",
  ]}
/>

Property	説明	必須・既定値
`brand`	メーカーまたはブランド名	必須
`name`	商品名	必須
`model`	型番	任意
`variant`	色，容量，サイズなどの仕様	任意
`price`	実際の購入価格	任意
`priceLabel`	価格欄の見出し。比較記事などで「直販価格」に変える場合に使用	`購入価格`
`retailer`	購入先	任意
`officialUrl`	公式商品サイト。公式サイトボタンとOGP画像の取得元になる	任意
`ogImage`	自動取得できない場合に，公式サイトのOGP画像URLを直接指定	任意
`purchaseLinks`	Amazonなど購入先へのリンク。`label`と`href`の配列で指定	`[]`
`features`	カード内に表示する主要スペックや補足事項の配列	`[]`
`fallbackImage`	OGP画像を取得・表示できない場合に使用するローカル画像または画像URL	任意
`imageMode`	画像の取得方法。`og`，`local`，`none`から選択	`og`

imageMode="og"では，ビルド時にofficialUrlからog:imageを取得する。公式サイトが自動取得を拒否する場合は，ページで使用されているOGP画像URLをogImageへ直接指定できる。取得に失敗した場合はfallbackImageを表示し，どちらも利用できなければ画像領域自体を表示しない。ブラウザ上でOGP画像の読み込みに失敗した場合も，同じ順序でフォールバックする。外部サイトの応答不良によってブログ全体のビルドが失敗することはない。

ローカル画像だけを使用する場合はimageMode="local"とfallbackImageを組み合わせる。画像を表示しない場合はimageMode="none"を指定する。

外部コンテンツの埋め込み

単独URLによる自動埋め込み

MDXファイルの独立した1行に，リンク化される完全なURLだけを書く。コンポーネントのimportは不要である。

https://www.youtube.com/watch?v=vhfYis6VuXY

自動埋め込みの対象は次のとおり。

YouTube
X / Twitter
Vimeo
GitHub Gist
Bluesky
Mastodon
その他のWebページのLinkPreview

URLの前後に文章がある場合や，リンクテキストがURLと異なる場合は自動埋め込みされない。

コンポーネントによる埋め込み

表示位置や対象を明示したい場合は，astro-embedからコンポーネントをimportして使用する。

import { YouTube, Tweet, LinkPreview } from "astro-embed";

<YouTube id="https://youtu.be/vhfYis6VuXY" />

<Tweet id="https://x.com/Perfume_Staff/status/1973342128710316241" />

<LinkPreview id="https://www.perfume-web.jp/" />

明示的に利用できるコンポーネントは次のとおり。

YouTube
Tweet
Vimeo
Gist
LinkPreview
BlueskyPost
MastodonPost
BaselineStatus

Instagram，TikTok，Spotify，Google Mapsなどには専用コンポーネントがない。各サービスが提供するiframeを直接記述することはできるが，レスポンシブ表示やプライバシー設定は執筆者が調整する必要がある。

↓Spotifyをiframeで埋め込む場合

コードブロック

バッククォート3つで囲み，開始行に言語名を書くとシンタックスハイライトされる。すべてのコードブロックにはコピーボタンが自動で付く。

```python
print(3 + 5)
```

print(3 + 5)

ファイル名

ファイル名は言語名の後ろにfile="ファイル名"と書く。言語名:ファイル名という記法には対応していない。

```typescript file="sum.ts"
export const sum = (a: number, b: number) => a + b;
```

export const sum = (a: number, b: number) => a + b;sum.ts

行・単語・差分の強調

Shikiの記法で，行のハイライト，単語のハイライト，追加・削除行を表示できる。記法用コメントは出力時に取り除かれる。

```javascript
const siteName = "奥山 怜央"; // [!code highlight]
const greeting = "Hello"; // [!code word:Hello]
console.log("old"); // [!code --]
console.log("new"); // [!code ++]
```

const siteName = "奥山 怜央";
const greeting = "Hello";
console.log("old");
console.log("new");

コールアウト

補足，ヒント，注意，重要事項，例示には，引用記法ではなくCalloutコンポーネントを使用する。コールアウトを使うMDXでは，フロントマター直後にコンポーネントを一度だけインポートする。

import Callout from "@/components/Callout.astro";

<Callout type="warning" title="個人情報に注意">

氏名や住所などの個人情報は入力しないでください。

</Callout>

記述時は次の点に注意する。

typeは必須で，次の5種類から選ぶ。
titleは任意。省略すると，種類ごとの標準タイトルが表示される。
本文をMarkdownとして解釈させるため，開始タグの直後と終了タグの直前に空行を置く。
終了タグ</Callout>は独立した行に置く。
コールアウト内では，通常のMarkdownと同じように段落，強調，リンク，リスト，コードなどを使用できる。

`type`	標準タイトル	用途
`info`	情報	補足，背景，記事について
`tip`	ヒント	推奨操作，効率化，コツ
`warning`	注意	リスク，避けるべき操作
`important`	重要	必ず確認すべき条件，権利表記
`example`	例	プロンプト，入力例，比較例

コールアウトは執筆者による補足や注意を示す。外部資料や人物の言葉を転載する場合は，次の引用記法を使用する。

引用

通常の引用

> 引用する本文。

引用する本文。

複数段落にする場合は，段落間に>だけの行を置く。

> 引用する本文の1段落目。
>
> 引用する本文の2段落目。

引用元

引用ブロックの末尾に<cite>を置くと，右下に引用元を表示する。画面上では「出典：」が自動で付くため，<cite>内には出典名だけを書く。

> あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら。
>
> <cite>宮沢賢治『ポラーノの広場』</cite>

あのイーハトーヴォのすきとおった風、夏でも底に冷たさをもつ青いそら。
宮沢賢治『ポラーノの広場』

引用元にURLを付ける場合は，<cite>内にリンクを書く。

> 引用する本文。
>
> <cite><a href="https://example.com/">資料名</a></cite>

脚注

GitHub Flavored Markdown¹の脚注を利用できる。脚注一覧は記事末に自動生成され，各脚注には本文へ戻るリンクが付く。

本文中で説明を補足する。[^storage]

[^storage]: 補足説明や参考資料を書く。

同じ記事内で脚注IDが重複しないようにする。数字だけでなく，内容が分かる英数字のIDも使用できる。

記事ページで自動的に表示されるもの

本文以外に，記事ページでは次の要素が自動的に表示・生成される。

パンくずリスト
公開日または更新日
推定読了時間
スクロール進捗バー
PC用サイド目次
見出しのアンカーリンク
コードブロックのコピーボタン
タグリンク
X，Pinterest，メール，Facebook，LINEの共有リンク
著者紹介
共通タグに基づく関連記事（最大4件）
前後の記事へのリンク
ページ先頭へ戻るボタン
ライト／ダークモード
Pagefindによる全文検索への収録
OGP，Twitter Card，canonical URL
BlogPosting構造化データ
RSSとsitemapへの掲載

GitHub Docs(N/A). 「基本的な書き込みと書式設定の構文 - GitHubドキュメント」 https://docs.github.com/ja/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax (参照：2026年08月15日) ↩

【参考】このブログで使える投稿記事の記法・仕様

目次

目次

記事ファイルの基本

最小構成

フロントマター

URL（スラッグ）

公開日時と更新日時

下書きと注目記事

タグ

ヒーロー画像

OG画像

canonicalURLと編集リンク

見出し

基本的な本文記法

文字装飾

箇条書きと番号付きリスト

表

水平線

画像

最適化する画像

最適化しない画像

リンク

商品カード

外部コンテンツの埋め込み

単独URLによる自動埋め込み

コンポーネントによる埋め込み

コードブロック

ファイル名

行・単語・差分の強調

コールアウト

引用

通常の引用

引用元

脚注

記事ページで自動的に表示されるもの

関連記事

プロフィール・ブログサイトを作成・アップデートしました

お問い合わせフォームをTallyからSSGformに移行しました

自作ツールをまとめるToolsページを作りました

目次

記事ファイルの基本

最小構成

フロントマター

URL（スラッグ）

公開日時と更新日時

下書きと注目記事

タグ

ヒーロー画像

OG画像

canonicalURLと編集リンク

見出し

基本的な本文記法

文字装飾

箇条書きと番号付きリスト

表

水平線

画像

最適化する画像

最適化しない画像

リンク

商品カード

外部コンテンツの埋め込み

単独URLによる自動埋め込み

コンポーネントによる埋め込み

コードブロック

ファイル名

行・単語・差分の強調

コールアウト

引用

通常の引用

引用元

脚注

記事ページで自動的に表示されるもの

Footnotes

関連記事

プロフィール・ブログサイトを作成・アップデートしました

お問い合わせフォームをTallyからSSGformに移行しました

自作ツールをまとめるToolsページを作りました