あまり手間をかけずに手順書や検証エビデンスを残したい

## 概要
あまり手間をかけずに手順書や検証エビデンスを残したい。
"いまは"これがいいかなと思ったことを書きました。

## 利用シーンの想定
フォーマットなど決まっていない内部向けの手順書や、簡単な検証結果の記録をするような場合。
手順やエビデンスは、コマンドと画面キャプチャが混在している。
※Windowsの想定。

## 用意するもの
- Visual Studio Code
    - [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
    - [Paste Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image)

## 出来るようになること
- Visual Studio Code
    - テキストが書ける
    - アドオンが追加できる
- Markdown All in One
    - HTML出力イメージがプレビューできる
    - HTML出力ができる
    - 目次が自動生成できる
- Paste Image
    - キャプチャを直感的に貼り付けることができる

## 出来るようになること（詳細）
### Visual Studio Code
詳しい説明は割愛し、紹介ページを貼るだけにします。

- https://azure.microsoft.com/ja-jp/products/visual-studio-code/

### Markdown All in One
#### HTML出力イメージがプレビューできる
`Ctrl + Shift + v` でプレビュー表示ができます。
もう一度押すとプレビューが閉じます。
出力イメージの確認に使用できます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/129204/7c699407-b79e-3c2f-f2c0-bdb9f8723c84.png)


#### HTML出力ができる
以下の操作をすると、Markdownファイルと同じフォルダにHTMLファイルが出力されます。
1. `Ctrl + Shift + P` でコマンドパレットを表示
2. `html` と入力する
3. 候補から、`Markdown All in One : Print Current document to HTML`を選択する

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/129204/3db486bb-9f94-bc8c-7e11-75f9900a163a.png)

ただし、画像のファイルパスがデフォルトだと絶対パスになっているため、このままではほかの人に渡せません。

- HTMLをテキストエディタで確認。絶対パスになっている。

```html
<p><img src="file:///d:\dev\****\****\images\201217-23-07-08.png" alt=""></p>
```

そのため、面倒ですが以下のように設定を変更します。
1. `Ctrl + ,` で設定画面を開く
2. `Absolute Img Path` と入力する
3. `Convert image path to absolute path` のチェックボックスを外す  

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/129204/4cb2b4e0-5a28-0b47-d2db-a6941800103d.png)

- HTMLをテキストエディタで確認。相対パスになった。

```html
<p><img src="images/201217-23-07-08.png" alt=""></p>
```

#### 目次が自動生成できる
画面キャプチャが多くてスクロールが多い手順は、重宝するとおもいます。
以下の操作をすると、カーソルを合わせた位置に目次が生成されます。
1. `Ctrl + Shift + p` でコマンドパレットを表示
2. `toc` と入力する
3. 候補から、`Markdown All in One : Create Table of Contents`を選択する

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/129204/0e183f63-08e0-fe33-96c4-335f13205681.png)


### Paste Image
#### キャプチャを直感的に貼り付けることができる
`Ctrl + Alt + v`でクリップボードのキャプチャを直感的に貼り付けることができます。
実際には、キャプチャを画像として保存して画像のパスをMarkdownに貼り付けています。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/129204/6db0ecd6-4e68-359e-7731-1bafc5f77bac.png)

画像はMarkdownファイルと同じ階層に出力されます。

また、以下のように設定を変更することで、出力先の指定が可能です。
1. `Ctrl + ,` で設定画面を開く
2. `pasteimage.path` と入力する
3. `Paste Image: Path` の値を変更する  
※デフォルト:`${currentFileDir}` となっている。`${currentFileDir}/images` などとする。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/129204/0da58256-f710-8240-ebe5-eea993a95b33.png)


### アウトプットイメージ

こういった手順書が作成できます。

※中身はこちらのAsciidoctorインストール手順を使用しました。
https://qiita.com/aki-nasu/items/450fa0f9dc5cdd7f0acb

#### HTML
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/129204/6d21c145-478d-ae0d-3601-0bc4958e3bf3.png)

#### Markdown

    # Asciidoctorのインストール検証

    - [Asciidoctorのインストール検証](#asciidoctorのインストール検証)
      - [Rubyをインストールする](#rubyをインストールする)
        - [Rubyバージョンを確認する](#rubyバージョンを確認する)
        - [Asciidoctorをインストールする](#asciidoctorをインストールする)
        - [実行確認](#実行確認)
          - [sample.adocとして保存](#sampleadocとして保存)
          - [AsciidoctorでHTMLを出力する](#asciidoctorでhtmlを出力する)

    ## Rubyをインストールする

    [Ruby-Install](https://rubyinstaller.org/downloads/)
    ### Rubyバージョンを確認する
    Ruby 2.7.1-1であること。
    ```
    ruby -v
    ```
    ![](images\201217-23-04-38.png)
    ### Asciidoctorをインストールする
    gemでAsciidoctorをインストールし、インストールできたことを確認
    ```
    gem install asciidoctor
    gem list --local
    ```
    ![](images/201217-23-05-28.png)

    ### 実行確認
    実際にHTMLを出力できることを確認
    以下の内容をテキストに貼り付けてAsciidoctorのコマンドを実行
    #### sample.adocとして保存
    ```
    == レベル 1
    Text.

    === レベル 2
    Text.

    ==== レベル 3
    Text.

    ===== レベル 4
    Text.

    .データ形式はCSV, 各カラム幅は表示域の15% (60 ÷ 4 = 15)
    [format="csv",width="60%",cols="4"]
    [frame="topbot",grid="none"]
    |======
    1,2,3,4
    a,b,c,d
    A,B,C,D
    |======
    ```

    #### AsciidoctorでHTMLを出力する
    ```
    asciidoctor sample.adoc
    ```
    ![](images/201217-23-07-08.png)

### おわりに
ちなみにこの記事は、HackMDで書きました。
公開していいものは、HackMDをオススメします。

**あわせて読みたい・・**
[CodiMDによるドキュメント作成のすすめ](https://qiita.com/aki-nasu/items/5f7cf55bd8bc78fb2050)