STGYの投稿の書式
この記事では、STGYに投稿する記事の書式について説明します。
基本はプレーンテキスト
STGYに投稿される各記事はMarkdown形式で表現されます。特別な記法を使わない限り、Markdownはプレーンテキストと同じ感覚で書けます。普通に文章を書けばそれが表示されます。単一の改行は段落内の改行とみなされ、連続した改行は段落の区切りとみなされます。典型的な例は以下のようになります。
今日の天気予報： 晴れときどき曇り、ところにより雨 まったく当てにならない天気予報を横目に、私は家を出た。 #天気予報, #ポエム
段落とヘッダ
Markdownは標準規格ではないので、変種が多数あります。ここでの実装もその変種の一つです。地の文の中の単一の改行を改行を無視する派閥と改行として扱う派閥があるのですが、ここでは単一の改行は段落内の改行（HTMLの<br/>）として扱われます。段落はHTMLの<p>で区切られます。結果として、単一改行と連続改行の行間は異なることになります。
ヘッダ（表題）も書けます。ヘッダレベル1は「# 」、ヘッダレベル2は「## 」、ヘッダレベル3は「### 」を行頭に置きます。「#」の後ろには必ず空白が必要です。レベル6まであります。
# ヘッダレベル1 ## ヘッダレベル2 ### ヘッダレベル3
まとまりのある複数の文を段落にまとめ、まとまりのある複数の段落をセクション（節）などにまとめたものを構造化文書と言います。読みやすい構造化文書を書くには、以下の原則に基づくと良いでしょう。
- 記事の冒頭にヘッダレベル1で記事の題名を付ける。
- 内容が強く関連する文を段落にまとめて書く。
- 段落をセクションに分類し、各セクションの冒頭にヘッダレベル2で題名を付ける。
記事が長くなってセクションが増えた場合、記事の冒頭付近に目次（table of contents）を置くと良いでしょう。目次を挿入したい場所に以下の行を書きます。
<!TOC!>
タグ
記事の末尾にある「#」で始まる行は、タグの定義として扱われます。タグの分離はMarkdownとしての解釈をする前に行われます。複数のタグを指定する場合、カンマで区切ります。タグはリンクとして描写され、それをクリックすると、同じタグを持つ投稿の検索結果に遷移します。関連する投稿に同じタグをつけておくと、自分が後で読み返す際に便利です。他のユーザと同じタグを使えば、同じ話題を共有していることが示せます。
通常のタグとは別に、特殊機能のあるタグもあります。「#[nolikes]]」という特殊タグを付けると、その投稿へのイイネが無効化されます。「#[noreplies]」という特殊タグを付けると、その投稿への返信が無効化されます。投稿時のプレビュー画面で、タグがきちんと設定されているかは確認できます。
「#[locale=en]」「#[locale=en-US]」のように、BCP47のロケール名を書くと、記事のロケール（＝言語と地域）が指定できます。未指定の場合、ユーザ設定のロケールが記事につけられます。言語指定は検索エンジンやスクリーンリーダなどが言語を判定する際に使われます。フォントの選択にも使われます。
- en : 一般英語（en-GBはイギリス英語、en-USはアメリカ英語）
- ja : 日本語（ja-JPとしてもOK）
- zh : 中国語（zh-CNは本土中国語、zh-TWは台湾中国語）
- ko : 朝鮮語（ko-KRは韓国語、ko-KPは北朝鮮語）
- es : スペイン語（es-ESは本土スペイン語、es-MXはメキシコスペイン語）
- pt : ポルトガル語（pt-PTは本土ポルトガル語、pt-BRはブラジルポルトガル語）
- fr : フランス語（fr-FRとしてもOK）
- ru : ロシア語（ru-RUとしてもOK）
- ar : アラビア語（ar-EZはエジプトアラビア語、ar-SAはサウジアラビア語）
- 独自ロケール : 「x-ja-osaka」のように「x」の後に「-」で区切った英数字を並べる
リスト
リストも書けます。「- 」で始まる行はリストの項目になります。「-」の後ろには必ず空白が必要です。「-」の前に2つのスペースを置くと、リストのレベルを深くできます。
- リストレベル1、項目1
- リストレベル1、項目2
- リストレベル2、項目1
- リストレベル2、項目2
- リストレベル3、項目1
- リストレベル3、項目2
- リストレベル1、項目3- リストレベル1、項目1
- リストレベル1、項目2
- リストレベル2、項目1
- リストレベル2、項目2
- リストレベル3、項目1
- リストレベル3、項目2
- リストレベル1、項目3
「-+ 」で始まる行は番号付きリストの項目になります。「-: 」で始まる行はマーク無しリストの項目になります。
-+ 織田信長 -+ 豊臣秀吉 -+ 徳川家康 -: 面堂終太郎 -: 九能帯刀 -: 三鷹瞬
- 織田信長
- 豊臣秀吉
- 徳川家康
- 面堂終太郎
- 九能帯刀
- 三鷹瞬
「-@author 」などで始まる行は、投稿のメタデータを意味します。「author」の部分は任意の英数字に置き換えられます。値は通常のリストと同様にスペースの後に書きます。典型的には、文書の題名となるヘッダの次に書いて、右詰めで表示されます。「author」と「date」は、外部公開時の著者名と日付のメタデータを上書きする効果があります。
-@author 芥川龍之介 -@date 1915-11-15
- 芥川龍之介
- 1915-11-15
引用
引用も書けます。「> 」で始まる行は引用になります。「>」の後ろには必ず空白が必要です。連続する引用の行は一つの引用の段落になります。
> あと何を話せただろう、 > 離れてしまうその前に。
あと何を話せただろう、
離れてしまうその前に。
テーブル
「|」で囲んだ連続した行は表になります。「|」で列を区切ります。「=」で囲まれたセルはヘッダになります。「{colspan=2}」「{rowspan=2}」を左端に置くと列結合と行結合ができます。「>>」「><」を左端に置くと右寄せと中寄せができます。
|=名前=|=説明=|={colspan=2}><人口=|
|東京都|都庁所在地は新宿区。日本の首都。|>>1,426万人|{rowspan=2}都会|
|神奈川県|県庁所在地は横浜市。大阪府より人口が多い。|>>921万人|
|千葉県|県庁所在地は千葉市。ピーナツで有名。|>>628人|{rowspan=2}田舎|
|埼玉県|県庁所在地はさいたま市。特徴は特にない。|>>770人|| 名前 | 説明 | 人口 | |
|---|---|---|---|
| 東京都 | 都庁所在地は新宿区。日本の首都。 | 1,426万人 | 都会 |
| 神奈川県 | 県庁所在地は横浜市。大阪府より人口が多い。 | 921万人 | |
| 千葉県 | 県庁所在地は千葉市。ピーナツで有名。 | 628人 | 田舎 |
| 埼玉県 | 県庁所在地はさいたま市。特徴は特にない。 | 770人 | |
ハイパーリンク
ハイパーリンクを表現するには、[ と ] でアンカー文字列を挟んでから、直後に ( と ) で挟んでURLを書きます。STGY内のページにも、外部サイトへも、リンクを貼ることができます。
私は[ChatGPT](https://ja.wikipedia.org/wiki/ChatGPT)を使っています。 Googleで[ChatGPT](https://www.google.com/?q=ChatGPT)を検索できます。 使い方については[ヘルプ記事](/posts/0002000000000002)を見てください。 詳細については[管理者ユーザ](/users/0001000000000001)に聞いて下さい。 画像の管理は[画像管理ページ](/images)で行います。
私はChatGPTを使っています。
GoogleでChatGPTを検索できます。
使い方についてはヘルプ記事を見てください。
詳細については管理者ユーザに聞いて下さい。
画像の管理は画像管理ページで行います。
本文の中に現れる http:// や https:// で始まる文字列は、自動的にそのURLへのハイパーリンクになります。
- 詳細はこちら: https://kantei.go.jp/
- 詳細はこちら: https://kantei.go.jp/
ハイパーリンクのURL部分には特殊記法も使えます。wiki-en や wiki-ja とすると、アンカー文字列を表題とするWikipedia英語版や日本語版の記事へのリンクになります。google とすると、アンカー文字列を検索語とするGoogle検索結果へのリンクになります。
私は[ChatGPT](wiki-en)を使っています。 私は[ChatGPT](wiki-ja)を使っています。 Googleで[ChatGPT](google)を検索すると出てきます。
私はChatGPTを使っています。
私はChatGPTを使っています。
GoogleでChatGPTを検索すると出てきます。
その他の装飾とルビと数式
文字の装飾もできます。装飾は地の文だけではなく、ヘッダやリストや表の中でも使えます。
**太字**、::斜体::、__下線__、~~打消~~、``コード``、@@マーク@@、%%細目%%、{{漢字|ルビ}}太字、斜体、下線、打消、コード、マーク、細目、
複雑な数式も書けます。$$ で囲んだ区間は、LaTeXの数式として処理され、SVG画像として表示されます。\frac、\sum、\lim、\sqrt などのマクロも使えます。
$$E = mc^2$$
$$\int_0^{\sqrt{N}} x^2 \, dx = \lim_{n \to \infty} \sum_{i=1}^{n} f\left( \frac{i \cdot x}{n} \right) \cdot \left( \frac{x}{n} \right)$$E = mc^2\int_0^{\sqrt{N}} x^2 \, dx = \lim_{n \to \infty} \sum_{i=1}^{n} f\left( \frac{i \cdot x}{n} \right) \cdot \left( \frac{x}{n} \right)
整形済みテキスト
HTMLの<pre>のように空白や改行をそのまま表現したい場合には、その部分を「```」だけの行と「```」だけの行で囲みます。整形済みテキストの中で「```」を書きたい場合には、「````」で囲みます。
```
これは ペンです。
これも ペン です。
``` これは ペンです。
これも ペン です。整形済みテキストには、シンタックスハイライト機能があります。各種のプログラミング言語やデータ書式の文法に応じて自動的に文字色を変える機能です。シンタックスハイライト機能を有効にするには、開始の区切り文字を「```json」などのようにして、言語名を指定します。「c」「cpp」「javascript」「typescript」「python」「ruby」「sql」「json」「yaml」「html」などがサポートされています。
```cpp
#include <iostream>
int main(int argc, char** argv) {
std::cout << "Hello, World" << std::endl;
return 0;
}
```#include <iostream>
int main(int argc, char** argv) {
std::cout << "Hello, World" << std::endl;
return 0;
}通常、整形済みテキストは固定幅フォントで枠内に表示されます。プログラミング言語ではなく、日本語や英語などの自然言語で詩などを書きたい場合には、言語として「natural」を指定します。すると、通常の段落と同様に可変幅フォントかつ枠なしで表示されます。
```natural
Fury said to a mouse,
That he met in the house,
"Let us both go to law: I will prosecute you."
``` Fury said to a mouse,
That he met in the house,
"Let us both go to law: I will prosecute you."整形済みテキストの言語名の部分に「:xsmall」「:small」「:large」「:xlarge」「:bold」「:italic」の修飾子を書くことができます。「json:small」とか「natural:large:italic」のように言語名と組み合わせて使うこともできます。
```:xsmall o sweet spontaneous earth ``` ```:small o sweet spontaneous earth ``` ```:large o sweet spontaneous earth ``` ```:xlarge o sweet spontaneous earth ``` ```:bold o sweet spontaneous earth ``` ```:italic o sweet spontaneous earth ```
o sweet spontaneous earth
o sweet spontaneous earth
o sweet spontaneous earth
o sweet spontaneous earth
o sweet spontaneous earth
o sweet spontaneous earth
罫線
罫線を引きたい時は、ハイフンを4つ繋げた「----」だけの行を書きます。5つ繋げた「-----」にするとより目立つ罫線になります。3つ繋げた「---」は見えない罫線で、行間を少し開けたり画像の回り込みを解除したりするのに使います。
--- ---- -----
投稿一覧画面で各投稿のスニペット（抜粋情報）は冒頭200文字かつ10行の範囲で生成されます。スニペットの生成時に罫線があると、その場所でスニペットは強制的に打ち切られます。投稿一覧画面には表示したくない内容が文書の冒頭近くにある場合、その前にスニペットを置くことで隠せます。意外な情報を投稿詳細画面を開くまで「勿体ぶる」のに便利です。
画像
記事内に画像を埋め込むには、 記法を用います。キャプションは空文字列でも構いません。投稿メニューの画像ツールを使うと、画像のアップロードと埋め込み記法の執筆が一度でできます。
セキュリティ上の理由で、埋め込める画像のURLには制限があります。画像管理機能でアップロードした /images/ で始まるパスか、STGYに既存の/data/ で始まるパスのみです。
記事本文の読みやすさのために画像は小さめに表示されますが、その画像を押すと拡大表示されます。
最初から画像を大きく表示したい場合には、{size=large} や {size=xlarge} マクロを指定できます。
{size=large}
{size=xlarge}画像を小さく表示したい場合には、{size=small} や {size=xsmall} マクロを指定できます。
{size=small}
{size=xsmall}画像をフローティングさせて文字を回り込みさせたい場合、{float=left} や {size=right}マクロを指定できます。回り込みを解除したい場合、「---」の見えない罫線を引くと良いでしょう。
{float=left,size=small}
渚のハイカラ人魚
キュートなヒップにズキンドキン
渚のハイカラ人魚
まぶしい素足にズキンドキン
---
{float=right,size=small}
I will follow you
あなたに追いてゆきたい
I will follow you
ちょっぴり気が弱いけど
---渚のハイカラ人魚
キュートなヒップにズキンドキン
渚のハイカラ人魚
まぶしい素足にズキンドキン
I will follow you
あなたに追いてゆきたい
I will follow you
ちょっぴり気が弱いけど
画像を横並びで表示したい場合には、{grid} マクロを使います。{grid} がついた画像が連続すると、それを1行にまとめます。最大5列までサポートしています。ひとつだけでグリッドにすると、中寄せにする効果があります。
{grid}
{grid}
{grid}
{grid}
{grid}
{grid}
{grid}
{grid}
{grid}
{grid}
{grid}
{grid}
{grid}
{grid}
{grid}投稿詳細画面には記事内の全ての画像が表示されますが、投稿一覧画像にはひとつの代表画像のサムネイルしか表示されません。デフォルトでは、最初の画像が代表画像になります。最初の画像以外を代表画像にしたい場合には、その画像に {featured} マクロを付与します。あるいは、代表画像にしたくない画像に {no-featured} をつけても良いでしょう。全ての画像に {no-featured} をつければ、代表画像は表示されなくなります。
コメント
「<[」と「]>」で挟んだ部分はコメントになります。ここで言うコメントとは、Markdown内には記述があるのに、読者向けには表示されない文字列のことです。コメントは文字が書ける任意の場所に置くことができます。コメントだけの行は、行ごと無視されるので、リストやテーブルの途中にコメント行を挟むこともできます。
- 東京都の人口は約1400万人<[要確認]>で、日本一である。 - 大阪市の実行より横浜市の人口の方が多い。 <[言い方に注意]> - 埼玉は田舎で、何もない。
- 東京都の人口は約1400万人で、日本一である。
- 大阪市の実行より横浜市の人口の方が多い。
- 北関東は田舎で、何もない。
Markdownの解釈はクライアント側で行われるので、コメントも含めた全データがクライアントに送られます。よって、秘匿情報をコメントに含めないでください。
Next: STGYのアーキテクチャ