はじめに
エンジニアとして働いていると、技術ドキュメントや手順書作成は避けて通れない業務です。でも正直、今まで使ってきたツールにはそれぞれ不満がありました。
Word はコードブロックが無かったりと技術ドキュメント向きでは無いし、
Notion や Obsidian 単体では PDF 出力時の見た目を調整できません。
そこで「チームで共有しやすくて、エンジニアが使いやすくて、見た目もキレイなドキュメント環境を作りたい！」と思い立ち、Obsidian + Cursor + Markdown All in Oneの組み合わせで理想的な環境を構築してみました。
今回構築した環境のテンプレートを GitHub で公開しています。
https://github.com/ymtdir/cursor-vault-template
1. 環境構築手順
Obsidian と Cursor の組み合わせについては既に多くの記事で紹介されているので、基本的な設定は他の記事を参考にしてください。この記事ではMarkdown All in One による PDF 出力環境の構築に焦点を当てて解説します。
1-1. Obsidian のインストール
Obsidian はこちらからインストールできます。
1-2. 保管庫を作成
まずは Obsidian で新しい保管庫を作成します。この保管庫がドキュメントの管理拠点となります。
保管庫の名前と保存先のパスを指定して作成します。
保管庫が作成されました。
1-3. Web Clipper の設定
情報収集を効率化したい場合は、Chrome 拡張機能の「Obsidian Web Clipper」をインストールしておくと便利です。
Obsidian Web Clipper - Chrome 拡張機能
使い方は簡単で、クリップしたい Web サイトを右クリックして「Obsidian Web Clipper」→「Save this page」をクリックするだけです。
ショートカットコマンド：
- Windows:
Alt + Shift + O- Mac:
Cmd + Shift + O
すると、Clippings フォルダに自動的に保存されます。
2. Cursor でプロジェクトを開く
Obsidian での初期設定が完了したら、ここからは実際の作業を Cursor で行います。
先ほど作成した保管庫フォルダを Cursor で開きます。
2-1. 推奨ディレクトリ構成
今回作成するディレクトリ構成例：
cursor-vault/
├── .obsidian/ # Obsidian設定ファイル
├── .vscode/
│ └── settings.json # VS Code設定
├── Clippings/ # Web記事のクリップ・情報収集
├── memo/ # 個人的なメモ・アイデアなど
├── docs/ # ドキュメント管理エリア
│ ├── project1/
│ ├── project2/
│ └── manual/
│ ├── setup.md
│ ├── image1.png
│ └── image2.png
├── output/ # PDF出力先
├── styles/
│ └── markdown.css # スタイルシート
└── .cursorrules # Cursorルール設定
このディレクトリ構成はあくまで一例です。皆さんの使い方に応じてカスタマイズしていってください。
例えば、ディレクトリごとに個別の.cursorrulesを設定することで、用途に応じた AI アシスタントのルールを適用できます。
私の場合はqiitaフォルダを作成し、過去記事を参照しながら統一感のある記事を書けるようにしています。
sample/
├── qiita/
│ ├── .cursorrules # Qiita記事用のルール設定
│ ├── archive/ # 過去記事のクリップを保管
│ └── drafts/ # 執筆中の記事
│ ├── qiita.md
│ ├── image1.png
│ └── image2.png
└── .cursorrules # 全体共通のルール設定
このように用途別にフォルダを分けることで、より効率的なドキュメント管理が可能になります。
2-2. .cursorrules の設定（オプション）
Cursor の AI アシスタント機能をさらに活用したい場合は、プロジェクト用の .cursorrules ファイルを作成することをおすすめします。
これにより、ドキュメント作成に特化した AI の支援を受けることができます。以下は一例です：
.cursorrules
# Obsidian + Cursor ドキュメント作成環境
あなたは Obsidian と Cursor を使ったドキュメント作成の専門アシスタントです。
## 全体的な役割
- マークダウン形式での文書作成支援
- Obsidian の機能を活用した構造化されたドキュメント作成
- 効率的な情報整理とナレッジ管理
- ユーザーの文書作成プロセスの最適化
## 基本ルール
1. **言語**: 日本語で応答
2. **形式**: マークダウン形式での出力
3. **構造**: Obsidian の機能を活用した構造化
4. **一貫性**: ディレクトリごとの用途に応じた適切な形式
5. **品質**: 読みやすく、メンテナンスしやすいドキュメント作成
## ディレクトリ別の用途
- **Clippings/**: Web 記事の要約・整理、情報収集、外部コンテンツの保存
- **docs/**: プロジェクトドキュメント、仕様書、ガイド類
- **output/**: 最終成果物・レポート、PDF 出力ファイル
- **styles/**: CSS やスタイルシート、レイアウト定義
## 出力時の注意点
- 適切な見出しレベルの使用（H1は1つまで、階層構造の維持）
- 内部リンク `[[]]` と外部リンク `[]()` の適切な使い分け
- タグの一貫性（`#tag` 形式）
- 後で検索しやすい構造とキーワードの配置
- Obsidian の機能（グラフビュー、バックリンク等）を考慮した設計
- コードブロックの言語指定（シンタックスハイライト）
このようなルールを設定することで、プロジェクトに特化した一貫性のあるドキュメント作成が可能になります。
3. Markdown All in One 拡張機能のインストール
Cursor で Markdown All in One 拡張機能をインストールします。
この拡張機能により、マークダウンから PDF への変換が可能になります。
4. PDF 出力設定
4-1. 出力先ディレクトリの指定
.vscode/settings.jsonファイルを作成し、PDF 出力先を指定します：
{
"markdown-pdf.outputDirectory": "output"
}
これにより、PDF ファイルはoutputフォルダに統一して出力されます。
なお、この設定を行わない場合、PDF はマークダウンファイルと同じディレクトリに出力されます。
出力先を統一したくない場合や、ファイルごとに個別に管理したい場合は、この設定を省略しても問題ありません。
4-2. PDF 出力の実行
ドキュメントを作成したら、エディタを右クリックして「Markdown PDF」をクリックします。
指定した output フォルダに PDF が生成されます。
5. スタイルのカスタマイズ
ここからがこの環境の真骨頂です。CSS を使って見た目を自由にカスタマイズできます。
既存のデザインリソースを参考にしながら、自分の好みやプロジェクトのトーンに合わせてカスタマイズできるのがこの環境の大きなメリットです。
色を変えたり、余白を調整したり、フォントを変更したりと、自由度は無限大です。
見出しのデザインについては、こちらのサイトを参考にさせていただきました：
https://pote-chil.com/css-stock/ja/heading
5-1. styles/markdown.css
h1 {
padding: 0.5em 0.7em;
border: 2px solid #2589d0;
box-shadow: 5px 5px #2589d0;
color: #333333;
}
h2 {
padding: 0.5em 0.7em;
border-left: 5px solid #2589d0;
background-color: #f2f2f2;
color: #333333;
}
h3 {
padding: 0 0.4em 0.2em;
border-bottom: 3px solid #2589d0;
background-color: #ffffff;
color: #333333;
}
:not(pre):not(.hljs) > code {
padding: 0.2em 0.4em;
margin: 0;
font-size: 85%;
white-space: break-spaces;
background-color: #f2f2f2;
border-radius: 6px;
color: blue !important;
}
pre.hljs {
background-color: #1e1e1e;
padding: 1em;
border-radius: 8px;
overflow-x: auto;
}
pre.hljs code {
font-family: "Fira Code", monospace;
font-size: 85%;
line-height: 1.5;
color: #d4d4d4 !important;
}
.hljs-comment {
color: #6a9955;
font-style: italic;
}
5-2. 設定の適用
.vscode/settings.jsonを更新してスタイルを適用します：
{
"markdown-pdf.outputDirectory": "output",
"markdown.styles": ["./styles/markdown.css"],
"markdown-pdf.headerTemplate": "<div></div>"
}
headerTemplateを空にすることで、日付やファイル名を非表示にできます。
なお、完全に非表示にするのではなく、日付のみを表示したり、自由にヘッダーをカスタマイズすることも可能です。
6. 実際の活用シーン
6-1. 技術手順書の作成
システム構築手順やデプロイ手順書の作成に最適です。
コードブロックを多用する文書でも美しく仕上がります。
# サーバー接続
ssh user@example.com
# アプリケーションの起動
docker-compose up -d
6-2. 社内勉強会資料
技術勉強会や手順書の共有にも威力を発揮します。
GitHub で資料を管理したり、PDF 化して配布できます。
6-3. プロジェクトドキュメント
要件定義書や設計書などの正式文書作成にも対応。
企業のブランドカラーに合わせた CSS を作成すれば、統一感のある文書が作成可能です。
7. Git 管理による効率化
作成した環境は Git で管理することで、さらに効率的になります。
なお、個人的なメモや機密情報など、共有したくないファイルは .gitignore で除外することも可能です。
# リポジトリ初期化
git init
# リモートリポジトリ追加
git remote add origin https://github.com/username/cursor-vault.git
# 初回コミット
git add .
git commit -m "feat: ドキュメント管理環境の初期構築"
# プッシュ
git branch -M main
git push -u origin main
まとめ
Obsidian + Cursor + Markdown All in One の組み合わせで、エンジニア向けのドキュメント作成環境を構築しました。
- コードブロックが美しく表示される
- マークダウン記法でサクサク執筆
- CSS で見た目を自由にカスタマイズ
- PDF 出力で簡単共有
- Git でバージョン管理可能
Word や Notion では実現困難な、エンジニアフレンドリーなドキュメント作成環境が完成です！