mirror of
https://github.com/brain-hackers/wiki.brainux.org
synced 2024-12-22 12:10:06 +09:00
Update How To Edit
This commit is contained in:
Takumi Sueda
parent
1718bd57f5
commit
95ce4d89c4
@ -58,24 +58,53 @@ Configuration file: /Users/takumi/dev/brain/wiki.brainux.org/_config.yml
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
# 各種操作
|
||||
|
||||
|
||||
## 1. a. ページを追加・削除する
|
||||
|
||||
- 新たにブランチを作成する
|
||||
- 後で Pull Request として提出するため、`master` ブランチには直接コミットしないでください
|
||||
- `_posts` ディレクトリにある他のファイルを参考にして md ファイルを追加します
|
||||
- 例: `2038-1-19-doomsday.md`
|
||||
- 記事内容を記述します
|
||||
- ひととおり追加と削除が終わったら `pull -r`, commit, push します
|
||||
- 新たにブランチを作成する
|
||||
- 後で Pull Request として提出するため、`master` ブランチには直接コミットしないでください
|
||||
- `_posts` ディレクトリにある他のファイルを参考にして md ファイルを追加します
|
||||
- 例: `2038-1-19-doomsday.md`
|
||||
- 記事内容を記述します
|
||||
- ひととおり追加と削除が終わったら `pull -r`, commit, push します
|
||||
|
||||
|
||||
## 1. b. ページを編集する
|
||||
|
||||
- 記事内容を記述します
|
||||
- ひととおり編集が終わったら `pull -r`, commit, push します
|
||||
- 記事内容を記述します
|
||||
- ひととおり編集が終わったら `pull -r`, commit, push します
|
||||
|
||||
|
||||
## 2. 変更を提出する・レビューを受ける・マージしてもらう
|
||||
@ -85,8 +114,8 @@ Configuration file: /Users/takumi/dev/brain/wiki.brainux.org/_config.yml
|
||||
|
||||
2021年12月現在、編集権限のあるメンバーは以下の通りです。
|
||||
|
||||
- @puhitaku
|
||||
- @tka3320
|
||||
- @puhitaku
|
||||
- @tka3320
|
||||
|
||||
注意！GitHub の Brain Hackers organization のメンバーでない人はレビューを依頼できないので、
|
||||
Discord にてメンバー追加依頼をしてメンバになってから Pull Request を提出しましょう。
|
||||
@ -96,26 +125,32 @@ Discord にてメンバー追加依頼をしてメンバになってから Pull
|
||||
|
||||
Wiki のページを生成している Jekyll は、md ファイルの名前から記事の日付や URL を生成します。以下のすべての条件を満たすようにしましょう。
|
||||
|
||||
- `YYYY-MM-DD-{英字とハイフンでできたタイトル}.md` の形式にする
|
||||
- URL が冗長になるので日本語は使わない
|
||||
- `YYYY-MM-DD-{英字とハイフンでできたタイトル}.md` の形式にする
|
||||
- URL が冗長になるので日本語は使わない
|
||||
|
||||
|
||||
# 記述ルール
|
||||
|
||||
Wiki の体裁について以下にルールを列挙します。コミットの前にこれらに従っているかチェックしてください。Textlint はまだありません。
|
||||
|
||||
|
||||
## 文体
|
||||
|
||||
基本的には、技術文書のルールと同一です。
|
||||
|
||||
|
||||
### 「ですます」と「だ・である」は統一する
|
||||
|
||||
Wiki 全体で「ですます」の形で統一します。
|
||||
|
||||
|
||||
### 依頼する時はできるだけ「します」で締める
|
||||
|
||||
「〇〇してください」は長いので、「します」で極力統一します。不自然に映る場合は「してください」や「しましょう」を使っても OK です。この文書でも実際にどちらも使用しています。
|
||||
|
||||
|
||||
### 繰り返しや冗長な表現をなくす
|
||||
|
||||
冗長な表現を組み込んでしまうことは多いので、極限まで削ります。
|
||||
「など」「いろいろ」「といった」「〇〇することができます」は使いがちですので特に気をつけましょう。
|
||||
|
||||
@ -125,6 +160,7 @@ Wiki 全体で「ですます」の形で統一します。
|
||||
|
||||
|
||||
### カッコは基本的に使わない
|
||||
|
||||
どうしても必要な場合は、名詞の別名や補足といった1〜2単語で済む体言を入れるだけにします。
|
||||
|
||||
:x: 悪い例: Linux マシン（Ubuntu か Debian が入っていることが望ましい）を用意します。
|
||||
@ -133,34 +169,40 @@ Wiki 全体で「ですます」の形で統一します。
|
||||
|
||||
|
||||
### 箇条書きには句読点を入れない
|
||||
|
||||
箇条書きは段落を表現する道具ではありません。よって、内容が極力短くなるようにしつつ、句読点を置かないようにします。
|
||||
|
||||
|
||||
### 感情を排除する
|
||||
|
||||
極力スムーズに読める文章になるには、感情的表現を取り除く事が必須です。
|
||||
文章は技術文書（レポート）のような無味乾燥なものにし、感情は Discord で共有しましょう。
|
||||
|
||||
|
||||
### コードブロックや画像と文章の関わりを示す
|
||||
|
||||
「以下にコマンド例を示します」などのように、文章と以下に連なる要素を関連付けます。
|
||||
|
||||
|
||||
## Markdown
|
||||
|
||||
Markdown はリッチなレンダリングがなくとも読めるシンタックスが特徴です。これを念頭に置いて、以下のルールに従ってください。
|
||||
|
||||
|
||||
### 必ずプレビューして確認する
|
||||
|
||||
ブラウザで文書を編集すると、コミット前に文書を HTML にレンダーするプレビューが利用可能です。ミスがないか確認してからコミットしましょう。
|
||||
|
||||
ローカルのコンソールやエディタで書く場合も、Markdown をプレビューできる環境を用意して確認してからコミットしましょう。
|
||||
|
||||
|
||||
### 改行コードは LF に統一する
|
||||
|
||||
Windows で特に気をつけましょう。Git は[コミット時に改行コードを LF のみに強制](https://qiita.com/uggds/items/00a1974ec4f115616580)できます。
|
||||
|
||||
`git config` で
|
||||
|
||||
```
|
||||
```sh
|
||||
git config --global core.autocrlf input
|
||||
```
|
||||
|
||||
@ -168,23 +210,25 @@ git config --global core.autocrlf input
|
||||
|
||||
|
||||
### 適切な空行を入れる
|
||||
|
||||
以下の箇所には1行空行を入れます。
|
||||
|
||||
- 段落と段落の間
|
||||
- プレーンテキストとプレーンテキスト以外の要素の間
|
||||
- 節タイトル
|
||||
- 箇条書き
|
||||
- テーブル
|
||||
- 図
|
||||
- コードブロック
|
||||
- 引用
|
||||
- 段落と段落の間
|
||||
- プレーンテキストとプレーンテキスト以外の要素の間
|
||||
- 節タイトル
|
||||
- 箇条書き
|
||||
- テーブル
|
||||
- 図
|
||||
- コードブロック
|
||||
- 引用
|
||||
|
||||
以下の箇所には2行空行を入れます。
|
||||
|
||||
- 節と節の間
|
||||
- 節と節の間
|
||||
|
||||
|
||||
### 適切な空白を入れる
|
||||
|
||||
プレーンテキスト以外の要素の前後に適切な空白がないと表示がおかしくなるケースがあります。この文書は GitHub での表示に限られるため空白がなくても大丈夫ですが、エディタでのシンタックスハイライトが上手くいかなくなることがありますので気をつけましょう。
|
||||
|
||||
:x: 悪い例1: `1.あいうえお`
|
||||
@ -197,11 +241,12 @@ git config --global core.autocrlf input
|
||||
|
||||
|
||||
### コードスパンとコードブロックを使い分ける
|
||||
|
||||
コードスパンとは、`` `ident` ``のように行の中に等幅で文字を入れるスパン要素を指します。
|
||||
|
||||
コードブロックとは
|
||||
|
||||
```
|
||||
```sh
|
||||
echo foo
|
||||
```
|
||||
|
||||
@ -219,6 +264,7 @@ ls -l
|
||||
|
||||
|
||||
### 明示的改行はバックスラッシュで行う
|
||||
|
||||
この節でいう明示的改行とは Hard line breaks のことで、空行による段落区切りや単一の LF による Soft line break ではなく確実に改行を入れることを指します。必要でない限りは使わないことが望ましいです。
|
||||
|
||||
明示的な改行の入れ方には行末にスペース2つを入れる方法とバックスラッシュを入れる方法がありまず。前者は通常不可視な上に意味合いがわかりづらいため、バックスラッシュを使用します。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user