デザイナースタートのプログラミング初心者です。
初歩的なVuepressの解説になります。
内容の多くが既出ですが、「現役エンジニアにとっては簡単なことかもしれないけど私にはわからないっ
」という部分を補強する意図があります。「理屈はわからないけど、書いてる通りに進めたら出来た！！」を目指します。
Version 1.7.1
流れ
- (必要なものを準備)
- Vuepressインストール
- Vuepressの設定をいじる
- Vuepressの中身をつくる
- サイトを公開する
必要なものを準備
テキストエディタ
なんでもいいのですが「VScode」がおすすめ
ターミナル
最初から入ってることが多いのでPC内で「terminal」とかで検索してみて下さい。
ターミナルにもいろいろあるらしいのですが、私は「Windows Terminal」をインストールしました。
Node.js
この辺はデザイナーに縁がありません。
しかしこれがないといけないみたいなので何も考えず手を動かします。
既に入ってるかどうかの確認法
ターミナルを起動、以下を入力してEnter
node --version
入っていればこんな感じでバージョンが表示されます。
v14.6.0
errorが表示されたら下記を参考にNode.jsを入手してください。
参考:Node.jsをインストールする
Vuepressインストール
まず作業フォルダを作成します。
vuepress_qという名前でフォルダを作りました。
(ネーミングに関して、日本語や記号とかは避けるのがベターですね)
ターミナルでそのフォルダまで移動します。
やり方ですが、例えばProductsフォルダの中のvuepress_qに移動したければ
cd Products/vuepress_q/
と入力してEnter。
例えば私の場合は以下のようになりました。
PS C:\Users\ユーザー名\Desktop\tests\vuepress_q>
ここで、
npm init
と入力してEnter。
ターミナルにいくつかの質問が表示されますが、全てEnterで進めます。
Is this OK? (yes)が最後です。
この段階ではフォルダ内にpackage.jsonが作られていることが確認できます。
そしてようやくvuepressのインストール。
npm install --save-dev vuepress
数十秒待たされます。
.
├── node_modules
├── package-lock.json
└── package.json
インストールが完了するとフォルダの中身はこんな感じになっていると思います。
Vuepressの設定をいじる
package.jsonを開いて、
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
↑ここを↓このように書き換えてください。
"scripts": {
"dev":"vuepress dev src",
"build":"vuepress build src"
},
次に、作業フォルダ(vuepress_q)の直下にsrcという名前でフォルダを作ります。
(自信のない方はフォルダ名変えずに)
さらにsrc直下にREADME.mdというファイルを作ります。
.mdはマークダウン記法という形式で文書を作成できるファイルです。
マークダウン自体はとても簡単なので気軽にご活用ください。
Markdown記法 チートシート
README.mdを開き、例えば
# ああああ
とでも入力し、保存して下さい。
一応これで超最小構成は完成となります。
ページの確認方法ですが、.htmlのようにローカルで開くだけでは正常に確認できません。
ターミナルで作業フォルダ(vuepress_q)にいる状態で、
npm run dev
と入力してEnterをおすと何やら処理が始まって
http://localhost:8080/
こんなURLが表示されます。このURLをブラウザで表示すると
元気なVuepressが確認できます。
Vuepressの中身をつくる
srcの直下に.vuepressというフォルダを作り、
さらにその中でconfig.jsというファイルを作成します。(命名順守)
config.jsの中身はひとまずこのように。
module.exports = {
title: 'ページタイトル',
description: 'ここにディスクリプションのテキスト' ,
locales: {
'/': {
lang: 'ja'
}
},
dest: 'docs',
}
aboutページを作る
srcの直下にaboutフォルダ作成しその中にindex.md作成。
上部ナビを作る
上部ナビメニューの設定をconfig.jsの続きに追記します。
module.exports = {
//(省略)
themeConfig: {
nav: [
{ text: 'ほーむ', link: '/' },
{ text: 'あばうと', link: '/about/' }
],
},
}
保存してもブラウザに変化がない場合は、
ターミナルでCtrl + C押してから先ほどのnpm run devを再度実行。
上部メニューが追加されているかと思います。
サイドメニューの追加
ページ内を移動できるサイドメニューを作成します。
下記追記してください。
themeConfig: {
nav: [
{ text: 'ほーむ', link: '/' },
{ text: 'あばうと', link: '/about/' }
],
sidebar: 'auto', //ここ追記
},
(適宜、見出し・本文を追記して…)
本文サンプル
# ああああ
## 画像
## 1 見出し
本文
## 2 見出し
本文
## 3 見出し
本文
こうなります。(変化が無ければターミナルでCtrl + Cからのnpm run dev)
本文で使用している ## 見出し などが自動でサイドメニューとして表示されます。
画像を表示
.vuepressフォルダの下にpublicフォルダを作成し、その中に画像を格納していきましょう。
記述は
もしくは
<img src="./.vuepress/public/sample.jpg">
で表示できます。
もちろん、publicの下にさらにフォルダを追加しても大丈夫です。
テーマカラーの変更
.vuepressの直下にstylesフォルダを作成。
palette.stylファイルを作成(命名順守)
下記の中から変更したい部分だけ記述します。
以下公式より引用
// colors
$accentColor = #3eaf7c
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961
// layout
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px
// responsive breakpoints
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419px
分かりやすくaccentColorを変更します。
$accentColor = #f66
グリーン→レッドに変更できました。
独自のCSSを適用する
前項はあらかじめ指定された箇所をいじるだけでしたが、
スタイルを独自にカスタマイズすることもできます。
stylesフォルダの中にindex.stylを作成します。
例えば以下のシチュエーションで画像を横並びにしたいときは、
<div class="flex">
<img src="https://placehold.jp/f66/fff/300x300.png">
<img src="https://placehold.jp/66f/fff/300x300.png">
<img src="https://placehold.jp/ff6/666/300x300.png">
</div>
.flex{
display:flex;
}
このように通常の.html .cssと同様の記述ができます。
スタイルを上書きする場合は!importantが必要な場合があります。
ページを公開する
サーバーの条件によってはVuepressは動きません。
契約プランにもよりますがレンタルサーバーだと動かないことのほうが多いです。
無料かつ手軽に利用できるサービスだとGithubPagesとNetlifyが有名です。
どちらも出来ることは同じですが、手順が少しだけ異なるのでご注意ください。
Netlifyの場合
ターミナルでvuepress_qにいる状態でnpm run buildと入力しEnterでビルドします。
(画像編集でいうところの書き出しのような作業です。)
ビルドが完了するとdocsという名前のフォルダが作成され、中にはhtmlやcssが生成されているはずです。
(※ここからはVuepressとか関係なく通常のサイト公開と変わりがないため、ざっくりと説明します。)
Netliftyのアカウントを作り、
こんな感じのところにdocsフォルダをドラッグアンドドロップします。
URLが生成されるのでそちらにアクセスしてページが表示されれば完了です。
GithubPagesの場合
Githubでバージョン管理する場合はこちらのほうが便利でしょう。
(※こちらも一般的なGithubの利用方法と被る部分はざっくりいきます。)
Githubでリポジトリを作成して作業データをコミット・プッシュするのですが、
node_moduleフォルダは基本いじらないのでバージョン管理からは外したほうがいいです。
また、src/.vuepress/public/の画像たちも(バージョン管理しないのであれば)含めなくて大丈夫です。
実際にページに反映されるのはこの後ビルドで生成するdocs/assets/imgの画像だからです。
.gitignoreに追記しましょう。
node_module
次にconfig.jsに下記を追記してください。
module.exports = {
//省略
base:'/Githubのリポジトリ名/',
}
あとはNetlifyの場合と同様、npm run buildでビルド、
作業フォルダの中身をデプロイします。
githubのSettingsページ内 Github Pagesセクションで下記のように設定してSaveを押下。
(Branch → Master , folder → /docs)
URLが生成されてページにアクセスできるようになりますが、確認ができるまでに数秒～数分かかります。
私の場合、10分以上かかったこともありました。
それまでは404ページが表示されるはずです。
以上です。適宜記事の更新、リポジトリの公開をしようと思っています。