[VuePress/Netlify]markdownだけでWebページを作成して公開するまで

• この記事はMDCアドベントカレンダー用に準備してましたが、全枠埋まったので普通に公開します。

概要

• markdownでドキュメントを書いてそれをWebページ化して公開するまでの話です
• markdown以外にも設定ファイルなどはいじりますが、プログラミングすることなくページを作成して公開できます
• 自分の場合は簡単なハンズオン資料など作る時によく活用しています
  • こんなものが作れます
  • https://react-handson.netlify.com/

• 少し長くなってしまいましたが、この手順通り進めれば公開までできるので試してもらえると嬉しいです

登場する技術やサービス

• VuePress
• GitHub
• Netlify

VuePress

• https://vuepress.vuejs.org/
• 今回のメインで、markdownをインプットにWebページ(HTML/CSS/JavaScript)を生成できるライブラリです
• Vueのコンポーネントを作ってカスタマイズなどできますが、markdownを書くだけでも十分便利なライブラリです

GitHub

• https://github.co.jp/
• 説明するまでもないですが、設計図共有サイトGitでバージョン管理しているソースコードをWeb上で管理できるサービスです
• 今回はNetlifyとの連携のためにVuePresを使ったファイルをGitHubにアップロードします

Netlify

• https://www.netlify.com/
• 静的ファイルのホスティングサービスです
• GitHubとの連携が簡単で、指定したリポジトリのコンテンツを簡単に世の中に公開することができます

事前準備

• Node.jsとGitのセットアップが必要です
• 3日目の記事で@aion0721さんが書いてくれたのでそちらを参考にしてください
  • Nodejsインストール
  • Gitのインストール

VuePressでページを作る

セットアップ

• 以下のコマンドを順番に実行してください

mkdir vuepress-sample
cd vuepress-sample
npm init -y
echo 'node_modules' > .gitignore
cd vuepress-sample

• 本筋から逸れるので説明は省きますがディレクトリ内が以下のような状態になっていればOKです

vuepress-sample
├── .gitignore
└── package.json

• vuepress-sampleディレクトリ内で以下のコマンドを実行しVuePressをインストールします

npm i vuepress

• node_modulesディレクトリの中にインストールしたライブラリが配置されます

vuepress-sample
├── .gitignore
├── node_modules
├── package-lock.json
└── package.json

ローカルで動かしてみる

• vuepress-sampleディレクトリにREADME.mdを作成して以下の内容を記載します

# Hello Vuepress

- こんにちは

• 以下のコマンドで起動します
  • 停止はctl + c

npx vuepress dev

• 起動が完了したらhttp://localhost:8080 にアクセスしてみましょう
  

• markdownで書いたファイルがWebページ化されています！

複数ページ作成してみる

• 複数ページ作成して遷移させたり、サイドメニューを表示させたりしてみます

markdownファイルの作成

• docsディレクトリを作成しそこにファイル作成します

# MDCアドベントカレンダー

- MDCの2019年のアドベントカレンダーです

# 1日目の記事

- 1日目の記事です

# 2日目の記事

- 2日目の記事です

# 3日目の記事

- 3日目の記事です

設定ファイルの作成

• 続いて設定ファイルを作成します

module.exports = {
  title: 'MDCアドベントカレンダー',
  themeConfig: {
    sidebar: [
      '/',
      '/article_1',
      '/article_2',
      '/article_3',
    ],
  },
};

起動スクリプトの設定

• 最後に起動スクリプトの設定をします
• package.jsonを修正して下さい
  • scripts内のstartとbuildの行を追加しています

{
  "name": "vuepress-sample",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "vuepress dev docs",
    "build": "vuepress build docs",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "vuepress": "^1.2.0"
  }
}

動作確認

• vuepress-sampleディレクトリで以下のコマンドを実行し起動します

npm start

• 起動したらhttp://localhost:8080 にアクセスしてみましょう

• 一気にそれっぽくなりました！

GitHubにアップロードする

• NetlifyでWeb上に公開するために、まずはGitHubにソースコードをアップロードします
• まずはgitのセットアップ
  • vuepress-sampleディレクトリで以下のコマンドを実行して下さい

git init

• 次にGitHubでリポジトリを作成しそのURLを設定します
• https://github.com にアクセスしてリポジトリを作成して下さい

• 作成できたらURLをコピーしてローカルのソースコードと紐付けます

git remote add origin https://さっきコピーしたURL

• GitHubにファイルをアップロードします

git add .
git commit -m "vuepressのサンプルを作成した"
git push origin master

• 実行後GitHubのリポジトリのページにアクセスしてファイルがアップロードされてればOKです

Netlifyにデプロイ

• 最後はNetlifyにデプロイしてWeb上に公開してみます
• まずはhttps://www.netlify.com/ にアクセスしてSignUpしてください
  • GitHub連携で登録すれば一瞬です
• ログインが完了したら先程作成したリポジトリを連携させます

• 連携が完了すると自動でビルドが走ります
• 少し待ってURLが黄色から緑色になったらデプロイ完了です！

• さっそくURLにアクセスしてみましょう

• ローカルで動かしたときと同じものが表示されてます！
• あなたが作成したWebページが全世界に公開されました！

ページの更新

ページ更新の一連のながれ

• ページを更新する場合は、ローカルで修正してGitHubにアップロードすると自動でNetlifyのビルドが走ります
• なので基本の手順は
  • ①ローカルで編集/動作確認
  • ②GitHubにアップロード
  • ③Netlifyに自動デプロイ
  • といった流れです

ページを更新してみる

• markdownを書き換えてもいいですが今回はVuePressのチップスを紹介しつつページの更新をしてみます

テーマカラーの変更

• デフォルトはVueのテーマカラーである緑色が設定されています
• docs/.vuepress/styles/palette.stylというファイルでカスタマイズできます

$accentColor = #28a6cf // 選択中部分の文字の色
$textColor = #2c3e50 // 文字の色
$borderColor = #eaecef // 区切り線の色
$codeBgColor = #282c34 // ソースコードエリアの背景色

画像の埋め込み

• 画像を埋め込みたい場合は画像ファイルをdocs/.vuepress/publicの中に配置します
• お好きなファイルをimage.pngという名前でdocs/.vuepress/publicに配置して下さい
• トップページに画像を埋め込んでみます

# MDCアドベントカレンダー

- MDCの2019年のアドベントカレンダーです

![mdc](/image.png)

• このように画像を埋め込むことができます

ファビコンの設定

• ファビコンとはブラウザのタブに表示されるアイコンのことです

• ファビコンは通常の画像ではなく専用のフォーマットが必要です
• favicon 作成 などとググれば画像からfaviconを生成してくれるサイトがあるのでそれを使ってfavicon.icoを作成してください
• 作成したfavicon.icoはdocs/.vuepress/public内に配置するだけでOKです

ページの最新化

• GitHubにアップロードします

git add .
git commit -m "ページの変更"
git push origin master

• アップロードが完了するとNetlifyのビルドが走ります
  • ビルドが走り出すとNetlifyのWebページでProduction deploysに表示されます

• Publishedになったらデプロイ完了です

• URLにアクセスすると内容が更新されているはずです！

最後に

• VuePressは最初にセットアップしてしまえば、あとはほとんどmarkdownの編集だけでページが作れます
• さらにNetlifyを使うと簡単にWebページを公開することができてとても便利だと実感していただけたかと思います
• この方法であればドキュメントの管理も自然とGitでバージョン管理されるのもいいところだと思います
• GitHubでブランチ運用をしていけば複数人でコンテンツを作成しレビューしながら作成していくことも容易になります