Ovellum v0.12.0
日本語
GitHub npm

最終更新

アセットとダウンロード#

画像、動画、音声、PDF、フォント、zip — Markdown ページ以外のあらゆるもの。それらを 置く場所は2 つあり、ファイルが 1 つのページに属するのか、それともサイト全体で 安定した URL に存在すべきなのかによって決まります。

1. コンテンツのそばに#

コンテンツフォルダ内のどこにあっても、Markdown 以外のファイルはパスを保ったまま 出力にそのままコピーされます。これは、特定のページやセクションに紐付くアセットの 自然な置き場所です:

content/
  guides/
    install.md
    architecture.svg     →  /guides/architecture.svg
    setup.zip            →  /guides/setup.zip

ルート絶対パス（先頭の /）で参照します:

![Architecture](/guides/architecture.svg)
[Download the starter kit (4 MB)](/guides/setup.zip)

相対パスではなく、ルート絶対パスを使ってください。 ページはきれいな URL （guides/install.md → /guides/install/）になるので、相対の architecture.svg は、ファイルがあるフォルダではなく /guides/install/ に対して解決されてしまいます。 /guides/architecture.svg は常に意図したところを指します。

2. public/ フォルダ → サイトルート#

予約された publicDir（デフォルトは public/）は、 サイトのルートにコピーされます — Next.js、Astro、Vite、Hugo（static/）と同じ 慣習です。ルートに存在しなければならないファイルや、きれいで永続的な URL に置きたい 共有ダウンロードに使います:

content/
  public/
    favicon.ico          →  /favicon.ico
    robots.txt           →  /robots.txt
    report.pdf           →  /report.pdf
    media/intro.mp4      →  /media/intro.mp4
    downloads/app.zip    →  /downloads/app.zip

public/ の中身は一切処理されません — .md でさえそのままコピーされ、ページに 変換されることはありません。お好みで site.publicDir を使って名前を変更できます。

目安: ページ固有の画像 → ページのそばに置く。きれいで永続的な URL がほしい ダウンロードや共有アセット（あるいは favicon.ico / robots.txt のようにルートが 必須のファイル）→ public/。

public/ を CDN から提供する#

デフォルトでは public/ はサイトとともに出荷されます。代わりに CDN やオブジェクト ストアから提供するには、site.assetBaseUrl を設定します — Vite の base や Next の assetPrefix と同じ発想です:

export default {
  site: {
    assetBaseUrl: 'https://cdn.example.com/site',
  },
} satisfies OvellumUserConfig;

あなたは同じルート絶対パス（/report.pdf、/media/intro.mp4）で書き続けます。 ビルド時に Ovellum は:

  • public/ のローカルへのコピーを止め — その中身は自分で CDN にアップロードし （一度きり、またはデプロイ手順で）、そして
  • レンダリングされた HTML 内の public/ のファイルへのすべての参照を CDN に 書き換えます。そのため /report.pdf は https://cdn.example.com/site/report.pdf になります。

コンテンツのそばに存在するアセット（セクション 1）は HTML サイトの一部であり、 手を加えられません — CDN に移るのは public/ だけです。すでにクエリ文字列を 持つ URL や srcset 内にある URL は書き換えられません。それらのファイルは、最終的な CDN の URL で直接参照してください。

ファイル種別ごと#

画像#

![A diagram of the build pipeline](/guides/pipeline.svg)

PDF、zip、その他のダウンロード#

ただのリンクです — ブラウザがそれを開くかダウンロードします:

[Read the spec (PDF, 1.2 MB)](/report.pdf)
[Download v1.0 (zip)](/downloads/app-1.0.zip)

動画と音声#

Markdown 内の生の HTML でネイティブのプレーヤーを埋め込みます（サニタイザーを 通過できます）:

<video src="/media/demo.mp4" controls width="720" poster="/media/cover.jpg"></video>

<audio controls>
  <source src="/media/talk.mp3" type="audio/mpeg" />
</audio>

許可される属性は表示/再生に関するものだけです — controls、width、height、 poster、preload、loop、muted、autoplay、playsinline、加えて <source> / <track>。src / poster の URL はスキームがチェックされ （http(s) または相対）、イベントハンドラ（onerror、…）は除去されるので、埋め込みが スクリプトを運ぶことはできません。小さく、Web 向けに最適化された .mp4 / .webm / .mp3 を選んでください。

YouTube と Vimeo#

YouTube または Vimeo で動画を開き、共有 → 埋め込みを押して、出てきた <iframe> を そのまま貼り付けてください — 編集は不要です:

<iframe
  width="560"
  height="315"
  src="https://www.youtube.com/embed/VIDEO_ID"
  title="YouTube video player"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
  referrerpolicy="strict-origin-when-cross-origin"
  allowfullscreen
></iframe>

Ovellum は既知の動画ホストからのみ <iframe> を許可します（youtube.com、 youtube-nocookie.com、vimeo.com）。そのため、それ以外のどこか（あるいは相対パス）を 指す iframe はサニタイズ中に除去されます — 信頼できないページを誤って埋め込むことは できません。生き残ったものは自動的に強化され（loading="lazy"、厳格なリファラ ポリシー）、レスポンシブな 16:9 のフレームで包まれるので、貼り付けたスニペット内の 固定の width / height は問題になりません。YouTube のプライバシー保護型の埋め込みが ほしい場合は youtube-nocookie.com を選んでください。ライブな例については スタイルガイドを参照してください。

リンクをチェックする#

ovellum check は内部のページリンクを検証します。アセットの URL（画像、 ダウンロード）はページではなくファイルを指すので、そのパスが正しいかは自分で 保ってください — 手早いローカルの ovellum serve（または ovellum dev）が、画像が 表示されダウンロードが解決することを確認する最速の方法です。

このページを編集