VS CodeでMarkdownプレビューにCSSを適用する方法｜自分好みのスタイルで見やすくする

Web

「Markdownは便利だけど、プレビューがちょっと味気ない」
「見出しをもっと目立たせたいし、文字を読みやすい色にしたい」
「プロジェクトのドキュメントを、チーム全体で統一したスタイルにしたい」

Markdownはドキュメント作成やREADME作成に非常に便利ですが、デフォルトのプレビュー表示では物足りなさを感じることがあります。

特に、技術文書やプロジェクトドキュメントでは、見た目の美しさと読みやすさが重要です。

実は、Visual Studio Code（VS Code）では、Markdownプレビューに自分で作ったCSSを適用して、見た目を大幅にカスタマイズできます。

これにより、プレビュー画面を自分好みのスタイルに変更し、より読みやすく美しいドキュメントを作成することができます。

この記事では、VS CodeでMarkdownプレビューにCSSを設定する方法を、初心者にも分かりやすく、実例とともに詳しく解説します。

スポンサーリンク

Markdownプレビューカスタマイズの基礎知識

VS CodeのMarkdownプレビュー機能

VS Codeには、Markdownファイルをリアルタイムでプレビューする機能が標準で搭載されています。

プレビューの基本操作

Ctrl + Shift + V    : プレビューを開く
Ctrl + K V          : サイドバイサイドでプレビュー表示
Ctrl + Shift + V    : プレビューとエディターの切り替え

デフォルトのスタイル

VS Codeのデフォルトプレビューは、シンプルで読みやすいスタイルですが、以下のような場合にカスタマイズが必要になります：

  • ブランディング: 会社やプロジェクトのカラーに合わせたい
  • 読みやすさ: フォントサイズや行間を調整したい
  • 見た目の向上: より美しく、印象的なドキュメントにしたい
  • 機能的な改善: コードブロックや表の見た目を改善したい

CSSカスタマイズの仕組み

VS Codeでは、markdown.stylesという設定項目を使用してCSSファイルを指定できます。

設定の流れ

1. CSSファイルを作成
2. settings.jsonで markdown.styles にパスを指定
3. Markdownプレビューで確認
4. 必要に応じてCSSを調整

適用範囲

  • ユーザー設定：すべてのプロジェクトに適用
  • ワークスペース設定：特定のプロジェクトのみに適用

CSSファイルの作成と基本スタイル

プロジェクト構成の準備

ディレクトリ構造の例

my-project/
├── .vscode/
│   └── settings.json
├── styles/
│   └── markdown.css
├── docs/
│   ├── README.md
│   └── API.md
└── src/
    └── ...

基本的なCSSファイルの作成

シンプルなスタイルの例

styles/markdown.cssファイルを作成し、以下のような基本的なスタイルから始めましょう：

/* 全体のフォント設定 */
body {
    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
    line-height: 1.6;
    color: #333;
    max-width: 900px;
    margin: 0 auto;
    padding: 20px;
}

/* 見出しのスタイル */
h1 {
    color: #2c3e50;
    border-bottom: 3px solid #3498db;
    padding-bottom: 8px;
    margin-top: 30px;
    margin-bottom: 20px;
    font-size: 2.2em;
}

h2 {
    color: #34495e;
    border-left: 4px solid #3498db;
    padding-left: 12px;
    margin-top: 25px;
    margin-bottom: 15px;
}

h3 {
    color: #34495e;
    margin-top: 20px;
    margin-bottom: 10px;
}

/* 段落のスタイル */
p {
    font-size: 16px;
    line-height: 1.7;
    margin-bottom: 16px;
    text-align: justify;
}

/* リストのスタイル */
ul, ol {
    padding-left: 30px;
    margin-bottom: 16px;
}

li {
    margin-bottom: 8px;
    line-height: 1.6;
}

/* 強調のスタイル */
strong {
    color: #2c3e50;
    font-weight: 600;
}

em {
    color: #7f8c8d;
    font-style: italic;
}

より高度なスタイル例

コードブロックの美化

/* インラインコード */
code {
    background-color: #f8f8f8;
    border: 1px solid #e1e4e8;
    border-radius: 3px;
    padding: 2px 6px;
    font-family: 'Consolas', 'Monaco', 'Menlo', monospace;
    font-size: 14px;
    color: #d73a49;
}

/* コードブロック */
pre {
    background-color: #f6f8fa;
    border: 1px solid #e1e4e8;
    border-radius: 6px;
    padding: 16px;
    overflow-x: auto;
    margin: 16px 0;
}

pre code {
    background-color: transparent;
    border: none;
    padding: 0;
    color: #24292e;
    font-size: 14px;
    line-height: 1.45;
}

/* シンタックスハイライト風の改善 */
.hljs-keyword {
    color: #d73a49;
    font-weight: bold;
}

.hljs-string {
    color: #032f62;
}

.hljs-comment {
    color: #6a737d;
    font-style: italic;
}

表（テーブル）のスタイル

/* テーブルのスタイル */
table {
    border-collapse: collapse;
    width: 100%;
    margin: 20px 0;
    box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}

th, td {
    border: 1px solid #ddd;
    padding: 12px 15px;
    text-align: left;
}

th {
    background-color: #3498db;
    color: white;
    font-weight: 600;
    text-transform: uppercase;
    font-size: 14px;
    letter-spacing: 0.5px;
}

tr:nth-child(even) {
    background-color: #f8f9fa;
}

tr:hover {
    background-color: #e8f4f8;
    transition: background-color 0.2s ease;
}

td code {
    background-color: #fff3cd;
    color: #856404;
}

引用とアラートボックス

/* 引用のスタイル */
blockquote {
    border-left: 4px solid #3498db;
    background-color: #f8f9fa;
    padding: 16px 20px;
    margin: 20px 0;
    font-style: italic;
    color: #555;
}

blockquote p {
    margin: 0;
}

/* 注意書きボックス（Markdown拡張記法） */
.admonition {
    border-radius: 6px;
    padding: 16px;
    margin: 16px 0;
}

.admonition.note {
    background-color: #e7f3ff;
    border-left: 4px solid #3498db;
}

.admonition.warning {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
}

.admonition.danger {
    background-color: #f8d7da;
    border-left: 4px solid #dc3545;
}

settings.jsonでの設定方法

ユーザー設定（グローバル）

設定ファイルの開き方

  1. コマンドパレットを開く
    • Ctrl + Shift + P（Windows/Linux）
    • Cmd + Shift + P（macOS）
  2. 設定ファイルを開く "Preferences: Open Settings (JSON)" を実行

CSSファイルの指定

{
    "markdown.styles": [
        "file:///C:/path/to/your/project/styles/markdown.css"
    ]
}

ワークスペース設定（プロジェクト固有）

.vscode/settings.jsonの作成

プロジェクトごとにスタイルを適用したい場合：

{
    "markdown.styles": [
        "file:///absolute/path/to/styles/markdown.css"
    ]
}

OS別のパス指定方法

Windows

{
    "markdown.styles": [
        "file:///C:/Users/YourName/Projects/my-project/styles/markdown.css"
    ]
}

macOS

{
    "markdown.styles": [
        "file:///Users/YourName/Projects/my-project/styles/markdown.css"
    ]
}

Linux

{
    "markdown.styles": [
        "file:///home/yourname/projects/my-project/styles/markdown.css"
    ]
}

複数CSSファイルの指定

{
    "markdown.styles": [
        "file:///path/to/base.css",
        "file:///path/to/custom.css",
        "file:///path/to/theme.css"
    ]
}

実用的なCSSスタイル集

GitHub風スタイル

GitHub風の見た目を再現

/* GitHub風スタイル */
body {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
    line-height: 1.5;
    color: #24292e;
    background-color: #ffffff;
    max-width: 980px;
    margin: 0 auto;
    padding: 45px;
}

/* GitHub風見出し */
h1, h2, h3, h4, h5, h6 {
    margin-top: 24px;
    margin-bottom: 16px;
    font-weight: 600;
    line-height: 1.25;
}

h1 {
    font-size: 2em;
    border-bottom: 1px solid #eaecef;
    padding-bottom: 0.3em;
}

h2 {
    font-size: 1.5em;
    border-bottom: 1px solid #eaecef;
    padding-bottom: 0.3em;
}

/* GitHub風コードブロック */
pre {
    background-color: #f6f8fa;
    border-radius: 6px;
    font-size: 85%;
    line-height: 1.45;
    overflow: auto;
    padding: 16px;
}

code {
    background-color: rgba(27,31,35,0.05);
    border-radius: 3px;
    font-size: 85%;
    margin: 0;
    padding: 0.2em 0.4em;
}

/* GitHub風バッジ */
.badge {
    display: inline-block;
    padding: 0.25em 0.4em;
    font-size: 75%;
    font-weight: 700;
    line-height: 1;
    text-align: center;
    white-space: nowrap;
    vertical-align: baseline;
    border-radius: 0.25rem;
}

.badge-primary {
    color: #fff;
    background-color: #007bff;
}

.badge-success {
    color: #fff;
    background-color: #28a745;
}

.badge-warning {
    color: #212529;
    background-color: #ffc107;
}

ダークテーマ風スタイル

目に優しいダークテーマ

/* ダークテーマ */
body {
    background-color: #1e1e1e;
    color: #d4d4d4;
    font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
    line-height: 1.6;
    max-width: 900px;
    margin: 0 auto;
    padding: 20px;
}

/* ダークテーマ見出し */
h1, h2, h3, h4, h5, h6 {
    color: #569cd6;
}

h1 {
    border-bottom: 2px solid #569cd6;
    padding-bottom: 8px;
}

h2 {
    border-left: 4px solid #569cd6;
    padding-left: 12px;
}

/* ダークテーマコード */
code {
    background-color: #2d2d30;
    color: #ce9178;
    border-radius: 3px;
    padding: 2px 6px;
}

pre {
    background-color: #2d2d30;
    border: 1px solid #3c3c3c;
    border-radius: 6px;
    padding: 16px;
    overflow-x: auto;
}

/* ダークテーマリンク */
a {
    color: #569cd6;
    text-decoration: none;
}

a:hover {
    color: #9cdcfe;
    text-decoration: underline;
}

/* ダークテーマテーブル */
table {
    border-collapse: collapse;
    width: 100%;
    margin: 20px 0;
}

th {
    background-color: #2d2d30;
    color: #569cd6;
    border: 1px solid #3c3c3c;
    padding: 12px 15px;
}

td {
    border: 1px solid #3c3c3c;
    padding: 12px 15px;
}

tr:nth-child(even) {
    background-color: #252526;
}

/* ダークテーマ引用 */
blockquote {
    border-left: 4px solid #569cd6;
    background-color: #2d2d30;
    padding: 16px 20px;
    margin: 20px 0;
    color: #cccccc;
}

印刷用スタイル

PDF出力時に最適化されたスタイル

/* 印刷・PDF用スタイル */
@media print {
    body {
        font-family: 'Times New Roman', serif;
        font-size: 12pt;
        line-height: 1.4;
        color: #000;
        background: #fff;
        max-width: none;
        margin: 0;
        padding: 0;
    }
    
    h1, h2, h3, h4, h5, h6 {
        color: #000;
        page-break-after: avoid;
    }
    
    h1 {
        font-size: 18pt;
        border-bottom: 2pt solid #000;
    }
    
    h2 {
        font-size: 16pt;
        border-left: none;
        margin-top: 20pt;
    }
    
    h3 {
        font-size: 14pt;
    }
    
    pre, code {
        font-family: 'Courier New', monospace;
        font-size: 10pt;
    }
    
    pre {
        background-color: #f8f8f8;
        border: 1pt solid #ccc;
        padding: 8pt;
        page-break-inside: avoid;
    }
    
    table {
        page-break-inside: avoid;
        font-size: 10pt;
    }
    
    th {
        background-color: #f0f0f0 !important;
    }
    
    a {
        color: #000;
        text-decoration: underline;
    }
    
    /* URLを表示 */
    a:after {
        content: " (" attr(href) ")";
        font-size: 9pt;
        color: #666;
    }
}

トラブルシューティング

よくある問題と解決方法

CSSが反映されない

原因1：ファイルパスの間違い

症状: CSSファイルを指定したが変化がない

解決方法:

// 間違った例
"markdown.styles": [
    "C:\\path\\to\\markdown.css"  // ❌ file:/// がない
]

// 正しい例
"markdown.styles": [
    "file:///C:/path/to/markdown.css"  // ✅ file:/// で始まる
]
原因2：パスの区切り文字

Windows環境での注意点:

// 推奨（フォワードスラッシュ）
"file:///C:/Users/Name/project/style.css"

// 避ける（バックスラッシュのエスケープが必要）
"file:///C:\\Users\\Name\\project\\style.css"
原因3：ファイルの存在確認
# ファイルが存在するか確認
ls /path/to/markdown.css     # Linux/macOS
dir C:\path\to\markdown.css  # Windows

プレビューに反映されない

VS Codeの再起動
1. VS Codeを完全に終了
2. 再起動
3. Markdownファイルを開いてプレビュー確認
キャッシュのクリア
1. Ctrl + Shift + P でコマンドパレット
2. "Developer: Reload Window" を実行

相対パスが使えない問題

現在の制限

VS CodeのmarkdownStyles設定では、相対パスがサポートされていません。

代替案1：絶対パスの使用
{
    "markdown.styles": [
        "file:///absolute/path/to/styles/markdown.css"
    ]
}
代替案2：拡張機能の使用

「Markdown Preview Enhanced」拡張機能では相対パスが使用可能：

// Markdown Preview Enhanced の設定例
{
    "markdown-preview-enhanced.previewTheme": "github-light.css",
    "markdown-preview-enhanced.codeBlockTheme": "auto.css"
}

CSSの動的な確認方法

開発者ツールでの確認

  1. プレビューを開く
    • Ctrl + Shift + V
  2. 開発者ツールを開く
    • プレビュー画面でCtrl + Shift + I
  3. スタイルの確認
    • Elements タブでHTML構造を確認
    • Styles タブで適用されているCSSを確認

ライブリロードの代替

CSSファイルを編集した際の確認方法：

1. CSSファイルを保存
2. Ctrl + Shift + P → "Markdown: Refresh Preview"
3. または F5 でプレビューをリフレッシュ

高度な活用方法

Markdown Preview Enhanced拡張機能

インストールと基本設定

1. 拡張機能タブで "Markdown Preview Enhanced" を検索
2. インストール
3. より豊富な機能を利用可能

相対パスでのCSS指定

<!-- MarkdownファイルのFront Matter -->
---
html:
  embed_local_images: true
  offline: true
print_background: true
---

<!-- CSSの埋め込み -->
<style>
@import url('./styles/custom.css');
</style>

Markdown Preview Enhanced の設定例

{
    "markdown-preview-enhanced.codeBlockTheme": "github.css",
    "markdown-preview-enhanced.previewTheme": "github-light.css",
    "markdown-preview-enhanced.revealjsTheme": "white.css",
    "markdown-preview-enhanced.mathRenderingOption": "KaTeX",
    "markdown-preview-enhanced.enableTypographer": true
}

CSS変数を使用した柔軟なテーマ

テーマ切り替え可能なCSS

:root {
    /* ライトテーマ */
    --bg-color: #ffffff;
    --text-color: #333333;
    --heading-color: #2c3e50;
    --accent-color: #3498db;
    --code-bg: #f8f8f8;
    --border-color: #e1e4e8;
}

[data-theme="dark"] {
    /* ダークテーマ */
    --bg-color: #1e1e1e;
    --text-color: #d4d4d4;
    --heading-color: #569cd6;
    --accent-color: #9cdcfe;
    --code-bg: #2d2d30;
    --border-color: #3c3c3c;
}

body {
    background-color: var(--bg-color);
    color: var(--text-color);
}

h1, h2, h3, h4, h5, h6 {
    color: var(--heading-color);
}

code {
    background-color: var(--code-bg);
}

pre {
    background-color: var(--code-bg);
    border: 1px solid var(--border-color);
}

条件分岐とレスポンシブデザイン

画面サイズに応じたスタイル

/* デスクトップ向け */
@media screen and (min-width: 1024px) {
    body {
        max-width: 980px;
        font-size: 16px;
    }
    
    h1 {
        font-size: 2.5em;
    }
}

/* タブレット向け */
@media screen and (max-width: 1023px) and (min-width: 768px) {
    body {
        max-width: 100%;
        padding: 20px;
        font-size: 15px;
    }
    
    h1 {
        font-size: 2.2em;
    }
}

/* モバイル向け */
@media screen and (max-width: 767px) {
    body {
        padding: 10px;
        font-size: 14px;
    }
    
    h1 {
        font-size: 1.8em;
    }
    
    pre {
        font-size: 12px;
        overflow-x: scroll;
    }
    
    table {
        font-size: 12px;
    }
}

チーム開発での活用

プロジェクト標準スタイルの作成

チーム共通のCSSファイル作成

/* team-docs.css - チーム標準スタイル */

/* ブランドカラーの定義 */
:root {
    --primary-color: #007acc;    /* 会社のメインカラー */
    --secondary-color: #5c6bc0;  /* セカンダリカラー */
    --success-color: #4caf50;    /* 成功色 */
    --warning-color: #ff9800;    /* 警告色 */
    --error-color: #f44336;      /* エラー色 */
}

/* 会社ロゴ風の見出し */
h1::before {
    content: "? ";
    color: var(--primary-color);
}

/* API仕様書用のスタイル */
.api-method {
    display: inline-block;
    padding: 4px 8px;
    border-radius: 4px;
    font-weight: bold;
    font-size: 12px;
    text-transform: uppercase;
}

.api-method.get {
    background-color: var(--success-color);
    color: white;
}

.api-method.post {
    background-color: var(--primary-color);
    color: white;
}

.api-method.put {
    background-color: var(--warning-color);
    color: white;
}

.api-method.delete {
    background-color: var(--error-color);
    color: white;
}

/* ステータスバッジ */
.status-badge {
    padding: 2px 8px;
    border-radius: 12px;
    font-size: 12px;
    font-weight: 600;
}

.status-badge.todo {
    background-color: #f0f0f0;
    color: #666;
}

.status-badge.in-progress {
    background-color: #fff3cd;
    color: #856404;
}

.status-badge.done {
    background-color: #d4edda;
    color: #155724;
}

Gitでの設定共有

.gitignoreの設定

# VS Code設定は共有するが、個人設定は除外
.vscode/settings.json
!.vscode/shared-settings.json

# 個人用CSSは除外
styles/personal-*.css

共有設定ファイルの作成

.vscode/shared-settings.json:

{
    "markdown.styles": [
        "file:///${workspaceFolder}/styles/team-docs.css"
    ],
    "markdown.preview.fontSize": 16,
    "markdown.preview.lineHeight": 1.6
}

まとめ

VS CodeでMarkdownプレビューにCSSを適用することで、ドキュメントの見た目を大幅に改善できます。

設定手順のおさらい

  1. CSSファイルの作成
    • プロジェクトに適したスタイルを定義
    • 読みやすさと美しさのバランスを考慮
  2. settings.jsonでの設定
    • markdown.stylesにfile:///形式でパス指定
    • ユーザー設定またはワークスペース設定を選択
  3. スタイルの確認と調整
    • プレビューで確認しながら微調整
    • 開発者ツールでCSS適用状況をチェック

カスタマイズのメリット

  • 見た目の向上: より美しく読みやすいドキュメント
  • ブランディング: プロジェクトや会社のカラーに統一
  • 機能性の向上: コードブロック、表、リンクの見やすさ改善
  • チーム統一: 全員が同じスタイルでドキュメントを確認

注意点

  • ファイルパス: file:///形式での絶対パス指定が必要
  • プレビューの更新: CSS変更後は手動でプレビュー更新
  • 拡張機能との競合: 他のMarkdown拡張機能との相性確認

発展的な活用

  • Markdown Preview Enhanced: より高度な機能とカスタマイズ
  • CSS変数: テーマ切り替え可能なスタイル
  • レスポンシブデザイン: 様々な画面サイズに対応
  • チーム開発: 統一されたドキュメントスタイル

Youtube

神話・歴史・伝承の解説チャンネル

スポンサーリンク

コメント

タイトルとURLをコピーしました