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人 | |
2行目に「|---|---|」などの区切りを置くこともできます。そうすると1行目のセルは全てヘッダになります。中身を「:---」「---:」「:---:」などにすることで、それぞれ左寄せ、右寄せ、中央寄せを継続行に指定することができます。
ハイパーリンク
ハイパーリンクを表現するには、[ と ] でアンカー文字列を挟んでから、直後に ( と ) で挟んでURLを書きます。STGY内のページにも、外部サイトへも、リンクを貼ることができます。
私は[ChatGPT](https://ja.wikipedia.org/wiki/ChatGPT)を使っています。 Googleで[ChatGPT](https://www.google.com/?q=ChatGPT)を検索できます。 使い方については[ヘルプ記事](/posts/0000000000020002)を見てください。 詳細については[管理者ユーザ](/users/0000000000000001)に聞いて下さい。 画像の管理は[画像管理ページ](/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」の修飾子を書くことができます。「:lines=N」でNに表示行数を指定できます。「json:small」とか「natural:large:italic:lines=10」のように言語名と組み合わせて使うこともできます。
```: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 ``` ```:small:lines=3 one two three four five ```
o sweet spontaneous earth
o sweet spontaneous earth
o sweet spontaneous earth
o sweet spontaneous earth
o sweet spontaneous earth
o sweet spontaneous earth
one two three four five
罫線
罫線を引きたい時は、ハイフンを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} をつければ、代表画像は表示されなくなります。
地図
記事内に地図を埋め込むには、@[キャプション](URL) 記法を用います。画像の埋め込み記法の先頭の ! を @ に変えた形です。キャプションは空文字列でも構いません。
@[サイクリング記録](/data/demo-toumi.trj)
URLには、アップロード済みのFITファイルやTrackJSONファイルを指定できます。FITファイルはGarmin社のサイクルコンピュータやその他のアクティビティトラッカーが用いる、GPSログや経路情報や各種センサーの測定記録を表すためのデータ形式です。TrackJSONは、GPSログや経路情報を記録する標準形式であるGeoJSONに各種センサーの測定記録を表すための拡張を施したデータ形式です。拡張子が .trj のファイルはそのままのTrackJSON、.trjgz のファイルはgzip圧縮されたTrackJSONです。アップロードされたFIT形式またはTrackJSON形式のデータからは、対応する軽量化されたTrackJSONデータが自動生成され、それが表示に使われます。
画像と同様に、表示用のオプションを {key=value,...} の形式で後ろに付けることもできます。
@[サイクリング記録](/data/demo-toumi.trj){float=right,size=small,graph=false}緑の中を走り抜けてく真紅なポルシェ
ひとり旅なの私 気ままにハンドル切るの
交差点では隣りの車がミラーこすったと
怒鳴っているから私もついつい大声になる
背景地図を指定したい場合には、base オプションを指定できます。たとえば、OpenStreetMapを使いたい場合には以下のように書きます。
@[サイクリング記録](/data/demo-toumi.trj){base=osm}オプションには以下のものがあります。
- base : 背景地図を指定します。値としてpale（GSI白地図）、std（GSI標準地図）、photo（GSI写真地図）、cycle（OSMサイクリング地図）、osm（OSM標準地図）、topo（OSM地形地図）を取ります。
- graph : 測定値グラフの描画指定です。デフォルトはtrueで、速度等がデータにあればグラフを表示します。falseにすると非表示になります。
- overlay : 測定値オーバーレイの描画指定です。デフォルトはtrueで、速度等がデータにあればオーバーレイを表示します。falseにすると非表示になります。
- controls : 地図切り替えや拡大縮小の制御機能の表示指定です。デフォルトはtrueで、制御機能を表示します。falseにすると非表示になります。
- float : 地図の左右への回り込みを指定します。値としてleftまたはrightを取ります。
- size : 地図の大きさを指定します。値として xsmall、small、medium、large、xlargeを取ります。
- grid : 連続して記述した複数の地図をグリッド状に並べる指定です。値は不要です。
- lthr : 心拍数のゾーニングに使うLTHRをワット単位で指定する。
- ftp : パワーのゾーニングに使うFTPをBPM単位で指定する。
サイクリングコンピュータで作ったFITファイルを使って地図を描画する場合、地図の下に標高や速度やケイデンスなどのグラフが表示されます。それだけではなく、地図の左上にあるレイヤーアイコンのメニューの中に「Metadata」と「Analysis」という項目が現れます。「Metadata」を選ぶと、各種の統計値が見られます。pedaling statsが特に有用で、停止区間と空走区間を除いたペダリングしている区間に絞った統計値を示します。「Aanlysis」を選ぶと、速度とケイデンスと心拍数とパワーのヒストグラムが見られます。さらに、オプションでLTHR（乳酸閾値心拍数）やFTP（機能的体力閾値）を指定すると、フリール式の心拍数ゾーニングやコーガン式のパワーゾーニングのヒストグラムが追加されます。
経路ファイルを使わずに、記事の中に直接地図の中心位置やピンを書くこともできます。その場合は、URLの代わりに map:// で始まる記法を使います。
@[東京都世田谷区赤堤](map://139.6444794,35.6595519,15)
map:// の直後には、地図の中心の経度、緯度、ズームレベルをカンマ区切りで書きます。順番は「経度、緯度、ズーム」です。緯度と経度の順番ではないので注意してください。経度と緯度の表記は、S/N/E/Wの方角を接尾させる方式と、西経や南緯を負数で示す方式の両方に対応しています。ズームレベルは省略でき、その場合は13になります。ズームレベル0は地球全体で、値を1増やす毎に倍率が2倍になります。
map://経度,緯度,ズーム
中心位置に加えて、任意の数のピンを立てることもできます。ピンは | で区切って追加します。各ピンは、経度と緯度を書いた後に、必要に応じてタイトル、説明文、リンクURL、画像URLを ; 区切りで書きます。ピンを複数指定する場合、| で区切ります。画像URLとして指定できるのは、自分でアップロードした画像の /images/ で始まるURLだけです。リンクURLと画像URLは空白で区切って複数個を指定することができます。
@[散歩メモ](map://139.6444794,35.6595519,15|139.6444772,35.6595498;パン屋;美味い;/data/logo-square.webp|139.6460,35.6600;公園;休憩に良い)
- パン屋美味い
- 公園休憩に良い
経路データを読み込んだ上で、そこにピンを加えることもできます。経路データのURLの後に | で区切ってピンの記法を並べます。記録した経路にメモや写真を貼り付けるのに便利です。
@[サイクリング記録](/data/demo-toumi.trj|138.29788,36.36151;謎の神社;財宝を埋めた)
map:// 記法は、人間が短い地図メモを手で書くための簡易記法です。複雑な経路情報を埋め込む用途には向いていません。サイクリングや登山などの経路を表示したい場合には、TrackJSONファイルをアップロードして、それを参照してください。map:// 記法の中では、カンマと縦棒は区切り文字として扱われます。そのため、タイトルや説明文の中にこれらの文字を含めることはできません。URLにこれらの文字が必要な場合には、URLエンコードされた形にしてください。形式が正しくない map:// のURLは、安全のため外部データとして読み込まれません。その場合、地図は正しく表示されません。
YouTube動画埋め込み
地図の埋め込みと同様に、@[キャプション](URL) 記法を使うと、Youtubeの動画を記事内に埋め込むことができます。キャプションは省略できます。画像や地図と同様に、{size=xxx} 形式のオプションでサイズを指定できます。
@[サイクリング記録](https://www.youtube.com/watch?v=BOF5PQ9Osc4)
YouTubeのURLとしては、以下のパターンのいずれを使っても構いません。www.youtube.comの代わりに、youtube.comやwww.youtube-nocookie.comなどの公式の別ドメインを使っても構いません。
https://www.youtube.com/watch?v=VIDEO_ID https://www.youtube.com/shorts/VIDEO_ID https://www.youtube.com/live/VIDEO_ID https://www.youtube.com/embed/VIDEO_ID https://www.youtube.com/v/VIDEO_ID https://youtu.be/VIDEO_ID
なお、動画データのSTGYへのアップロードには現在は対応していません。
リンクスニペット
STGY内の他の記事やSTGY外の一般サイトへのリンクを記事に埋め込む際には、リンクスニペットを使うと見やすくなります。リンク先の文書のタイトルや説明文を自動取得して記事内に表示する機能です。リンク先がOGP（Open Graph Protocol）のスニペットを配信している場合、そこに記述されたデータが利用されます。そうでない場合、HTMLのtitleやdescriptionや本文がスニペットの生成に使われます。リンクスニペットは、%[キャプション](URL) 記法で記述します。キャプションはタイトルを上書きするので通常はキャプションは空にします。URLは、外部サイトのリンク場合はhttps://で始まる絶対URLを用いて、STGY内のユーザや記事へのリンクの場合は /users/ や /posts/ で始まる相対URLを用います。
%[](https://www.strava.com/activities/19016462432) %[](/posts/0000000000020003)
コメント
「<[」と「]>」で挟んだ部分はコメントになります。ここで言うコメントとは、Markdown内には記述があるのに、読者向けには表示されない文字列のことです。コメントは文字が書ける任意の場所に置くことができます。コメントだけの行は、行ごと無視されるので、リストやテーブルの途中にコメント行を挟むこともできます。
- 東京都の人口は約1400万人<[要確認]>で、日本一である。 - 大阪市の実行より横浜市の人口の方が多い。 <[言い方に注意]> - 埼玉は田舎で、何もない。
- 東京都の人口は約1400万人で、日本一である。
- 大阪市の実行より横浜市の人口の方が多い。
- 北関東は田舎で、何もない。
Markdownの解釈はクライアント側で行われるので、コメントも含めた全データがクライアントに送られます。よって、秘匿情報をコメントに含めないでください。
Next: STGYのアーキテクチャ