マークダウンからドキュメントの整備をする備忘録

ドキュメント納品的な内容の備忘録です。

github上のvscodeでLiveShareで共同編集

https://qiita.com/irico/items/b67328fdaa2d9a306cba
招待リンクを踏んだ後にGithubへのログインが必要
招待した人しかコミットできない
誰かの画面を追うのに右上のピンボタンをつかうが招待者が最初からピンついてて画面が移動するが違うとこ編集したい場合外す
プラグインも入れようと思えば入れられるが対応してないものもある

目次を自動挿入

（ローカルで作ったのを貼る）
https://b1san-blog.com/post/vscode/vscode-md-toc/
https://qiita.com/batch_success/items/8b68b0bb35ff2d8f6374

textlinter

コードのlinterではなく日本語の文章校正が要るという話で採用
https://qiita.com/takasp/items/22f7f72b691fda30aea2

ローカルにnodeをみんなが入れる手間をかけるよりはとGithubActionでubuntuでLintがはしるように

name: text linter action
on:
  push:
    branches:
      - main
    paths:
      - "**/*.md"

jobs:
  RunTextLint:
    runs-on: ubuntu-latest
    steps:
      - name: checkout repository
        uses: actions/checkout@v2
      - name: node install
        shell: bash
        run: |
          npm install
      - name: run text lint
        shell: bash
        run: |
          npm run lint

ビルド履歴で問題個所が出るのでそれを基に修正する

ルールを変えたい場合.textlintrcを修正

.textlintrc

{
  "filters": {},
  "rules": {
    "preset-ja-technical-writing": {
      "max-kanji-continuous-len": {
          "max": 10,
          allow: ["***報告書"]
      },
      "no-exclamation-question-mark": {
        allow: ["/\"w+?\"/g"]
      },
      "sentence-length": {
          "max": 200
      }
    }
  }
}

ルールの設定方法と一覧のマニュアル
https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing#%E3%83%AB%E3%83%BC%E3%83%AB%E3%81%AE%E8%A8%AD%E5%AE%9A%E6%96%B9%E6%B3%95

drowioで図を作成する

プラグインを入れて特定の拡張子のファイルを開けるとdrawioの図が作れる画面になるので編集して終わったらsaveし通常通りコミット。
https://tech.fusic.co.jp/posts/2021-06-15-vscode-draw-io-integration/
図の引用部分はマークダウンの書き方のとおりで、以下のように指定する。
![monitoring-flow](images/aaa-flow.drawio.png)

pandocでフォーマット変換

※きれいにwordにするにはテンプレートが無いとダメそうらしいのと、アンカーの改行とかがおかしいとダメとか色々あるようです。

目的：マークダウンで書いたドキュメントをワードに変換したい
変換ツール：pandoc
CIツール：githubactions
成果物保存場所：blob

• ローカルでのテスト

documentのリポジトリをクローンしてくる

pandocをローカルのWSL(ubuntu)に入れる

LinuxのほうがGithubActionsが安いらしいのでWSL側に入れる

# wget https://github.com/jgm/pandoc/releases/download/2.16.1/pandoc-2.16.1-1-amd64.deb
# sudo dpkg -i pandoc-2.16.1-1-amd64.deb
# which pandoc
/usr/bin/pandoc

$ pandoc --version
pandoc 2.16.1

変換方法参考（※扱えるフォーマットなど詳しくは--helpを確認する）
以下はmdファイルをdocxに変換している例

make.sh

#!/bin/bash
pandoc ${1}.md -t docx -o ${1}.docx

ローカルで変換できることを動確する

$ for i in $(ls *.md|grep -v README|sed -e 's/.md//g'); do bash ./make.sh $i; done

xx.mdからxx.docxができるていることを確認する。

• githubactionsのyamlを書く

リポジトリの以下の場所にyamlを書く。

vi .github/workflows/githubAction.yaml

githubActionの部分は任意の名前で大丈夫

pushされるたびに動かすと課金が生じて面倒なことになる可能性があるのでtriggerは手動にする。onのとこに指定する。

name: docs md to docx
# 手動で動くtrigger
on: [ workflow_dispatch ]
# pushされたら動くtrigger
#  push:
#    branches:
#      - main
#    paths-ignore:
#      - ".github/workflows/githubAction.yaml"

# ubuntuで、リポジトリチェックアウトしてpandoc入れて変換して成果物をアップロードする
jobs:
  ConvertDocument:
    runs-on: ubuntu-latest
    steps:
      - name: checkout repository
        uses: actions/checkout@v2
      - name: install pandoc
        shell: bash
        run: |
          wget https://github.com/jgm/pandoc/releases/download/2.16.1/pandoc-2.16.1-1-amd64.deb
          sudo dpkg -i pandoc-2.16.1-1-amd64.deb
          pandoc --version
      - name: convert ConvertDocument
        shell: bash
        run: |
          for i in $(ls *.md|grep -v README|sed -e 's/.md//g'); do bash ./make.sh $i; done
      #TODO 成果物アップロードのところをblobにしたければする
      # https://docs.github.com/ja/enterprise-server@3.0/admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-azure-blob-storage
      # https://docs.github.com/ja/actions/advanced-guides/storing-workflow-data-as-artifacts#uploading-build-and-test-artifacts
      #- name: upload artifact
      #  uses: actions/upload-artifact@v2

• 参考

pandoc
https://pandoc.org/getting-started.html#step-1-install-pandoc

"Understanding GitHub Actions"
https://docs.github.com/ja/actions/learn-github-actions/understanding-github-actions

"ビルドおよびテストの成果物をアップロードする"
https://docs.github.com/ja/actions/advanced-guides/storing-workflow-data-as-artifacts#uploading-build-and-test-artifacts

torigger
https://qiita.com/SnowCait/items/7a30ff80be70a739915c

artifact
https://docs.github.com/ja/enterprise-server@3.0/admin/github-actions/enabling-github-actions-for-github-enterprise-server/enabling-github-actions-with-azure-blob-storage
https://docs.github.com/ja/actions/advanced-guides/storing-workflow-data-as-artifacts#uploading-build-and-test-artifacts
https://docs.github.com/ja/actions/advanced-guides/storing-workflow-data-as-artifacts

そのたgithubaction参考
https://44smkn.hatenadiary.com/entry/2021/03/23/224925
https://qiita.com/HeRo/items/935d5e268208d411ab5a