146 lines
6.0 KiB
Markdown
146 lines
6.0 KiB
Markdown
|
---
|
|||
|
|
title: "管理向け情報"
|
|||
|
|
level: classified # ページのレベルを設定
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 管理向け情報
|
|||
|
|
|
|||
|
|
## このAPIリファレンスの仕組み
|
|||
|
|
|
|||
|
|
このAPIリファレンスは、MkDocsというシンプルなStatic Site Generator（マークダウンで簡単に記載した.md形式のドキュメントから静的なウェブページを生成するジェネレータ）を使ってウェブページを生成し、そうして生成したウェブページをウェブサーバにコピペすることで作られています。
|
|||
|
|
|
|||
|
|
* For full documentation visit [mkdocs.org](https://www.mkdocs.org).
|
|||
|
|
|
|||
|
|
また、生成されるウェブページが使いやすいレイアウトやデザインを持てるよう、MkDocsに下記のMaterial for MkDocsというモジュールを追加してあります。
|
|||
|
|
|
|||
|
|
* For full documentation for MkDocs Material theme visit [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/)
|
|||
|
|
|
|||
|
|
<br>
|
|||
|
|
|
|||
|
|
## MkDocs
|
|||
|
|
|
|||
|
|
MkDocsはMarkdown記述のドキュメントから静的なhtmlサイトページを生成するジェネレーターなのでサーバー側にインストールする必要はありません。Windowsパソコンに入っているWSLを使ってLinuxを動かし、そのLinuxにMkDocsをインストールしてマークダウンドキュメントの生成とhtmlサイトページ生成を行います。なお、MkDocsのLinux（ここではDebian系のUbuntu）へのインストールは下記の手順で行います
|
|||
|
|
|
|||
|
|
$ cd
|
|||
|
|
$ sudo apt update
|
|||
|
|
$ sudo apt install mkdocs
|
|||
|
|
$ mkdocs new <作成するサイトコンテンツ群のフォルダ名（新規・任意名称）>
|
|||
|
|
|
|||
|
|
<br>
|
|||
|
|
|
|||
|
|
## 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.
|
|||
|
|
|
|||
|
|
<br>
|
|||
|
|
|
|||
|
|
## 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.
|
|||
|
|
|
|||
|
|
<br>
|
|||
|
|
|
|||
|
|
## Markdown （マークダウン）
|
|||
|
|
|
|||
|
|
### Markdownの書き方
|
|||
|
|
|
|||
|
|
MkDocksのようなStatic Site Generatorのレンダリング機能を使わなくても、Visual Studio Code (VSCode) に「Markdown All in One」のような拡張モジュールを追加すれば、書きながらそのレンダリング結果を見てマークダウンドキュメントを編集できる。
|
|||
|
|
|
|||
|
|
作成したマークダウンドキュメントをプロジェクトフォルダの下のdocsフォルダに置いていけば、mkdocs buildコマンドで静的サイトコンテンツを生成できるので。
|
|||
|
|
|
|||
|
|
### コンテンツを生成後
|
|||
|
|
|
|||
|
|
静的サイトコンテンツを生成したら、それをウェブサーバに置いて配信する必要があります。サーバー側にFTPサーバーを立ててアップロードという方法も旧来からの手法としてありますが、このケースでは簡便さのためにSCPコマンドを使っています。
|
|||
|
|
|
|||
|
|
<br>
|
|||
|
|
|
|||
|
|
## 使用可能なMarkDownの例
|
|||
|
|
|
|||
|
|
### 文字の装飾
|
|||
|
|
|
|||
|
|
- ==This was marked (highlight)== （対象の文字列を二連続の「=」で挟む）
|
|||
|
|
- ^^This was inserted (underline)^^ （対象の文字列を二連続の「^」で挟む）
|
|||
|
|
- ~~This was deleted (strikethrough)~~ （対象の文字列を二連続の「~」で挟む）
|
|||
|
|
|
|||
|
|
### 絵文字
|
|||
|
|
|
|||
|
|
すべての絵文字のマークダウンは[こちら](https://gist.github.com/rxaviers/7360908)。
|
|||
|
|
|
|||
|
|
:smile: :new: :computer: :thumbsup: :file_folder: :no_entry_sign: :o: :x: :bangbang: :link: :white_check_mark:
|
|||
|
|
|
|||
|
|
### フローチャート図
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
flowchart LR
|
|||
|
|
Start --> Stop
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
``` mermaid
|
|||
|
|
graph LR
|
|||
|
|
A[Start] --> B{Error?};
|
|||
|
|
B -->|Yes| C[Hmm...];
|
|||
|
|
C --> D[Debug];
|
|||
|
|
D --> B;
|
|||
|
|
B ---->|No| E[Yay!];
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 画像
|
|||
|
|
|
|||
|
|
{ width="300" }
|
|||
|
|
|
|||
|
|
<br>
|
|||
|
|
|
|||
|
|
## サイトの記述の更新方法
|
|||
|
|
|
|||
|
|
### 現状ファイルの用意
|
|||
|
|
|
|||
|
|
手書き、もしくはMkDocsのようなSSGを使ってマークダウンドキュメントを書きます。
|
|||
|
|
|
|||
|
|
### 上記を書き換える
|
|||
|
|
|
|||
|
|
基本的には上記のmdファイル書き換えを進めますが、複数の方法があります。
|
|||
|
|
|
|||
|
|
* htmlファイルを書き換える場合
|
|||
|
|
|
|||
|
|
ウェブサーバーにアップロードされているhtmlファイルを取得して書き換えるのでもよいでしょう。その場合はmdファイルから生成したhtmlで上書きされてしまう可能性があるので追ってmdファイルに反映することをすすめます。
|
|||
|
|
|
|||
|
|
* mdファイルを書き換える場合
|
|||
|
|
|
|||
|
|
MkDocsの静的サイト生成機能を使ってhtmlファイルを生成する
|
|||
|
|
|
|||
|
|
### ファイルのアップロード
|
|||
|
|
|
|||
|
|
現状ではウェブサーバにFTPサーバ機能は載せていませんが、FTPが使える場合はFTPでsiteフォルダの中身をアップロードすればよいと思います。
|
|||
|
|
|
|||
|
|
<br>
|
|||
|
|
|
|||
|
|
## トップページ単独更新方法
|
|||
|
|
|
|||
|
|
お知らせなどのみを書き換えたい場合のクイックな手順です。
|
|||
|
|
|
|||
|
|
1. その時点で表示されているサイトコンテンツのダウンロードします。ブラウザで下記のurlにアクセスするとzip形式で全サイトコンテンツがダウンロードできます。
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
http://152.42.132.168/site.zip
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
2. 上記のZipファイルを解凍して得られるsiteフォルダの中にある index.html をテキストエディタで開いて、適宜書き換えます。
|
|||
|
|
|
|||
|
|
3. 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/
|
|||
|
|
|
|||
|
|
4. パスワード（別途個別連絡）を聞かれるので入力します。
|
|||
|
|
|
|||
|
|
これでサイトのindex.htmlを編集したindex.htmlで上書きしました。
|