6.0 KiB
| title | level |
|---|---|
| 管理向け情報 | classified |
管理向け情報
このAPIリファレンスの仕組み
このAPIリファレンスは、MkDocsというシンプルなStatic Site Generator（マークダウンで簡単に記載した.md形式のドキュメントから静的なウェブページを生成するジェネレータ）を使ってウェブページを生成し、そうして生成したウェブページをウェブサーバにコピペすることで作られています。
- For full documentation visit mkdocs.org.
また、生成されるウェブページが使いやすいレイアウトやデザインを持てるよう、MkDocsに下記のMaterial for MkDocsというモジュールを追加してあります。
- For full documentation for MkDocs Material theme visit Material for MkDocs
MkDocs
MkDocsはMarkdown記述のドキュメントから静的なhtmlサイトページを生成するジェネレーターなのでサーバー側にインストールする必要はありません。Windowsパソコンに入っているWSLを使ってLinuxを動かし、そのLinuxにMkDocsをインストールしてマークダウンドキュメントの生成とhtmlサイトページ生成を行います。なお、MkDocsのLinux（ここではDebian系のUbuntu）へのインストールは下記の手順で行います
$ cd
$ sudo apt update
$ sudo apt install mkdocs
$ mkdocs new <作成するサイトコンテンツ群のフォルダ名（新規・任意名称）>
Commands
mkdocs new [dir-name]- Create a new project.mkdocs serve- Start the live-reloading docs server.mkdocs build- Build the documentation site.mkdocs -h- Print help message and exit.
Project layout
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
site/ # Generated static documentation site contents.
Markdown （マークダウン）
Markdownの書き方
MkDocksのようなStatic Site Generatorのレンダリング機能を使わなくても、Visual Studio Code (VSCode) に「Markdown All in One」のような拡張モジュールを追加すれば、書きながらそのレンダリング結果を見てマークダウンドキュメントを編集できる。
作成したマークダウンドキュメントをプロジェクトフォルダの下のdocsフォルダに置いていけば、mkdocs buildコマンドで静的サイトコンテンツを生成できるので。
コンテンツを生成後
静的サイトコンテンツを生成したら、それをウェブサーバに置いて配信する必要があります。サーバー側にFTPサーバーを立ててアップロードという方法も旧来からの手法としてありますが、このケースでは簡便さのためにSCPコマンドを使っています。
使用可能なMarkDownの例
文字の装飾
- ==This was marked (highlight)== （対象の文字列を二連続の「=」で挟む）
- ^^This was inserted (underline)^^ （対象の文字列を二連続の「^」で挟む）
This was deleted (strikethrough)（対象の文字列を二連続の「~」で挟む）
絵文字
すべての絵文字のマークダウンはこちら。
😄 🆕 💻 👍 📁 🚫 ⭕ ❌ ‼️ 🔗 ✅
フローチャート図
flowchart LR
Start --> Stop
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
画像
{ width="300" }
サイトの記述の更新方法
現状ファイルの用意
手書き、もしくはMkDocsのようなSSGを使ってマークダウンドキュメントを書きます。
上記を書き換える
基本的には上記のmdファイル書き換えを進めますが、複数の方法があります。
- htmlファイルを書き換える場合
ウェブサーバーにアップロードされているhtmlファイルを取得して書き換えるのでもよいでしょう。その場合はmdファイルから生成したhtmlで上書きされてしまう可能性があるので追ってmdファイルに反映することをすすめます。
- mdファイルを書き換える場合
MkDocsの静的サイト生成機能を使ってhtmlファイルを生成する
ファイルのアップロード
現状ではウェブサーバにFTPサーバ機能は載せていませんが、FTPが使える場合はFTPでsiteフォルダの中身をアップロードすればよいと思います。
トップページ単独更新方法
お知らせなどのみを書き換えたい場合のクイックな手順です。
-
その時点で表示されているサイトコンテンツのダウンロードします。ブラウザで下記のurlにアクセスするとzip形式で全サイトコンテンツがダウンロードできます。
http://152.42.132.168/site.zip -
上記のZipファイルを解凍して得られるsiteフォルダの中にある index.html をテキストエディタで開いて、適宜書き換えます。
-
Windows Power Shellを使って生成したサイトコンテンツ（index.html）をサーバーにアップロードします。下記のコマンドを実行します。
scp "書き換えたindex.htmlがあるフォルダに古パス"\index.html mats@152.42.132.168:/var/www/html/例） scp C:\Users\user\OneDrive\index.html mats@152.42.132.168:/var/www/html/
-
パスワード（別途個別連絡）を聞かれるので入力します。
これでサイトのindex.htmlを編集したindex.htmlで上書きしました。