mirror of
https://github.com/brain-hackers/wiki.brainux.org
synced 2024-12-23 04:30:05 +09:00
Update How To Edit
This commit is contained in:
parent
1718bd57f5
commit
95ce4d89c4
@ -58,6 +58,35 @@ Configuration file: /Users/takumi/dev/brain/wiki.brainux.org/_config.yml
|
|||||||
Server running... press ctrl-c to stop.
|
Server running... press ctrl-c to stop.
|
||||||
````
|
````
|
||||||
|
|
||||||
|
次に、Textlintとmarkdownlintを使うためにNode.jsとパッケージをインストールします。
|
||||||
|
|
||||||
|
```sh
|
||||||
|
$ cd wiki.brainux.org
|
||||||
|
$ npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
Node.jsのインストール方法とバージョンは動けば何でも良いです。まずはパッケージマネージャーでインストールしたNode.jsを使ってみて、上手く行かなければnodeenv(nodenvではない!)を使う以下の方法を試してください。nodeenvでインストールした場合は、毎回envをactivateするのを忘れないでください。
|
||||||
|
|
||||||
|
```sh
|
||||||
|
$ pip install nodeenv
|
||||||
|
$ nodeenv -n 16.13.2 env
|
||||||
|
$ source ./env/bin/activate
|
||||||
|
(env) $ npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
Textlintを動かして、正常にlintされるか試します。自動修正は`npm run fix`で発動できますが、意図しない修正が起こる可能性があるためあまりおすすめしません。
|
||||||
|
|
||||||
|
```sh
|
||||||
|
$ npm run lint
|
||||||
|
$ npm run fix # お好みで
|
||||||
|
```
|
||||||
|
|
||||||
|
markdownlintを動かして、正常にlintされるか試します。
|
||||||
|
|
||||||
|
```sh
|
||||||
|
$ npm run mdlint
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
# 各種操作
|
# 各種操作
|
||||||
|
|
||||||
@ -101,21 +130,27 @@ Wiki のページを生成している Jekyll は、md ファイルの名前か
|
|||||||
|
|
||||||
|
|
||||||
# 記述ルール
|
# 記述ルール
|
||||||
|
|
||||||
Wiki の体裁について以下にルールを列挙します。コミットの前にこれらに従っているかチェックしてください。Textlint はまだありません。
|
Wiki の体裁について以下にルールを列挙します。コミットの前にこれらに従っているかチェックしてください。Textlint はまだありません。
|
||||||
|
|
||||||
|
|
||||||
## 文体
|
## 文体
|
||||||
|
|
||||||
基本的には、技術文書のルールと同一です。
|
基本的には、技術文書のルールと同一です。
|
||||||
|
|
||||||
|
|
||||||
### 「ですます」と「だ・である」は統一する
|
### 「ですます」と「だ・である」は統一する
|
||||||
|
|
||||||
Wiki 全体で「ですます」の形で統一します。
|
Wiki 全体で「ですます」の形で統一します。
|
||||||
|
|
||||||
|
|
||||||
### 依頼する時はできるだけ「します」で締める
|
### 依頼する時はできるだけ「します」で締める
|
||||||
|
|
||||||
「〇〇してください」は長いので、「します」で極力統一します。不自然に映る場合は「してください」や「しましょう」を使っても OK です。この文書でも実際にどちらも使用しています。
|
「〇〇してください」は長いので、「します」で極力統一します。不自然に映る場合は「してください」や「しましょう」を使っても OK です。この文書でも実際にどちらも使用しています。
|
||||||
|
|
||||||
|
|
||||||
### 繰り返しや冗長な表現をなくす
|
### 繰り返しや冗長な表現をなくす
|
||||||
|
|
||||||
冗長な表現を組み込んでしまうことは多いので、極限まで削ります。
|
冗長な表現を組み込んでしまうことは多いので、極限まで削ります。
|
||||||
「など」「いろいろ」「といった」「〇〇することができます」は使いがちですので特に気をつけましょう。
|
「など」「いろいろ」「といった」「〇〇することができます」は使いがちですので特に気をつけましょう。
|
||||||
|
|
||||||
@ -125,6 +160,7 @@ Wiki 全体で「ですます」の形で統一します。
|
|||||||
|
|
||||||
|
|
||||||
### カッコは基本的に使わない
|
### カッコは基本的に使わない
|
||||||
|
|
||||||
どうしても必要な場合は、名詞の別名や補足といった1〜2単語で済む体言を入れるだけにします。
|
どうしても必要な場合は、名詞の別名や補足といった1〜2単語で済む体言を入れるだけにします。
|
||||||
|
|
||||||
:x: 悪い例: Linux マシン(Ubuntu か Debian が入っていることが望ましい)を用意します。
|
:x: 悪い例: Linux マシン(Ubuntu か Debian が入っていることが望ましい)を用意します。
|
||||||
@ -133,34 +169,40 @@ Wiki 全体で「ですます」の形で統一します。
|
|||||||
|
|
||||||
|
|
||||||
### 箇条書きには句読点を入れない
|
### 箇条書きには句読点を入れない
|
||||||
|
|
||||||
箇条書きは段落を表現する道具ではありません。よって、内容が極力短くなるようにしつつ、句読点を置かないようにします。
|
箇条書きは段落を表現する道具ではありません。よって、内容が極力短くなるようにしつつ、句読点を置かないようにします。
|
||||||
|
|
||||||
|
|
||||||
### 感情を排除する
|
### 感情を排除する
|
||||||
|
|
||||||
極力スムーズに読める文章になるには、感情的表現を取り除く事が必須です。
|
極力スムーズに読める文章になるには、感情的表現を取り除く事が必須です。
|
||||||
文章は技術文書(レポート)のような無味乾燥なものにし、感情は Discord で共有しましょう。
|
文章は技術文書(レポート)のような無味乾燥なものにし、感情は Discord で共有しましょう。
|
||||||
|
|
||||||
|
|
||||||
### コードブロックや画像と文章の関わりを示す
|
### コードブロックや画像と文章の関わりを示す
|
||||||
|
|
||||||
「以下にコマンド例を示します」などのように、文章と以下に連なる要素を関連付けます。
|
「以下にコマンド例を示します」などのように、文章と以下に連なる要素を関連付けます。
|
||||||
|
|
||||||
|
|
||||||
## Markdown
|
## Markdown
|
||||||
|
|
||||||
Markdown はリッチなレンダリングがなくとも読めるシンタックスが特徴です。これを念頭に置いて、以下のルールに従ってください。
|
Markdown はリッチなレンダリングがなくとも読めるシンタックスが特徴です。これを念頭に置いて、以下のルールに従ってください。
|
||||||
|
|
||||||
|
|
||||||
### 必ずプレビューして確認する
|
### 必ずプレビューして確認する
|
||||||
|
|
||||||
ブラウザで文書を編集すると、コミット前に文書を HTML にレンダーするプレビューが利用可能です。ミスがないか確認してからコミットしましょう。
|
ブラウザで文書を編集すると、コミット前に文書を HTML にレンダーするプレビューが利用可能です。ミスがないか確認してからコミットしましょう。
|
||||||
|
|
||||||
ローカルのコンソールやエディタで書く場合も、Markdown をプレビューできる環境を用意して確認してからコミットしましょう。
|
ローカルのコンソールやエディタで書く場合も、Markdown をプレビューできる環境を用意して確認してからコミットしましょう。
|
||||||
|
|
||||||
|
|
||||||
### 改行コードは LF に統一する
|
### 改行コードは LF に統一する
|
||||||
|
|
||||||
Windows で特に気をつけましょう。Git は[コミット時に改行コードを LF のみに強制](https://qiita.com/uggds/items/00a1974ec4f115616580)できます。
|
Windows で特に気をつけましょう。Git は[コミット時に改行コードを LF のみに強制](https://qiita.com/uggds/items/00a1974ec4f115616580)できます。
|
||||||
|
|
||||||
`git config` で
|
`git config` で
|
||||||
|
|
||||||
```
|
```sh
|
||||||
git config --global core.autocrlf input
|
git config --global core.autocrlf input
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -168,6 +210,7 @@ git config --global core.autocrlf input
|
|||||||
|
|
||||||
|
|
||||||
### 適切な空行を入れる
|
### 適切な空行を入れる
|
||||||
|
|
||||||
以下の箇所には1行空行を入れます。
|
以下の箇所には1行空行を入れます。
|
||||||
|
|
||||||
- 段落と段落の間
|
- 段落と段落の間
|
||||||
@ -185,6 +228,7 @@ git config --global core.autocrlf input
|
|||||||
|
|
||||||
|
|
||||||
### 適切な空白を入れる
|
### 適切な空白を入れる
|
||||||
|
|
||||||
プレーンテキスト以外の要素の前後に適切な空白がないと表示がおかしくなるケースがあります。この文書は GitHub での表示に限られるため空白がなくても大丈夫ですが、エディタでのシンタックスハイライトが上手くいかなくなることがありますので気をつけましょう。
|
プレーンテキスト以外の要素の前後に適切な空白がないと表示がおかしくなるケースがあります。この文書は GitHub での表示に限られるため空白がなくても大丈夫ですが、エディタでのシンタックスハイライトが上手くいかなくなることがありますので気をつけましょう。
|
||||||
|
|
||||||
:x: 悪い例1: `1.あいうえお`
|
:x: 悪い例1: `1.あいうえお`
|
||||||
@ -197,11 +241,12 @@ git config --global core.autocrlf input
|
|||||||
|
|
||||||
|
|
||||||
### コードスパンとコードブロックを使い分ける
|
### コードスパンとコードブロックを使い分ける
|
||||||
|
|
||||||
コードスパンとは、`` `ident` ``のように行の中に等幅で文字を入れるスパン要素を指します。
|
コードスパンとは、`` `ident` ``のように行の中に等幅で文字を入れるスパン要素を指します。
|
||||||
|
|
||||||
コードブロックとは
|
コードブロックとは
|
||||||
|
|
||||||
```
|
```sh
|
||||||
echo foo
|
echo foo
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -219,6 +264,7 @@ ls -l
|
|||||||
|
|
||||||
|
|
||||||
### 明示的改行はバックスラッシュで行う
|
### 明示的改行はバックスラッシュで行う
|
||||||
|
|
||||||
この節でいう明示的改行とは Hard line breaks のことで、空行による段落区切りや単一の LF による Soft line break ではなく確実に改行を入れることを指します。必要でない限りは使わないことが望ましいです。
|
この節でいう明示的改行とは Hard line breaks のことで、空行による段落区切りや単一の LF による Soft line break ではなく確実に改行を入れることを指します。必要でない限りは使わないことが望ましいです。
|
||||||
|
|
||||||
明示的な改行の入れ方には行末にスペース2つを入れる方法とバックスラッシュを入れる方法がありまず。前者は通常不可視な上に意味合いがわかりづらいため、バックスラッシュを使用します。
|
明示的な改行の入れ方には行末にスペース2つを入れる方法とバックスラッシュを入れる方法がありまず。前者は通常不可視な上に意味合いがわかりづらいため、バックスラッシュを使用します。
|
||||||
|
Loading…
Reference in New Issue
Block a user