ENGINEER BLOG ENGINEER BLOG
  • 公開日
  • 最終更新日

【VSCode拡張機能】Markdown PDFでサクッと手順書作成！

この記事を共有する

目次

はじめに

こんにちは、サービスGの森です。
みなさんは手順書をどのような形式で作成されていますか？Word、Excel、txt...など現場によってさまざかと思います。

ただし上記のファイル形式において作成しづらい、スタイルの不整合が発生しやすい、バージョン管理しにくい、各バージョンの差分が表示しづらい、改竄できてしまう...etcなどのデメリットを感じた方もいらっしゃるのではないでしょうか？

そこで、今回は手順書をMarkdownで作成してPDF化する方法を紹介していきます。

やりたいこと

  1. txt形式の手順書をMarkdown形式に置き換える
  2. VSCodeの拡張機能「Markdown PDF」で作成したMarkdownファイルをPDF化する


0. 事前準備

今回はAmazon CloudShellにログインして、aws sts get-caller-identityコマンドを実行する架空の手順書を用意しました。こちらをMarkdownで記述していきます。 

================================================================================
作業手順書
 
バージョン: 1.0
作成日: yyyy年mm月dd日
作成者: aa部bb課              
================================================================================
 
0. 前提条件
〇作業環境
①対象のAWSアカウントのCloudShellにアクセス可能な権限を持つIAMユーザーの認証情報（ユーザー名、パスワード）を取得していること
②MFA（多要素認証）デバイスまたはアプリケーションが利用可能であること
③Google Chrome ブラウザがインストールされており、最新版に更新されていること
④AWS管理コンソール（*.aws.amazon.com）へのHTTPS接続が可能であること
〇作業体制
⑤作業は必ず2人1組（作業者: 1名、確認者: 1名）で実施すること
⑥作業チェックシートを用意し、各手順の実施状況を必ず記録すること
⑦エラーが発生した場合は、エラー内容とその対処法を詳細に記録して上長に速やかにエスカレーションを行う事
 
1. AWSマネジメントコンソールへのログイン
①ブラウザでAWSコンソールにアクセスを行う
URL: https://aws.amazon.com/console/
②サインイン方法に「IAMユーザーとしてサインイン」を選択する
③認証情報を入力する
・アカウントID: 12桁のAWSアカウントID
・IAMユーザー名: 作成済みのIAMユーザー名
・パスワード: IAMユーザーのパスワード
④MFA デバイスからの認証コードを入力し、マネジメントコンソールにログインする
⑤ログイン後、リージョンを[アジアパシフィック(東京)]に切り替える※ログイン時に[アジアパシフィック(東京)]が選択されている場合は不要
 
2. CloudShellサービスへのアクセス
①マネジメントコンソール上部の検索バーに [CloudShell] と入力し、検索結果からCloudShellを選択する
②ap-northeast-1タブにプロンプトが表示されていることを確認する
③現在のユーザー情報を出力し、対象アカウントとIAMユーザー名に相違が無い事を確認する
  
実行コマンド:
aws sts get-caller-identity
     
実行結果例:
{
    "UserId": "AIDACKCEVSQ6C2EXAMPLE",
    "Account": "123456789012", 
    "Arn": "arn:aws:iam::123456789012:user/username"
}


1. Markdown PDFのインストール・設定

1. VSCodeで拡張機能「Markdown PDF」をインストール

  • 今回の肝となるツールです。

markdown_pdf.png

2. [設定]から拡張機能の設定

設定項目 設定値 説明
Markdown-pdf: Hilight Enable Syntax hilighting: check SyntaxHilightを有効にする
Markdown-pdf: Hilight Style dark.css SyntaxHilightに使用するcssを指定
Markdown-pdf: Markdown-it-include: Enable Enable markdown-it-include. markdownのネスト機能を有効化
Markdown-pdf: Header Template <div></div> ヘッダーを空にする


2. Markdownファイルの作成

1. プロジェクトフォルダの作成

  • 「Amazon_CloudShell_作業手順.md」から他のファイルを参照する構成とします。
.Amazon_CloudShell_作業手順/
├─ docs/                                   # Markdownファイルを保管
│    ├─ Amazon_CloudShell_作業手順.md     # ルートとなるファイル
│    ├─ 1_表紙.md                         # ルートから参照するファイル
│    ├─ 2_改定履歴.md
│    ├─ 3_概要.md
│    └─ 4_作業手順.md
│
└─ images/                　　　　         # 画像ファイルを保管


2. docs/1_表紙.mdの作成

  • ここではタイトルをページ中央に表示させたいのでHTMLで記述していきます。
<div style="text-align: center; margin-top: 50%;">
 
<h1 style="text-align: center;">作業手順書</h1>
 
<div style="text-align: center;">
バージョン: 1.0<br>
作成日: yyyy年mm月dd日<br>
作成者: aa部bb課<br>
</div>
</div>
 
<!-- 改ページ -->
<div style="page-break-after: always;"></div>
 

ポイント1:

改ページが必要な箇所には以下のHTMLタグを使用します。

<!-- 改ページ -->
<div style="page-break-after: always;"></div>
 

ポイント2:

ファイルの最終行は空白行としておきます。これをしておかないと次のページの先頭行が正しく解析されません。 他のファイル形式と同様、Markdownでもお作法のように空白行をいれておきましょう。


3. docs/2_改定履歴.mdの作成

  • Markdownのテーブルで記述していきます。
# 改定履歴
 
| バージョン | 改訂日 | 改訂内容 | 作成者 |
|---|---|---|---|
| 1.0 | yyyy/mm/dd | 初版作成 | aa部bb課 |
| - | - | - | - |
| - | - | - | - |
| - | - | - | - |
| - | - | - | - |
| - | - | - | - |
 
<!-- 改ページ -->
<div style="page-break-after: always;"></div>
 


4. docs/3_概要.mdの作成

  • ざっくり概要だけ記載します。
# 概要
本ドキュメントはAmazon CloudShellを使用し、CloudShell実行ユーザーのアカウントIDとIAMユーザーARNを取得する手順について記載します。
 
<!-- 改ページ -->
<div style="page-break-after: always;"></div>
 


5. docs/4_作業手順.mdの作成

  • ここでは存分にMarkdown記法を使って下さい！
# 作業手順
 
## 0. 前提条件
 
### 作業環境
 
1. 対象のAWSアカウントのCloudShellにアクセス可能な権限を持つIAMユーザーの認証情報（ユーザー名、パスワード）を取得していること
2. MFA（多要素認証）デバイスまたはアプリケーションが利用可能であること
3. Google Chrome ブラウザがインストールされており、最新版に更新されていること
4. AWS管理コンソール（*.aws.amazon.com）へのHTTPS接続が可能であること
### 作業体制
 
1. 作業は必ず2人1組（作業者: 1名、確認者: 1名）で実施すること
2. 作業チェックシートを用意し、各手順の実施状況を必ず記録すること
3. エラーが発生した場合は、エラー内容とその対処法を詳細に記録して上長に速やかにエスカレーションを行う事
 
## 1. AWSマネジメントコンソールへのログイン
 
1. ブラウザでAWSコンソールにアクセスを行う
   ```
   URL: https://aws.amazon.com/console/
   ```
 
2. サインイン方法に「IAMユーザーとしてサインイン」を選択する
 
3. 認証情報を入力する
   - **アカウントID**: 12桁のAWSアカウントID
   - **IAMユーザー名**: 作成済みのIAMユーザー名
   - **パスワード**: IAMユーザーのパスワード
 
4. MFA デバイスからの認証コードを入力し、マネジメントコンソールにログインする
 
5. ログイン後、リージョンを[アジアパシフィック(東京)]に切り替える
  - **画面表示例**  
  ![リージョン選択画面](.././images/リージョン選択画面.png)
   
  - **※ログイン時に[アジアパシフィック(東京)]が選択されている場合は不要**
 
### 2. CloudShellサービスへのアクセス
 
1. マネジメントコンソール上部の検索バーに **[CloudShell]** と入力し、検索結果から**CloudShell**を選択する
2. `ap-northeast-1`タブにプロンプトが表示されていることを確認する
 
3. 現在のユーザー情報を出力し、**対象アカウントとIAMユーザー名**に相違が無い事を確認する
   ```bash
   aws sts get-caller-identity
   ```
 
    **実行結果例**
   ```json
   {
       "UserId": "AIDACKCEVSQ6C2EXAMPLE",
       "Account": "123456789012", 
       "Arn": "arn:aws:iam::123456789012:user/username"
   }
   ```
 


3. MarkdownファイルのPDF化

1. VSCodeで「Amazon_CloudShell_作業手順書.md」を開き、「右クリック」-「Markdown PDF: export (pdf)」の順に実行します。

pdf化.png


2. しばらくすると「Amazon_CloudShell_作業手順書.pdf」が出力されます。

pdfファイルの確認.png


3. PDFファイルを確認してみます。

  • 表紙

手順書1.png

  • 改定履歴

手順書2.png

  • 概要

手順書3.png

  • 作業手順

手順書4.png

手順書5.png


PDFファイルの生成に成功しました。
Markdownによるバージョン管理の容易性、PDF化による機密性が期待できそうです。

cssが得意な方はもっとかっこよくカスタマイズしてみて下さい。

Markdownについて

Markdownによるドキュメント作成について私見を書いておきます。ここから先は読み飛ばしても大丈夫です。

markdown-it-includeを使用するメリットについて

今回「markdown-it-include」を使用して別ファイルを参照させましたが、これには以下のようなメリットがあります。

  • モジュール化: 大きなドキュメントを分割管理
  • 再利用性: 共通部分を複数ファイルで共有
  • 保守性: 変更時は該当ファイルのみ修正
  • チーム開発: 分担してドキュメント作成

Markdownを記述する時に気を付けたいこと

Markdownの書き方は現場ごとにルールも様々だと思いますが、共通して気を付けた方がいい事をピックアップしてみました。

1. ドキュメントの概要を記載する

本題に入る前に概要を記載しておくと、読み手は何について記されたドキュメントかを早めに理解できます。

2. 階層構造を守る

簡単にいうと「見出し3の中に見出し2を入れないようにしましょう」ということになります。文字を強調したいときは「bold(太字)」などで対応しましょう。

悪い例:

## 見出し2
### 見出し3
 
## 注意！ 
 
### 見出し3
 

良い例:

## 見出し2
 
### 見出し3
 
**注意！**
 
### 見出し3
 

3. コードブロックのSyntax Highlightを有効にする。

可能であれば必ずSyntaxHighlightを使用しましょう。長いコードほど見づらくなります。

悪い例: 

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "*",
            "Resource": "*"
        }
    ]
}
```

良い例:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "*",
            "Resource": "*"
        }
    ]
}
```

4. 複雑な書き方をしない。

Markdown記法を存分に使いこなせるのは良いことですが、あまりに多彩な書き方をしすぎると冒頭であげた「スタイルの不整合」を招いて本末転倒です。
以下8つの要素を使うだけでもドキュメントの体裁は十分だったりします。

  • 見出し
  • リスト
  • 番号付きリスト
  • テーブル
  • コードブロック
  • インラインコード
  • 画像リンク
  • 太字


おわりに

この記事がどなたかのお役に立てると幸いです！

この記事は私が書きました

森 翔吾

記事一覧

最近はコンテナ・サーバレスを学習しています。 よろしくお願いします。

森 翔吾

この記事を共有する

クラウドのご相談

CONTACT

クラウド導入や運用でお悩みの方は、お気軽にご相談ください。
専門家がサポートします。

お問い合わせ

サービス資料ダウンロード

DOWNLOAD

ビジネスをクラウドで加速させる準備はできていますか？
今すぐサービス資料をダウンロードして、詳細をご確認ください。

資料請求