📘 SmartURLs テンプレートガイド (v1.4.0+)

このガイドでは、SmartURLsのカスタムテンプレート機能の使用方法を説明します。テンプレートは1行の入力フィールドに記述しますが、$nlトークンを使用して複数行の出力を生成できます。

SmartURLsは意図的に軽量です。Webページのコンテンツを読み取ることはなく、URLとブラウザのタブ情報のみで動作します。

1. 基本トークン

SmartURLsは、タブのメタデータと現在のURLに基づいてトークンを置き換えます。

トークン	説明	出力例
`$title`	タブに表示されるページタイトル	`Why the Moon?`
`$title(html)`	HTMLエスケープされたページタイトル（`&`, `<`, `>`, `"`, `'`をエンティティに変換）。HTMLタグ/属性内で安全に使用可能。	`Rock & Roll <Best Hits>` (タイトル例: “Rock & Roll <Best Hits>”)
`$url`	完全なURL	`https://www.youtube.com/watch?v=bmC-FwibsZg`
`$domain`	ホスト名のみ	`www.youtube.com`
`$path`	URLのパス部分	`/watch`
`$basename`	パスの最後のセグメント	`watch`
`$idx`	タブインデックス(1始まり)	`3`
`$date`	ローカル日付(YYYY-MM-DD)	`2025-01-12`
`$time`	ローカル時刻(HH:MM:SS)	`14:03:55`
`$date(utc)`	UTC日付	`2025-01-12`
`$time(utc)`	UTC時刻	`05:03:55`
`$nl`	改行を挿入	(出力に改行を生成)

⚠️ $nlに関する注意: コピーカスタムテンプレートでのみサポートされています。テキストから開くカスタムテンプレートでは使用できません。コピーとオープンで同じテンプレートを再利用したい場合は、オープンテンプレートで$nlを避けるか、スマート(自動検出)モードを使用してください。

⚠️ $title(html)に関する注意: コピーカスタムテンプレートでのみサポートされています。テキストから開くカスタムテンプレートはこのトークンを処理しません。オープンテンプレートでは、代わりに$titleを使用してください。

上記で使用した例のURLとタイトル

トークンがどのように展開されるかを示すため、これらの例では以下を使用します:

📘 タイトル

Why the Moon?

🔗 URL

https://www.youtube.com/watch?v=bmC-FwibsZg

このURLから:

$domain → www.youtube.com
$path → /watch
$basename → watch
$v (クエリパラメータ) → bmC-FwibsZg

日付と時刻は例です。実際の出力はシステムクロックに依存します。

2. クエリパラメータトークン

SmartURLsは、URLから直接クエリパラメータを抽出できます。

🔤 構文

$<param>

🔗 URL例

https://www.youtube.com/watch?v=bmC-FwibsZg&t=123

トークン	出力
`$v`	`bmC-FwibsZg`
`$t`	`123`

パラメータが存在しない場合、その値は空文字列になります。

⚠️ クエリパラメータトークンに関する注意: クエリパラメータトークン(例えば$v、$id、$tagなど)は、コピーカスタムテンプレートでのみ評価されます。テキストから開くカスタムテンプレートでは評価されないため、オープンテンプレートでは使用しないでください。

3. 条件付きブロック

条件付きブロックを使用すると、特定のクエリパラメータが存在する場合にのみ、テンプレートが特定のテキストを出力できます。

🔤 構文

🔹 単一パラメータ

{{q=v: ... }}

🔸 複数パラメータ(AND条件)

{{q=v,t: ... }}

条件付きブロック内では:

$v、$tなどは通常通り展開されます
$nl、$title、$domainも機能します
ネストされたブロックは許可されていません
elseは使用できません

条件が満たされない場合、ブロック全体が出力から削除されます。

⚠️ 条件付きブロックに関する注意: 条件付きブロック(例えば``)は、コピーカスタムテンプレートでのみ利用可能です。テキストから開くカスタムテンプレートでは機能しません。URLを開く際に柔軟なフィルタリングが必要な場合は、スマート(自動検出)モードを使用してください。

4. テンプレートの例とパターン

テンプレートは1行として記述されますが、$nlを使用して複数行を出力できます。

このセクションで使用する例のURLとタイトル:

📘 タイトル

Why the Moon?

🔗 URL

https://www.youtube.com/watch?v=bmC-FwibsZg&t=123

4.1 Markdown: タイトル + URL

🛠 テンプレート

$title$nl$url

💬 出力

Why the Moon?
https://www.youtube.com/watch?v=bmC-FwibsZg&t=123

4.2 Markdownリストアイテム

🛠 テンプレート

- [$title]($url)

💬 出力

- [Why the Moon?](https://www.youtube.com/watch?v=bmC-FwibsZg&t=123)

4.3 YouTube動画ID(存在する場合のみ)

🛠 テンプレート

{{q=v:Video ID: $v$nl}}$title$nl$url

💬 出力

Video ID: bmC-FwibsZg
Why the Moon?
https://www.youtube.com/watch?v=bmC-FwibsZg&t=123

v=が欠けている場合:

Why the Moon?
https://example.com/page

4.4 YouTubeサムネイルURLを生成

既知のYouTubeサムネイルパターンに基づく:

https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg

🛠 テンプレート

{{q=v:Thumbnail: https://img.youtube.com/vi/$v/maxresdefault.jpg$nl}}$title$nl$url

💬 出力

Thumbnail: https://img.youtube.com/vi/bmC-FwibsZg/maxresdefault.jpg
Why the Moon?
https://www.youtube.com/watch?v=bmC-FwibsZg&t=123

4.5 YouTubeサムネイルを埋め込む (Markdown)

🛠 テンプレート

{{q=v:![thumb](https://img.youtube.com/vi/$v/mqdefault.jpg)$nl}}[$title]($url)

💬 出力

![thumb](https://img.youtube.com/vi/bmC-FwibsZg/mqdefault.jpg)
[Why the Moon?](https://www.youtube.com/watch?v=bmC-FwibsZg&t=123)

4.6 タイムスタンプ(利用可能な場合)

🛠 テンプレート

{{q=t:Timestamp: $t sec$nl}}$title$nl$url

💬 出力

Timestamp: 123 sec
Why the Moon?
https://www.youtube.com/watch?v=bmC-FwibsZg&t=123

4.7 複数パラメータ条件

🛠 テンプレート

{{q=v,t:Video: $v ($t sec)$nl}}$url

💬 出力

Video: bmC-FwibsZg (123 sec)
https://www.youtube.com/watch?v=bmC-FwibsZg&t=123

4.8 ログ形式(ドメイン + パス)

🛠 テンプレート

[$domain] $path$nl$url

💬 出力

[www.youtube.com] /watch
https://www.youtube.com/watch?v=bmC-FwibsZg&t=123

4.9 ファイル名スタイルの見出し

🛠 テンプレート

## $basename: $title$nl$url

💬 出力

## watch: Why the Moon?
https://www.youtube.com/watch?v=bmC-FwibsZg&t=123

4.10 ミニマリスト

🛠 テンプレート

$title — $url

💬 出力

Why the Moon? — https://www.youtube.com/watch?v=bmC-FwibsZg&t=123

4.11 日次ログエントリ

🛠 テンプレート

- [$title]($url) — $date $time

💬 出力

- [Why the Moon?](https://www.youtube.com/watch?v=bmC-FwibsZg&t=123) — 2025-01-12 14:03:55

4.12 セパレータ付き複数行

🛠 テンプレート

$title$nl$url$nl---$nl$domain

💬 出力

Why the Moon?
https://www.youtube.com/watch?v=bmC-FwibsZg&t=123
---
www.youtube.com

5. 制限事項

SmartURLsは意図的にシンプルなままです。

❌ SmartURLsが行わないこと:

Webページのコンテンツを解析 (SmartURLsにはHTMLページにアクセスまたは読み取る権限がありません)
メタデータやサムネイルを読み取り
ページ上でJavaScriptを実行
OGタグ、著者、または説明を抽出
ネストされた条件やelseをサポート

✔️ SmartURLsが使用するもののみ:

タブのタイトル
URLコンポーネント
クエリパラメータ
シンプルなトークン置換
オプションの条件付きブロック

これにより、すべてのWebサイトで一貫した動作が保証されます。

6. バージョン互換性

これらの機能は以下で利用可能です: SmartURLs v1.4.0以降

7. フィードバック

機能リクエストや質問については、こちらでイシューを開いてください:

https://github.com/isshiki/SmartURLs/issues