Markdownから、共有したくなるPDFへ

1. まずMarkdownを用意する

テキストをエディタに貼り付けるか、.md、.markdown、.txtファイルを開きます。まずわかりやすい文書タイトルを付け、続けてセクションで内容を整理しましょう。入力するそばからプレビューが更新されるので、確認のための保存や再読み込みは不要です。画面が小さい場合は、エディタとプレビューのタブを切り替えながら執筆と確認を行えます。

元のMarkdownは必ず控えておきましょう。テンプレートを試すときは、書き出す前に内容を確認し、サンプルの文章が完成した文書に残らないようにしてください。

2. 見出しと強調を意図的に使う

メインタイトルは半角の#とスペース1つで書きます。大きなセクションには##、小見出しには###を使いましょう。単語をアスタリスク2つで囲むと太字、1つで囲むと斜体、3つで両方になります。左右のマーカーの数を揃えてください。アスタリスクを何度も重ねると原文が読みにくくなり、パーサーの解釈が変わることもあります。

# Project brief

## The goal

Make the **important point** clear.
Use *emphasis* sparingly, or ***combine both***.

- First action
- Second action

段落の間やリストの前後には空行を入れてください。原文の改行が、PDFで必ず新しい段落になるとは限りません。見出しを一貫させておくと、自動生成される目次も使いやすくなります。

3. 表とコードを見やすく保つ

表は短い比較に便利です。列名の下に区切り行を入れ、各セルは簡潔にまとめましょう。モニターでは余裕を持って見えていた幅広の表も、紙面では窮屈になることがあります。大きな比較は小さな表に分けるか、長い説明は下の段落に移してください。

| Task | Status |
| --- | --- |
| Draft | Complete |
| Review | In progress |

```javascript
const total = 3 * 4;
console.log(total);
```

複数行にわたる例にはフェンス付きコードブロックを、短い1行のコマンドにはバッククォートを使いましょう。書き出す前に長すぎるコード行は短くしておいてください。印刷されたページは、エディタのように横に広がることができません。

4. 文書にふさわしい画像を追加する

画像は感嘆符、角括弧内の説明テキスト、丸括弧内の参照元という形式で書きます。下の例のアドレスは、実際の画像のものに置き換えてください。Imagesツールを使えば、ローカルのPNG、JPEG、GIF、WebPを選んでMarkdownに埋め込むこともできます。ファイル名をそのまま残さず、内容が伝わる代替テキストを書きましょう。

![Project timeline with three milestones](https://example.com/timeline.png)

ダウンロードする前に、すべての画像が正しく表示されているか確認してください。リモート画像はアクセス権限が必要だったり、後で参照できなくなったりすることがあります。また、自分のパソコン上のローカルなファイルパスは、書き出し用サーバーから自動的に参照できるわけではありません。極端に大きい元画像より、適切なサイズに調整した画像を使いましょう。

図、数式、改ページ

言語をmermaidに指定したフェンス付きブロックは図になります。単一のドル記号で囲んだTeXはインライン数式、独立した行で二重のドル記号に囲んだTeXは中央揃えの数式になります。\newpageのみを含む行は強制的に改ページを行います。先頭のフロントマターブロックでは、表紙とPDFのプロパティに使われるタイトル、サブタイトル、著者、日付、キーワードを設定できます。

---
title: Payment service spec
author: Sam
---

```mermaid
flowchart LR
  A[Order] --> B[Charge] --> C[Receipt]
```

The wait after attempt $n$ is $w_n = 2^n \cdot 250$ ms.

\newpage

図はブラウザ内で描画され、PDFの生成リクエストと一緒に送信されるため、図に関する情報がサーバーに保存されることはありません。

5. 最終確認の前にページレイアウトを設定する

A4、A5、Letterのいずれかを選び、続けてクリーン、エディトリアル、テクニカルのいずれかの文書スタイルを選びます。これらの設定は書き出す文書に反映されます。標準、コンパクト、ゆったりの余白はすぐに使える出発点で、カスタム余白では各辺をミリメートル単位で調整できます。ヘッダーやフッターを使う場合は、そのための余白も確保しておきましょう。

長い文書には目次をオンにしましょう。目次には最初の3段階までの見出しレベルが使われます。ページ番号や、ブランドのテキスト・ロゴも確認してください。サイトをライトモードとダークモードで切り替えるのは閲覧上の好みであり、文書を暗い背景で印刷する指示ではありません。

6. 書き出して、確認して、ダウンロードする

プレビューの内容に問題がなければPDFを生成します。ライブプレビューは編集中に便利ですが、改ページや画像の配置、繰り返し表示される要素の最終確認には、生成されたPDFそのものを見る必要があります。共有する前に、1ページ目、表のあるページ、最後のページを開いて確認しましょう。

通常の文書テキストは、PDF内でも選択可能な状態のままです。MDPressは最初のメイン見出しからダウンロード用のファイル名を作成し、それがない場合はほかの見出しか、最初の空でない行を使います。たとえば「Project brief」は「project-brief.pdf」になります。ダウンロードフォルダの外でも意味が通じるよう、わかりやすいタイトルを付けましょう。

確認しておきたい書式の問題

書式がおかしく見えるときは、閉じられていないコードフェンス、対応の取れていない強調マーカー、空行の抜けがないか確認してください。内容が詰まって見える場合は、表のセルを短くするか、ページ形式や余白を調整しましょう。生のHTMLはテキストとして扱われ、先頭のYAMLフロントマターは取り除かれます。埋め込みのHTMLやフロントマターで書き出しを制御しようとせず、対応している印刷設定には文書の各種コントロールを使ってください。

下書きと書き出しデータの行き先

下書きのテキスト、設定、保存したプリセットは、このブラウザのローカルストレージに保存されます。クラウドへのバックアップではないため、ブラウザのデータを消去すると失われる場合があります。書き出しを行うと、Markdownと文書設定がPDF生成のためにMDPressのサーバーへ送信されます。再利用できる元ファイルが欲しい場合、特に別の端末に移る前には、Markdown形式でもダウンロードしておきましょう。